Pre-release

This release is a pre-release and may not be stable for production use.

ConnectOnion

🚧 Private Beta - ConnectOnion is currently in private beta. Join our waitlist to get early access!

A simple Python framework for creating AI agents that can use tools and track their behavior.

✨ What's New

🎯 Function-Based Tools: Just write regular Python functions - no classes needed!
🎭 System Prompts: Define your agent's personality and role
🔄 Automatic Conversion: Functions become OpenAI-compatible tools automatically
📝 Smart Schema Generation: Type hints become function schemas

🚀 Quick Start

Installation

pip install -r requirements.txt

Basic Usage

import os  
from connectonion import Agent

# Set your OpenAI API key
os.environ["OPENAI_API_KEY"] = "your-api-key-here"

# 1. Define tools as simple functions
def search(query: str) -> str:
    """Search for information."""
    return f"Found information about {query}"

def calculate(expression: str) -> float:
    """Perform mathematical calculations."""
    return eval(expression)  # Use safely in production

# 2. Create an agent with tools and personality
agent = Agent(
    name="my_assistant",
    system_prompt="You are a helpful and friendly assistant.",
    tools=[search, calculate]
)

# 3. Use the agent
result = agent.run("What is 25 * 4?")
print(result)  # Agent will use the calculate function

result = agent.run("Search for Python tutorials") 
print(result)  # Agent will use the search function

# 4. View behavior history (automatic!)
print(agent.history.summary())

🔧 Core Concepts

Agent

The main class that orchestrates LLM calls and tool usage. Each agent:

Has a unique name for tracking purposes
Can be given a custom personality via system_prompt
Automatically converts functions to tools
Records all behavior to JSON files

Function-Based Tools

NEW: Just write regular Python functions! ConnectOnion automatically converts them to tools:

def my_tool(param: str, optional_param: int = 10) -> str:
    """This docstring becomes the tool description."""
    return f"Processed {param} with value {optional_param}"

# Use it directly - no wrapping needed!
agent = Agent("assistant", tools=[my_tool])

Key features:

Automatic Schema Generation: Type hints become OpenAI function schemas
Docstring Integration: First line becomes tool description
Parameter Handling: Supports required and optional parameters
Type Conversion: Handles different return types automatically

System Prompts

Define your agent's personality and behavior with flexible input options:

# 1. Direct string prompt
agent = Agent(
    name="helpful_tutor",
    system_prompt="You are an enthusiastic teacher who loves to educate.",
    tools=[my_tools]
)

# 2. Load from file (any text file, no extension restrictions)
agent = Agent(
    name="support_agent",
    system_prompt="prompts/customer_support.md"  # Automatically loads file content
)

# 3. Using Path object
from pathlib import Path
agent = Agent(
    name="coder",
    system_prompt=Path("prompts") / "senior_developer.txt"
)

# 4. None for default prompt
agent = Agent("basic_agent")  # Uses default: "You are a helpful assistant..."

Example prompt file (prompts/customer_support.md):

# Customer Support Agent

You are a senior customer support specialist with expertise in:
- Empathetic communication
- Problem-solving
- Technical troubleshooting

## Guidelines
- Always acknowledge the customer's concern first
- Look for root causes, not just symptoms
- Provide clear, actionable solutions

History

Automatic tracking of all agent behaviors including:

Tasks executed
Tools called with parameters and results
Agent responses and execution time
Persistent storage in ~/.connectonion/agents/{name}/behavior.json

🎯 Example Tools

You can still use the traditional Tool class approach, but the new functional approach is much simpler:

Traditional Tool Classes (Still Supported)

from connectonion.tools import Calculator, CurrentTime, ReadFile

agent = Agent("assistant", tools=[Calculator(), CurrentTime(), ReadFile()])

New Function-Based Approach (Recommended)

def calculate(expression: str) -> float:
    """Perform mathematical calculations."""
    return eval(expression)  # Use safely in production

def get_time(format: str = "%Y-%m-%d %H:%M:%S") -> str:
    """Get current date and time."""
    from datetime import datetime
    return datetime.now().strftime(format)

def read_file(filepath: str) -> str:
    """Read contents of a text file."""
    with open(filepath, 'r') as f:
        return f.read()

