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

connectonion/docs/useful_tools/google_calendar.md

@@ -0,0 +1,126 @@
+# GoogleCalendar
+
+Google Calendar integration for managing events and meetings.
+
+## Usage
+
+**Option 1: Import directly**
+
+```python
+from connectonion import GoogleCalendar
+
+agent = Agent("assistant", tools=[GoogleCalendar()])
+```
+
+**Option 2: Copy and customize**
+
+```bash
+co copy google_calendar
+```
+
+```python
+from tools.google_calendar import GoogleCalendar  # Your local copy
+```
+
+## Quick Start
+
+```python
+from connectonion import Agent, GoogleCalendar
+
+calendar = GoogleCalendar()
+agent = Agent("assistant", tools=[calendar])
+
+agent.input("What meetings do I have today?")
+```
+
+## Setup
+
+Requires Google OAuth authorization:
+
+```bash
+co auth google
+```
+
+## Methods
+
+### Reading Events
+
+```python
+# List upcoming events
+calendar.list_events(days_ahead=7, max_results=10)
+
+# Get today's events
+calendar.get_today_events()
+
+# Get specific event
+calendar.get_event(event_id="abc123")
+
+# Get upcoming meetings
+calendar.get_upcoming_meetings(days_ahead=7)
+
+# Find free slots
+calendar.find_free_slots(date="2024-01-15", duration_minutes=30)
+```
+
+### Creating Events
+
+```python
+# Create event
+calendar.create_event(
+    title="Team Meeting",
+    start_time="2024-01-15 14:00",
+    end_time="2024-01-15 15:00",
+    description="Weekly sync",
+    attendees="alice@example.com,bob@example.com",
+    location="Conference Room A"
+)
+
+# Create Google Meet meeting
+calendar.create_meet(
+    title="Video Call",
+    start_time="2024-01-15 14:00",
+    end_time="2024-01-15 15:00",
+    attendees="alice@example.com",
+    description="Quick sync"
+)
+```
+
+### Managing Events
+
+```python
+# Update event
+calendar.update_event(
+    event_id="abc123",
+    title="Updated Title",
+    start_time="2024-01-15 15:00",
+    end_time="2024-01-15 16:00"
+)
+
+# Delete event
+calendar.delete_event(event_id="abc123")
+```
+
+## Use with calendar_plugin
+
+For calendar approval before creating/modifying events:
+
+```python
+from connectonion.useful_plugins import calendar_plugin
+
+agent = Agent("assistant", tools=[calendar], plugins=[calendar_plugin])
+```
+
+## Customizing
+
+Need to modify GoogleCalendar's behavior? Copy the source to your project:
+
+```bash
+co copy google_calendar
+```
+
+Then import from your local copy:
+
+```python
+# from connectonion import GoogleCalendar  # Before
+from tools.google_calendar import GoogleCalendar  # After - customize freely!
+```

connectonion/docs/useful_tools/memory.md

