connectonion 0.6.2__py3-none-any.whl → 0.6.3__py3-none-any.whl

connectonion/docs/api.md

@@ -0,0 +1,457 @@
+# API Reference
+
+## Agent
+
+The main class for creating AI agents that can use tools.
+
+### Constructor
+
+```python
+Agent(
+    name: str,
+    llm: Optional[LLM] = None,
+    tools: Optional[List[Callable]] = None,
+    system_prompt: Union[str, Path, None] = None,
+    api_key: Optional[str] = None,
+    model: str = "co/gemini-2.5-pro"
+)
+```
+
+#### Parameters
+
+- **name** (`str`): Unique identifier for the agent
+- **llm** (`Optional[LLM]`): Custom LLM instance (defaults to OpenAILLM)
+- **tools** (`Optional[List[Callable]]`): List of functions the agent can use
+- **system_prompt** (`Union[str, Path, None]`): Agent's personality and behavior definition
+  - `str`: Can be either a direct prompt text or a file path (auto-detected)
+  - `Path`: Path object pointing to a prompt file
+  - `None`: Uses default prompt
+- **api_key** (`Optional[str]`): OpenAI API key (if not using custom LLM)
+- **model** (`str`): Model to use (default: "co/gemini-2.5-pro")
+  - Managed keys: `co/gemini-2.5-pro`, `co/gpt-4o-mini`, `co/claude-3-5-sonnet`
+  - Your own key: `gpt-4o-mini`, `claude-3-5-sonnet`, `gemini-1.5-pro`
+
+### System Prompt Options
+
+The `system_prompt` parameter accepts multiple input types:
+
+```python
+# 1. Direct string
+agent = Agent(name="bot", system_prompt="You are helpful")
+
+# 2. File path as string (auto-detected if file exists)
+agent = Agent(name="bot", system_prompt="prompts/assistant.md")
+
+# 3. Path object (must point to existing file)
+from pathlib import Path
+agent = Agent(name="bot", system_prompt=Path("prompts/assistant.txt"))
+
+# 4. None (uses default)
+agent = Agent(name="bot")  # Default: "You are a helpful assistant..."
+```
+
+**File Loading Rules:**
+- Any text file can be used (no extension restrictions)
+- Files must be valid UTF-8 encoded text
+- Empty files raise `ValueError`
+- Non-existent Path objects raise `FileNotFoundError`
+- Strings that don't exist as files are treated as literal prompts
+
+### Methods
+
+#### `input(prompt: str, max_iterations: Optional[int] = None) -> str`
+
+Provide input to the agent and get response.
+
+**Parameters:**
+- `prompt` - User input/task for the agent
+- `max_iterations` - Override agent's default max_iterations for this task only
+
+```python
+result = agent.input("Calculate 2 + 2")
+
+# Override iterations for complex tasks
+result = agent.input("Complex multi-step task", max_iterations=25)
+```
+
+#### `add_tool(tool: Callable) -> None`
+
+Add a new tool to the agent.
+
+```python
+def new_tool(param: str) -> str:
+    return f"Processed {param}"
+
+agent.add_tool(new_tool)
+```
+
+#### `remove_tool(tool_name: str) -> None`
+
+Remove a tool from the agent.
+
+```python
+agent.remove_tool("calculator")
+```
+
+#### `list_tools() -> List[str]`
+
+Get list of available tool names.
+
+```python
+tools = agent.list_tools()
+# ['calculator', 'search', 'get_time']
+```
+
+## Tools
+
+### Function-Based Tools
+
+Any Python function can be used as a tool:
+
+```python
+def my_tool(param: str, optional: int = 10) -> str:
+    """Tool description from docstring.
+
+    Args:
+        param: The main parameter.
+
+    Returns:
+        Formatted result.
+    """
+    return f"Result: {param} with {optional}"
+
+agent = Agent("bot", tools=[my_tool])
+```
+
+**How schemas are generated:**
+- `name` ← function name
+- `description` ← first paragraph of docstring (Args/Returns NOT included)
+- `parameters` ← from Python type hints
+- `required` ← parameters without default values
+
+**Everything is optional:**
+- No docstring? Description defaults to "Execute the {name} tool."
+- No type hints? Defaults to string type
+
+### Tool Conversion
+
+The `create_tool_from_function` utility converts functions to tools:
+
+```python
+from connectonion import create_tool_from_function
+
+def simple_function(x: int) -> int:
+    """Double a number."""
+    return x * 2
+
+tool = create_tool_from_function(simple_function)
+# tool now has: .name, .description, .run(), .to_function_schema()
+```
+
+## Logging
+
+Automatic activity logging for agents. Three output destinations:
+- **Console**: Rich-formatted terminal output
+- **Plain text**: `.co/logs/{name}.log`
+- **Session YAML**: `.co/evals/{name}_{timestamp}.yaml`
+
+### Configuration
+
+Control logging via `quiet` and `log` parameters:
+
+```python
+# Default: everything on (console + logs + sessions)
+agent = Agent("assistant")
+
+# Quiet mode: suppress console, keep sessions for eval
+agent = Agent("assistant", quiet=True)
+
+# Disable all file logging (console only)
+agent = Agent("assistant", log=False)
+
+# Custom log file path
+agent = Agent("assistant", log="my_logs/custom.log")
+```
+
+### Logging Modes
+
+| quiet | log | Console | Plain Text | Sessions | Use Case |
+|-------|-----|---------|------------|----------|----------|
+| False | True/None | ✓ | ✓ | ✓ | Development (default) |
+| True | True/None | ✗ | ✗ | ✓ | Eval/testing |
+| False | False | ✓ | ✗ | ✗ | Benchmarking |
+| False | "path" | ✓ | custom | ✓ | Custom log path |
+
+### Log Format
+
+Plain text logs include:
+- Timestamp
+- User input
+- LLM calls with timing, tokens, cost
+- Tool executions with parameters and results
+- Final agent responses
+
+Example log output:
+```
+[10:30:15] INPUT: Calculate 2 + 2
+[10:30:15] -> LLM Request (gpt-4o-mini) • 2 msgs • 1 tools
+[10:30:16] <- LLM Response (234ms) • 1 tools • 156 tokens • $0.0001
+[10:30:16] -> Tool: calculator({"expression": "2+2"})
+[10:30:16] <- Result (1ms): 4
+[10:30:16] [OK] Complete (1.2s)
+```
+
+### Session YAML Format
+
+Sessions are saved for replay and eval:
+
+```yaml
+name: assistant
+timestamp: 2024-12-02 10:30:15
+
+turns:
+  - input: "Calculate 2 + 2"
+    model: "gpt-4o-mini"
+    duration_ms: 1200
+    tokens: 156
+    cost: 0.0001
+    tools_called: [calculator]
+    result: "The answer is 4"
+    messages: '[{"role":"system",...}]'
+```
+
+## LLM
+
+Abstract base class for language models. ConnectOnion supports multiple LLM providers through a unified interface.
+
+### Model Routing
+
+The `create_llm()` factory function routes models to the appropriate provider:
+
+```python
+from connectonion.llm import create_llm
+
+# OpenAI models
+llm = create_llm("gpt-4o-mini")      # → OpenAILLM
+llm = create_llm("o4-mini")          # → OpenAILLM
+
+# Anthropic models
+llm = create_llm("claude-3-5-sonnet") # → AnthropicLLM
+
+# Google Gemini models
+llm = create_llm("gemini-2.5-flash")  # → GeminiLLM
+
+# ConnectOnion managed keys (co/ prefix)
+llm = create_llm("co/gpt-4o-mini")    # → OpenOnionLLM
+llm = create_llm("co/gemini-2.5-flash") # → OpenOnionLLM
+```
+
+### co/ Models (Managed Keys)
+
+Models prefixed with `co/` use ConnectOnion's managed API keys through the OpenOnion proxy:
+
+```python
+from connectonion import Agent
+
+# Uses OpenOnion managed keys - no API key needed
+agent = Agent(name="bot", model="co/gemini-2.5-flash")
+```
+
+**How it works:**
+1. Client detects `co/` prefix → routes to `OpenOnionLLM`
+2. Prefix is stripped before sending to server
+3. Server routes to appropriate provider (OpenAI, Anthropic, Gemini)
+4. Response returned in OpenAI-compatible format
+
+**Available co/ models:**
+- `co/gpt-4o-mini`, `co/gpt-4o`, `co/gpt-5`, `co/gpt-5-mini`, `co/gpt-5-nano`, `co/o4-mini`
+- `co/gemini-2.5-pro`, `co/gemini-2.5-flash`, `co/gemini-2.5-flash-lite`, `co/gemini-2.0-flash`
+
+**Environment variable:** `OPENONION_API_KEY` (auto-loaded from `.env`)
+
+### OpenAILLM
+
+OpenAI API implementation.
+
+```python
+from connectonion.llm import OpenAILLM
+
+llm = OpenAILLM(
+    api_key="your-key",  # or OPENAI_API_KEY env var
+    model="gpt-4o-mini",
+    temperature=0.7
+)
+
+agent = Agent("bot", llm=llm)
+```
+
+### AnthropicLLM
+
+Anthropic Claude API implementation.
+
+```python
+from connectonion.llm import AnthropicLLM
+
+llm = AnthropicLLM(
+    api_key="your-key",  # or ANTHROPIC_API_KEY env var
+    model="claude-3-5-sonnet-20241022"
+)
+
+agent = Agent("bot", llm=llm)
+```
+
+### GeminiLLM
+
+Google Gemini API implementation (uses OpenAI-compatible endpoint).
+
+```python
+from connectonion.llm import GeminiLLM
+
+llm = GeminiLLM(
+    api_key="your-key",  # or GEMINI_API_KEY env var
+    model="gemini-2.5-flash"
+)
+
+agent = Agent("bot", llm=llm)
+```
+
+### OpenOnionLLM
+
+ConnectOnion managed keys implementation.
+
+```python
+from connectonion.llm import OpenOnionLLM
+
+llm = OpenOnionLLM(
+    api_key="your-token",  # or OPENONION_API_KEY env var
+    model="co/gemini-2.5-flash"
+)
+
+agent = Agent("bot", llm=llm)
+```
+
+**Base URLs:**
+- Production: `https://oo.openonion.ai/v1`
+- Development: `http://localhost:8000/v1` (when `ENVIRONMENT=development`)
+
+## Prompts Module
+
+Utilities for loading system prompts.
+
+### `load_system_prompt(prompt: Union[str, Path, None]) -> str`
+
+Load system prompt from various sources.
+
+```python
+from connectonion.prompts import load_system_prompt
+
+# From string
+prompt = load_system_prompt("You are helpful")
+
+# From file
+prompt = load_system_prompt("prompts/assistant.md")
+
+# From Path
+from pathlib import Path
+prompt = load_system_prompt(Path("prompts/assistant.txt"))
+
+# Default
+prompt = load_system_prompt(None)
+```
+
+**Raises:**
+- `FileNotFoundError`: If Path object points to non-existent file
+- `ValueError`: If file is empty or not valid UTF-8
+- `TypeError`: If invalid type provided
+
+## Decorators
+
+### `@xray`
+
+Enable detailed execution tracing.
+
+```python
+from connectonion import xray
+
+@xray
+def my_agent_function():
+    agent = Agent("tracer")
+    return agent.input("task")
+
+# After execution:
+xray.trace()  # Shows detailed execution flow
+```
+
+### `@replay`
+
+Record and replay agent interactions.
+
+```python
+from connectonion import replay
+
+@replay
+def workflow():
+    agent = Agent("bot")
+    return agent.input("task")
+
+# Replay the recorded interaction
+replay.last()
+```
+
+## Examples
+
+### Basic Agent
+
+```python
+from connectonion import Agent
+
+# Simple calculator agent
+def calculate(expression: str) -> str:
+    """Evaluate mathematical expressions."""
+    return str(eval(expression))
+
+agent = Agent("calculator", tools=[calculate])
+result = agent.input("What is 15 * 4?")
+```
+
+### Agent with Custom Prompt File
+
+```python
+# prompts/expert.md
+"""
+You are an expert Python developer with 10 years of experience.
+Focus on clean code, best practices, and performance.
+"""
+
+# main.py
+agent = Agent(
+    name="python_expert",
+    system_prompt="prompts/expert.md",
+    tools=[code_review, suggest_improvement]
+)
+```
+
+### Multi-Tool Agent
+
+```python
+def search(query: str) -> str:
+    """Search the web."""
+    # Implementation
+    
+def calculate(expr: str) -> str:
+    """Do math."""
+    # Implementation
+    
+def get_time() -> str:
+    """Get current time."""
+    # Implementation
+
+agent = Agent(
+    name="assistant",
+    system_prompt="You are a helpful research assistant.",
+    tools=[search, calculate, get_time]
+)
+
+# Agent can use multiple tools in one request
+result = agent.input("Search for Python tutorials, calculate 42*17, and tell me the time")
+```