# Use them directly!
agent = Agent("assistant", tools=[calculate, get_time, read_file])

The function-based approach is simpler, more Pythonic, and easier to test!

🔨 Creating Custom Tools

from connectonion.tools import Tool

class WeatherTool(Tool):
    def __init__(self):
        super().__init__(
            name="weather",
            description="Get current weather for a city"
        )
    
    def run(self, city: str) -> str:
        # Your weather API logic here
        return f"Weather in {city}: Sunny, 22°C"
    
    def get_parameters_schema(self):
        return {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "Name of the city"
                }
            },
            "required": ["city"]
        }

# Use with agent
agent = Agent(name="weather_agent", tools=[WeatherTool()])

📁 Project Structure

connectonion/
├── connectonion/
│   ├── __init__.py     # Main exports
│   ├── agent.py        # Agent class
│   ├── tools.py        # Tool interface and built-ins
│   ├── llm.py          # LLM interface and OpenAI implementation
│   └── history.py      # Behavior tracking
├── examples/
│   └── basic_example.py
├── tests/
│   └── test_agent.py
└── requirements.txt

🧪 Running Tests

python -m pytest tests/

Or run individual test files:

python -m unittest tests.test_agent

📊 Behavior Tracking

All agent behaviors are automatically tracked and saved to:

~/.connectonion/agents/{agent_name}/behavior.json

Each record includes:

Timestamp
Task description
Tool calls with parameters and results
Final result
Execution duration

View behavior summary:

print(agent.history.summary())
# Agent: my_assistant
# Total tasks completed: 5
# Total tool calls: 8
# Total execution time: 12.34 seconds
# History file: ~/.connectonion/agents/my_assistant/behavior.json
# 
# Tool usage:
#   calculator: 5 calls
#   current_time: 3 calls

🔑 Configuration

OpenAI API Key

Set your API key via environment variable:

export OPENAI_API_KEY="your-api-key-here"

Or pass directly to agent:

agent = Agent(name="test", api_key="your-api-key-here")

Model Selection

agent = Agent(name="test", model="gpt-4")  # Default: gpt-3.5-turbo

🛠️ Advanced Usage

Multiple Tool Calls

Agents can chain multiple tool calls automatically:

result = agent.run(
    "Calculate 15 * 8, then tell me what time you did this calculation"
)
# Agent will use calculator first, then current_time tool

Custom LLM Providers

from connectonion.llm import LLM

class CustomLLM(LLM):
    def complete(self, messages, tools=None):
        # Your custom LLM implementation
        pass

agent = Agent(name="test", llm=CustomLLM())

🚧 Current Limitations (MVP)

This is an MVP version with intentional limitations:

Single LLM provider (OpenAI)
Synchronous execution only
JSON file storage only
Basic error handling
No multi-agent collaboration

🗺️ Future Roadmap

Multiple LLM provider support (Anthropic, Local models)
Async/await support
Database storage options
Advanced memory systems
Multi-agent collaboration
Web interface for behavior monitoring
Plugin system for tools

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

This is an MVP. For the full version roadmap:

Fork the repository
Create a feature branch
Add tests for new functionality
Submit a pull request

📞 Support

For issues and questions:

Create an issue on GitHub
Check the examples/ directory for usage patterns
Review the test files for implementation details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

connectonion-0.0.1b1-py3-none-any.whl (38.9 kB view details)

Uploaded Aug 7, 2025 Python 3

File details

Details for the file connectonion-0.0.1b1-py3-none-any.whl.

File metadata

Download URL: connectonion-0.0.1b1-py3-none-any.whl
Upload date: Aug 7, 2025
Size: 38.9 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.9.7

File hashes

Hashes for connectonion-0.0.1b1-py3-none-any.whl
Algorithm	Hash digest
SHA256	`11d50cecd97cba8b19876f3c96896d1fa0971bc864d2f7c8cf6cd3cfe4ce8ae3`
MD5	`beacae14842902ed80f67afdf3b209db`
BLAKE2b-256	`b8f79c6e22c3f7dbc5b6c63658775eb207f0ad1363ceb36d4e1b59abb719ff1f`