@@ -0,0 +1,506 @@
+# Memory System
+
+Give your agents persistent memory using markdown-based storage.
+
+## Usage
+
+**Option 1: Import directly**
+
+```python
+from connectonion import Memory
+
+agent = Agent("assistant", tools=[Memory()])
+```
+
+**Option 2: Copy and customize**
+
+```bash
+co copy memory
+```
+
+```python
+from tools.memory import Memory  # Your local copy
+```
+
+## Quick Start
+
+```python
+from connectonion import Agent, Memory
+
+memory = Memory()
+agent = Agent(
+    name="assistant",
+    system_prompt="You are a helpful assistant with memory.",
+    tools=[memory]
+)
+
+# Agent can now remember things
+agent.input("Remember that Alice prefers email communication")
+agent.input("What do I know about Alice?")
+```
+
+## What is Memory?
+
+Memory is a simple, file-based storage system that lets your agents:
+- Save information persistently across sessions
+- Retrieve information by key
+- Search across all memories with regex
+- Organize knowledge in markdown format
+
+**Storage**: Memories start in a single `memory.md` file. When the file exceeds 3000 lines, it automatically splits into a directory structure with separate `.md` files per memory key.
+
+## Installation
+
+Memory is included in ConnectOnion:
+
+```bash
+pip install connectonion
+```
+
+## Basic Usage
+
+### Creating a Memory Instance
+
+```python
+from connectonion import Memory
+
+# Default (creates memory.md)
+memory = Memory()
+
+# Custom file path
+memory = Memory(memory_file="agent_knowledge.md")
+
+# Legacy: directory structure (creates directory immediately)
+memory = Memory(memory_dir="agent_knowledge")
+```
+
+### Adding Memory to an Agent
+
+```python
+from connectonion import Agent, Memory
+
+memory = Memory()
+agent = Agent("assistant", tools=[memory])
+```
+
+Now your agent has access to 4 memory methods:
+- `write_memory(key, content)` - Save or update information
+- `read_memory(key)` - Retrieve information
+- `list_memories()` - Show all stored memories
+- `search_memory(pattern)` - Search with regex
+
+## Memory Methods
+
+### write_memory
+
+Save information to memory:
+
+```python
+memory.write_memory("alice-notes", "Alice prefers email\nAlice works at TechCorp")
+# Returns: "Memory saved: alice-notes"
+```
+
+**Keys are sanitized:**
+- Only alphanumeric, hyphens, and underscores allowed
+- Converted to lowercase
+- `"Alice Notes!"` becomes `"alicenotes"`
+
+### read_memory
+
+Retrieve saved information:
+
+```python
+memory.read_memory("alice-notes")
+# Returns:
+# Memory: alice-notes
+#
+# Alice prefers email
+# Alice works at TechCorp
+```
+
+If not found:
+```python
+memory.read_memory("unknown")
+# Returns: "Memory not found: unknown\nAvailable memories: alice-notes, project-x"
+```
+
+### list_memories
+
+Show all stored memories:
+
+```python
+memory.list_memories()
+# Returns:
+# Stored Memories (3):
+# 1. alice-notes (85 bytes)
+# 2. bob-notes (62 bytes)
+# 3. project-x (120 bytes)
+```
+
+### search_memory
+
+Search across all memories using regex:
+
+```python
+# Simple text search (case-sensitive by default)
+memory.search_memory("email")
+# Returns:
+# Search Results (2 matches):
+#
+# alice-notes:
+#   Line 1: Alice prefers email
+#
+# contacts:
+#   Line 3: Email: alice@example.com
+
+# Case-insensitive search with (?i) flag
+memory.search_memory("(?i)email")
+
+# Regex patterns
+memory.search_memory(r"\w+@\w+\.\w+")  # Find email addresses
+memory.search_memory(r"Project [A-Z]")  # Find project names
+```
+
+## Examples
+
+### Example 1: Customer Notes
+
+```python
+from connectonion import Agent, Memory
+
+memory = Memory(memory_dir="customer_notes")
+agent = Agent(
+    name="sales-assistant",
+    system_prompt="You help track customer information.",
+    tools=[memory]
+)
+
+# Save customer info
+agent.input("Remember that Alice from TechCorp is interested in our API product and prefers email contact")
+
+# Later, recall the information
+agent.input("What do I know about Alice?")
+# Agent will use read_memory() to retrieve Alice's info
+```
+
+### Example 2: Project Tracker
+
+```python
+from connectonion import Agent, Memory
+
+memory = Memory(memory_dir="projects")
+agent = Agent(
+    name="project-manager",
+    system_prompt="You track project status and notes.",
+    tools=[memory]
+)
+
+# Save project updates
+agent.input("Remember: Project Alpha is 80% complete, needs final testing")
+agent.input("Remember: Project Beta is blocked, waiting on API keys")
+
+# Search for blocked projects
+agent.input("Which projects are blocked?")
+# Agent will use search_memory("blocked") to find relevant projects
+```
+
+### Example 3: Research Assistant
+
+```python
+from connectonion import Agent, Memory
+
+def web_search(query: str) -> str:
+    """Search the web for information."""
+    # Your search implementation
+    return f"Results for {query}"
+
+memory = Memory(memory_dir="research")
+agent = Agent(
+    name="researcher",
+    system_prompt="You research topics and save key findings.",
+    tools=[web_search, memory]
+)
+
+# Research and save
+agent.input("Research the history of Python programming and save key points")
+# Agent will search, then use write_memory() to save findings
+
+# Later, recall research
+agent.input("What did I learn about Python's history?")
+```
+
+### Example 4: Multi-Agent Shared Memory
+
+```python
+from connectonion import Agent, Memory
+
+# Shared memory between agents
+shared_memory = Memory(memory_dir="shared_knowledge")
+
+researcher = Agent(
+    name="researcher",
+    system_prompt="You research and document findings.",
+    tools=[shared_memory]
+)
+
+writer = Agent(
+    name="writer",
+    system_prompt="You write articles based on research.",
+    tools=[shared_memory]
+)
+
+# Researcher saves findings
+researcher.input("Research AI trends and save the findings")
+
+# Writer uses the same memory
+writer.input("Write an article based on AI trends research")
+```
+
+## Advanced Patterns
+
+### Memory with Different Tools
+
+Memory works alongside any other tools:
+
+```python
+from connectonion import Agent, Memory
+
+def calculate(expression: str) -> float:
+    """Calculate math expressions."""
+    return eval(expression)
+
+def send_email(to: str, subject: str, body: str) -> str:
+    """Send an email."""
+    # Implementation
+    return "Email sent"
+
+memory = Memory()
+
+agent = Agent(
+    name="multi-tool-agent",
+    tools=[calculate, send_email, memory]
+)
+```
+
+### Custom Memory File Organization
+
+Organize memories by category:
+
+```python
+# Separate memory files for different purposes
+customer_memory = Memory(memory_file="data/customers.md")
+project_memory = Memory(memory_file="data/projects.md")
+research_memory = Memory(memory_file="data/research.md")
+
+agent = Agent(
+    name="organized-agent",
+    tools=[customer_memory, project_memory, research_memory]
+)
+```
+
+### Regex Search Patterns
+
+Powerful search with regex:
+
+```python
+# Find email addresses
+memory.search_memory(r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b")
+
+# Find phone numbers
+memory.search_memory(r"\d{3}-\d{3}-\d{4}")
+
+# Find dates
+memory.search_memory(r"\d{4}-\d{2}-\d{2}")
+
+# Find URLs
+memory.search_memory(r"https?://[^\s]+")
+
+# Find specific keywords (word boundaries, case-insensitive)
+memory.search_memory(r"(?i)\bproject\b")
+```
+
+## File Format
+
+### Single File (Default)
+
+Memories start in a single `memory.md` file using section headers:
+
+```markdown
+## alice-notes
+
+Alice prefers email communication
+Works at TechCorp
+Interested in API product
+Last contact: 2025-11-20
+
+## bob-notes
+
+Bob from Marketing
+Prefers phone calls
+
+## project-x
+
+Project X is 80% complete
+Needs final testing
+```
+
+### Auto-Split to Directory
+
+When `memory.md` exceeds 3000 lines, it automatically migrates to a directory structure:
+
+```
+memory/
+├── alice-notes.md
+├── bob-notes.md
+└── project-x.md
+```
+
+Each file contains plain text/markdown content (without the `##` header).
+
+**Benefits of this approach:**
+- Simple by default (one file)
+- Scales automatically when needed
+- Human-readable
+- Version control friendly (git)
+- Easy to edit manually if needed
+- Supports rich formatting
+
+## Best Practices
+
+### 1. Use Descriptive Keys
+
+```python
+# Good
+memory.write_memory("alice-techcorp-contact-info", content)
+memory.write_memory("project-alpha-status", content)
+
+# Bad
+memory.write_memory("note1", content)
+memory.write_memory("data", content)
+```
+
+### 2. Structure Your Content
+
+```python
+# Use markdown formatting for better organization
+content = """# Alice - TechCorp
+
+## Contact Info
+- Email: alice@techcorp.com
+- Prefers: Email over phone
+
+## Projects
+- Interested in API product
+- Budget: $50k
+
+## Notes
+- Decision maker
+- Wants demo next week
+"""
+
+memory.write_memory("alice-techcorp", content)
+```
+
+### 3. Keep Memories Updated
+
+```python
+# Update or overwrite outdated memories
+agent.input("Review and update any memories older than 6 months")
+```
+
+### 4. Search Before Creating
+
+```python
+# Check if similar memory exists
+agent.input("Do we have any notes about Alice?")
+# Agent will search before creating duplicate memory
+```
+
+### 5. Use Consistent Naming
+
+```python
+# Choose a naming convention and stick to it
+memory.write_memory("customer-alice-techcorp", ...)
+memory.write_memory("customer-bob-acmecorp", ...)
+memory.write_memory("project-alpha", ...)
+memory.write_memory("project-beta", ...)
+```
+
+## Limitations
+
+### Storage
+
+- All memories are kept in memory during search operations
+- For very large memory stores (>1000 files or >100MB), consider database alternatives
+- No built-in memory limits - monitor disk usage
+
+### Concurrency
+
+- File-based storage is not optimized for high-concurrency scenarios
+- Multiple agents writing to the same memory simultaneously may cause race conditions
+- For production multi-agent systems, consider database-backed storage
+
+### Search Performance
+
+- Regex search scans all files linearly
+- Performance degrades with more memories
+- For large-scale search needs, consider full-text search solutions (Elasticsearch, etc.)
+
+## Troubleshooting
+
+### "Memory not found"
+
+Check available memories:
+```python
+print(memory.list_memories())
+```
+
+Remember that keys are sanitized (lowercase, alphanumeric + hyphens/underscores).
+
+### "Invalid key name"
+
+Use only alphanumeric characters, hyphens, and underscores:
+```python
+# Good
+memory.write_memory("alice-notes", content)
+
+# Bad (will be rejected or sanitized)
+memory.write_memory("alice@notes!", content)
+```
+
+### Memory file not created
+
+Memory creates the file automatically on first write:
+```python
+import os
+memory = Memory()
+memory.write_memory("test", "content")
+print(os.path.exists("memory.md"))  # Should be True
+```
+
+## Next Steps
+
+- See [Examples](../examples/memory_agent.py) for complete working code
+- Learn about [Plugins](./plugin.md) for automatic memory behaviors
+- Explore [Multi-Agent Systems](./multi-agent.md) with shared memory
+
+## Customizing
+
+Need to modify Memory's behavior? Copy the source to your project:
+
+```bash
+co copy memory
+```
+
+Then import from your local copy:
+
+```python
+# from connectonion import Memory  # Before
+from tools.memory import Memory      # After - customize freely!
+```
+
+## Related Documentation
+
+- [Agent Basics](./agent.md)
+- [Tools](./tools.md)
+- [Plugins](./plugin.md)