connectonion/docs/archive/001-ai-agent-is-just-prompt-plus-function.md

@@ -0,0 +1,249 @@
+# Tutorial 001: AI Agent = Prompt + Function
+
+**Read time: 1 minute. Build your first AI Agent: 30 seconds.**
+
+## The Truth About Those $199 Courses
+
+People are selling courses right now:
+- **"Master LangChain in 30 Days!"** - $199
+- **"AutoGen Expert Certification"** - $299
+- **"Complete CrewAI Bootcamp"** - $499
+
+Here's what they don't want you to know:
+
+**AI Agent = Prompt + Function**
+
+That's it. That's the entire course.
+
+## Why I Built ConnectOnion
+
+I was building a project with LangChain and got disgusted:
+- Simple agent required 100+ lines of code
+- Documentation was incomprehensible, too many abstractions
+- Debugging made me want to throw my laptop
+- Every version update broke my code
+
+**I thought: Why can't this be simple?**
+
+So I built ConnectOnion. One design principle: **Keep simple things simple**.
+
+## See the Difference
+
+**LangChain Weather Agent:** 67 lines of hell
+```python
+from langchain.agents import Tool, AgentExecutor, LLMSingleActionAgent
+from langchain.prompts import StringPromptTemplate
+from langchain.chains import LLMChain
+from langchain.schema import AgentAction, AgentFinish, OutputParserException
+from langchain.chat_models import ChatOpenAI
+from typing import List, Union
+import re
+
+# Define the tool
+def get_weather(city: str) -> str:
+    return f"Sunny in {city}, 22°C"
+
+weather_tool = Tool(
+    name="Weather",
+    func=get_weather,
+    description="Get weather for a city"
+)
+
+tools = [weather_tool]
+
+# Set up the prompt template (yes, this is required)
+template = """You are a weather assistant.
+
+You have access to the following tools:
+
+{tools}
+
+Use the following format:
+
+Question: the input question you must answer
+Thought: you should always think about what to do
+Action: the action to take, should be one of [{tool_names}]
+Action Input: the input to the action
+Observation: the result of the action
+... (this Thought/Action/Action Input/Observation can repeat N times)
+Thought: I now know the final answer
+Final Answer: the final answer to the original input question
+
+Question: {input}
+{agent_scratchpad}"""
+
+class CustomPromptTemplate(StringPromptTemplate):
+    template: str
+    tools: List[Tool]
+
+    def format(self, **kwargs) -> str:
+        intermediate_steps = kwargs.pop("intermediate_steps")
+        thoughts = ""
+        for action, observation in intermediate_steps:
+            thoughts += action.log
+            thoughts += f"\nObservation: {observation}\nThought: "
+        kwargs["agent_scratchpad"] = thoughts
+        kwargs["tools"] = "\n".join([f"{tool.name}: {tool.description}" for tool in self.tools])
+        kwargs["tool_names"] = ", ".join([tool.name for tool in self.tools])
+        return self.template.format(**kwargs)
+
+prompt = CustomPromptTemplate(
+    template=template,
+    tools=tools,
+    input_variables=["input", "intermediate_steps"]
+)
+
+# Output parser (more boilerplate)
+class CustomOutputParser:
+    def parse(self, llm_output: str) -> Union[AgentAction, AgentFinish]:
+        if "Final Answer:" in llm_output:
+            return AgentFinish(
+                return_values={"output": llm_output.split("Final Answer:")[-1].strip()},
+                log=llm_output,
+            )
+        regex = r"Action\s*\d*\s*:(.*?)\nAction\s*\d*\s*Input\s*\d*\s*:[\s]*(.*)"
+        match = re.search(regex, llm_output, re.DOTALL)
+        if not match:
+            raise OutputParserException(f"Could not parse LLM output: `{llm_output}`")
+        action = match.group(1).strip()
+        action_input = match.group(2)
+        return AgentAction(tool=action, tool_input=action_input.strip(" ").strip('"'), log=llm_output)
+
+# Create the LLM chain
+llm = ChatOpenAI(temperature=0)
+llm_chain = LLMChain(llm=llm, prompt=prompt)
+
+# Create the agent (finally!)
+tool_names = [tool.name for tool in tools]
+agent = LLMSingleActionAgent(
+    llm_chain=llm_chain,
+    output_parser=CustomOutputParser(),
+    stop=["\nObservation:"],
+    allowed_tools=tool_names
+)
+
+# Create the executor
+agent_executor = AgentExecutor.from_agent_and_tools(agent=agent, tools=tools, verbose=True)
+
+# Use it (after 67 lines of setup)
+agent_executor.run("What's the weather in Tokyo?")
+```
+
+**My ConnectOnion:** 5 lines
+```python
+from connectonion import Agent
+
+def get_weather(city: str) -> str:
+    return f"Sunny in {city}, 22°C"
+
+agent = Agent("weather_bot", tools=[get_weather])
+agent.input("What's the weather in Tokyo?")
+```
+
+**Same result. 92% less code.**
+
+## How I Did It
+
+Simple. I found the essence:
+- **LangChain**: Makes simple problems complex to look professional
+- **My insight**: AI Agent is just ChatGPT that can call functions
+
+So ConnectOnion's core is:
+1. You write functions (define capabilities)
+2. You write prompts (define behavior)
+3. Framework combines them (I already built this part)
+
+## 30 Seconds with My Framework
+
+```python
+from connectonion import Agent
+
+# 1. Write a function - You already know how (10 seconds)
+def calculate(expression: str) -> str:
+    """Calculate math expression"""
+    return str(eval(expression))
+
+# 2. Create agent - Just prompt + function (10 seconds)
+agent = Agent(
+    "calculator",
+    system_prompt="You're a math tutor, explain your steps",
+    tools=[calculate]
+)
+
+# 3. Use it (10 seconds)
+print(agent.input("What's 42 times 17?"))
+# Output: 42 times 17 equals 714. Here's how: 40×17=680, 2×17=34, 680+34=714
+```
+
+**Done. This is the simplicity I wanted.**
+
+## Why Other Frameworks Are Garbage
+
+I've tried them all:
+
+**LangChain:**
+- Too many abstraction layers, like Russian dolls
+- Breaking changes every update
+- Debugging? Good luck
+- **My verdict:** Textbook overengineering
+
+**AutoGen:**
+- Forces you to learn Actor patterns
+- Message passing will make you dizzy
+- **My verdict:** Microsoft-style complexity for no reason
+
+**My ConnectOnion:**
+- No unnecessary abstractions
+- Functions are functions, prompts are prompts
+- Something wrong? Just print and debug
+- **Design philosophy:** If it needs documentation to explain, the design is wrong
+
+## Real Feedback
+
+What users are saying:
+- "Finally someone built a sane framework"
+- "Migrated from LangChain, 90% less code"
+- "This is what AI Agents should be"
+
+## Why I Made It Free and Open Source
+
+Because I'm sick of:
+1. Garbage frameworks wasting everyone's time
+2. Course sellers scamming people
+3. Simple things made complex
+
+**ConnectOnion will always be free, always open source.**
+
+```bash
+pip install connectonion
+```
+
+## The Formula
+
+**AI Agent = Prompt + Function**
+
+This is the essence I discovered. Now I'm sharing it with you.
+
+---
+
+## Class Dismissed
+
+This tutorial series is over.
+
+**Because there's really nothing to teach.**
+
+ConnectOnion is that simple:
+- Can you write functions? Yes
+- Can you write prompts? Yes
+- Then you already know how to use it
+
+The rest is just creativity.
+
+**Stop paying for garbage courses.**
+**Use ConnectOnion. 5 lines of code to change the world.**
+
+**Class dismissed.**
+
+---
+
+**Next**: Want to see what real agents can do? → [002: Real-World Agent Examples](002-make-your-agent-useful.md)