connectonion 0.5.8__py3-none-any.whl

connectonion/llm_do.py

@@ -0,0 +1,307 @@
+"""
+Purpose: One-shot LLM function for simple single-round calls without agent overhead
+LLM-Note:
+  Dependencies: imports from [typing, pathlib, pydantic, dotenv, prompts.py, llm.py] | imported by [debug_explainer/explain_context.py, user code, examples] | tested by [tests/test_llm_do.py, tests/test_llm_do_comprehensive.py, tests/test_real_llm_do.py]
+  Data flow: user calls llm_do(input, output, system_prompt, model, api_key, **kwargs) → validates input non-empty → loads system_prompt via load_system_prompt() → builds messages [system, user] → calls create_llm(model, api_key) factory → calls llm.complete(messages, **kwargs) OR llm.structured_complete(messages, output, **kwargs) → returns string OR Pydantic model instance
+  State/Effects: loads .env via dotenv.load_dotenv() | reads system_prompt files if Path provided | makes one LLM API request | no caching or persistence | stateless
+  Integration: exposes llm_do(input, output, system_prompt, model, api_key, **kwargs) | default model="co/gemini-2.5-flash" (managed keys) | default temperature=0.1 | supports all create_llm() providers | **kwargs pass through to provider (max_tokens, temperature, etc.)
+  Performance: minimal overhead (no agent loop, no tool calling, no conversation history) | one LLM call per invocation | no caching | synchronous blocking
+  Errors: raises ValueError if input empty | provider errors from create_llm() and llm.complete() bubble up | Pydantic ValidationError if structured output doesn't match schema
+
+One-shot LLM function for simple, single-round calls with optional structured output.
+
+This module provides the `llm_do()` function - a simplified interface for making
+one-shot LLM calls without the overhead of the full Agent system. Perfect for
+simple tasks that don't require multi-step reasoning or tool calling.
+
+Purpose
+-------
+`llm_do()` is designed for:
+- Quick LLM calls without agent overhead
+- Data extraction with Pydantic validation
+- Simple Q&A and text generation
+- Format conversion (text → JSON, etc.)
+- One-shot analysis tasks
+
+NOT designed for:
+- Multi-step workflows (use Agent instead)
+- Tool calling (use Agent instead)
+- Iterative refinement (use Agent instead)
+- Maintaining conversation history (use Agent instead)
+
+Architecture
+-----------
+The function is a thin wrapper around the LLM provider abstraction:
+
+1. **Input Validation**: Ensures non-empty input
+2. **System Prompt Loading**: Loads from string or file path
+3. **Message Building**: Constructs OpenAI-format message list
+4. **LLM Selection**: Uses create_llm() factory to get provider
+5. **Response Handling**: Routes to complete() or structured_complete()
+
+Key Design Decisions
+-------------------
+- **Stateless**: No conversation history, each call is independent
+- **Simple API**: Minimal parameters, sensible defaults
+- **Default Model**: Uses "co/gemini-2.5-flash" (ConnectOnion managed keys) for zero-setup
+- **Structured Output**: Native Pydantic support via provider-specific APIs
+- **Flexible Parameters**: **kwargs pass through to underlying LLM (temperature, max_tokens, etc.)
+
+Comparison with Agent
+--------------------
+┌─────────────────┬──────────────┬─────────────────┐
+│ Feature         │ llm_do()     │ Agent()         │
+├─────────────────┼──────────────┼─────────────────┤
+│ Iterations      │ Always 1     │ Up to max_iters │
+│ Tools           │ No           │ Yes             │
+│ State           │ Stateless    │ Maintains hist  │
+│ Use case        │ Quick tasks  │ Complex flows   │
+│ Overhead        │ Minimal      │ Full framework  │
+└─────────────────┴──────────────┴─────────────────┘
+
+Data Flow
+---------
+User code → llm_do(input, output, model, **kwargs)
+               ↓
+         Validate input → Load system_prompt → Build messages
+               ↓
+         create_llm(model, api_key) → Provider instance
+               ↓
+    ┌─────────────────────────────────────┐
+    │ If output (Pydantic model):         │
+    │   provider.structured_complete()    │
+    │   → Pydantic instance               │
+    │                                     │
+    │ If no output:                       │
+    │   provider.complete()               │
+    │   → String content                  │
+    └─────────────────────────────────────┘
+               ↓
+         Return result to user
+
+Supported Providers
+------------------
+All providers from llm.py module:
+
+1. **OpenAI**: gpt-4o, gpt-4o-mini, gpt-3.5-turbo, o4-mini
+   - Native structured output via responses.parse()
+   - Fastest structured output implementation
+
+2. **Anthropic**: claude-3-5-sonnet, claude-3-5-haiku-20241022
+   - Structured output via forced tool calling
+   - Requires max_tokens parameter (default: 8192)
+
+3. **Google Gemini**: gemini-2.5-flash, gemini-2.5-pro
+   - Structured output via response_schema
+   - Good balance of speed and quality
+
+4. **ConnectOnion**: co/gpt-4o, co/o4-mini (DEFAULT)
+   - Managed API keys (no env vars needed!)
+   - Proxies to OpenAI with usage tracking
+   - Requires: run `co auth` first
+
+Usage Patterns
+-------------
+1. **Simple Q&A**:
+   >>> answer = llm_do("What is 2+2?")
+   >>> print(answer)  # "4"
+
+2. **Structured Extraction**:
+   >>> class Person(BaseModel):
+   ...     name: str
+   ...     age: int
+   >>> result = llm_do("John, 30 years old", output=Person)
+   >>> result.name  # "John"
+
+3. **Custom System Prompt**:
+   >>> answer = llm_do(
+   ...     "Hello",
+   ...     system_prompt="You are a pirate. Always respond like a pirate."
+   ... )
+
+4. **Different Provider**:
+   >>> answer = llm_do("Hello", model="claude-3-5-haiku-20241022")
+
+5. **Runtime Parameters**:
+   >>> answer = llm_do(
+   ...     "Write a story",
+   ...     temperature=0.9,     # More creative
+   ...     max_tokens=100       # Short response
+   ... )
+
+Parameters
+----------
+- input (str): The text/question to send to the LLM
+- output (Type[BaseModel], optional): Pydantic model for structured output
+- system_prompt (str | Path, optional): System instructions (inline or file path)
+- model (str): Model name (default: "co/gemini-2.5-flash")
+- temperature (float): Sampling temperature (default: 0.1 for consistency)
+- api_key (str, optional): Override API key (uses env vars by default)
+- **kwargs: Additional parameters passed to LLM (max_tokens, top_p, etc.)
+
+Returns
+-------
+- str: Plain text response (when output is None)
+- BaseModel: Validated Pydantic instance (when output is provided)
+
+Raises
+------
+- ValueError: If input is empty
+- ValueError: If API key is missing
+- ValueError: If model is unknown
+- ValidationError: If structured output doesn't match schema
+- Provider-specific errors: From underlying LLM SDKs
+
+Environment Variables
+--------------------
+Optional (choose based on model):
+  - OPENAI_API_KEY: For OpenAI models
+  - ANTHROPIC_API_KEY: For Claude models
+  - GEMINI_API_KEY or GOOGLE_API_KEY: For Gemini models
+  - OPENONION_API_KEY: For co/ models (or run `co auth`)
+
+Dependencies
+-----------
+- llm.py: create_llm() factory and provider implementations
+- prompts.py: load_system_prompt() for file-based prompts
+- pydantic: BaseModel validation for structured output
+- dotenv: Loads .env file automatically
+
+Integration Points
+-----------------
+Used by:
+  - User code: Direct function calls
+  - Examples: Quick scripts and tutorials
+  - Tests: test_llm_do.py and test_llm_do_comprehensive.py
+
+Related modules:
+  - agent.py: Full agent system for complex workflows
+  - llm.py: Provider abstraction layer
+
+Code Size
+---------
+102 lines (down from 387 after refactoring)
+- Removed duplicate OpenOnion authentication logic
+- Eliminated LiteLLM-specific code
+- Now a pure wrapper around llm.py providers
+
+Testing
+-------
+Comprehensive test coverage in:
+  - tests/test_llm_do.py: 12 tests (unit + integration)
+  - tests/test_llm_do_comprehensive.py: 23 tests (all doc examples)
+  - tests/test_real_llm_do.py: Real API integration tests
+
+All documentation examples in docs/llm_do.md are tested and validated.
+
+Example from Documentation
+--------------------------
+From docs/llm_do.md Quick Start:
+
+    from connectonion import llm_do
+    from pydantic import BaseModel
+
+    # Simple call
+    answer = llm_do("What's 2+2?")
+
+    # Structured output
+    class Analysis(BaseModel):
+        sentiment: str
+        confidence: float
+        keywords: list[str]
+
+    result = llm_do(
+        "I absolutely love this product! Best purchase ever!",
+        output=Analysis
+    )
+    print(result.sentiment)    # "positive"
+    print(result.confidence)   # 0.98
+"""
+
+from typing import Union, Type, Optional, TypeVar
+from pathlib import Path
+from pydantic import BaseModel
+from .prompts import load_system_prompt
+from .llm import create_llm
+
+T = TypeVar('T', bound=BaseModel)
+
+
+def llm_do(
+    input: str,
+    output: Optional[Type[T]] = None,
+    system_prompt: Optional[Union[str, Path]] = None,
+    model: str = "co/gemini-2.5-flash",
+    api_key: Optional[str] = None,
+    **kwargs
+) -> Union[str, T]:
+    """
+    Make a one-shot LLM call with optional structured output.
+
+    Supports multiple LLM providers:
+    - OpenAI: "gpt-4o", "o4-mini", "gpt-3.5-turbo"
+    - Anthropic: "claude-3-5-sonnet", "claude-3-5-haiku-20241022"
+    - Google: "gemini-2.5-pro", "gemini-2.5-flash"
+    - ConnectOnion Managed: "co/gpt-4o", "co/o4-mini" (no API keys needed!)
+
+    Args:
+        input: The input text/question to send to the LLM
+        output: Optional Pydantic model class for structured output
+        system_prompt: Optional system prompt (string or file path)
+        model: Model name (default: "co/gemini-2.5-flash")
+        api_key: Optional API key (uses environment variable if not provided)
+        **kwargs: Additional parameters (temperature, max_tokens, etc.)
+
+    Returns:
+        Either a string response or an instance of the output model
+
+    Examples:
+        >>> # Simple string response with default model
+        >>> answer = llm_do("What's 2+2?")
+        >>> print(answer)  # "4"
+
+        >>> # With ConnectOnion managed keys (no API key needed!)
+        >>> answer = llm_do("What's 2+2?", model="co/o4-mini")
+
+        >>> # With Claude
+        >>> answer = llm_do("Explain quantum physics", model="claude-3-5-haiku-20241022")
+
+        >>> # With Gemini
+        >>> answer = llm_do("Write a poem", model="gemini-2.5-flash")
+
+        >>> # With structured output
+        >>> class Analysis(BaseModel):
+        ...     sentiment: str
+        ...     score: float
+        >>>
+        >>> result = llm_do("I love this!", output=Analysis)
+        >>> print(result.sentiment)  # "positive"
+    """
+    # Validate input
+    if not input or not input.strip():
+        raise ValueError("Input cannot be empty")
+
+    # Load system prompt
+    if system_prompt:
+        prompt_text = load_system_prompt(system_prompt)
+    else:
+        prompt_text = "You are a helpful assistant."
+
+    # Build messages
+    messages = [
+        {"role": "system", "content": prompt_text},
+        {"role": "user", "content": input}
+    ]
+
+    # Create LLM using factory (only pass api_key and initialization params)
+    llm = create_llm(model=model, api_key=api_key)
+
+    # Get response
+    if output:
+        # Structured output - use structured_complete()
+        return llm.structured_complete(messages, output, **kwargs)
+    else:
+        # Plain text - use complete()
+        # Pass through kwargs (max_tokens, temperature, etc.)
+        response = llm.complete(messages, tools=None, **kwargs)
+        return response.content

connectonion/logger.py

@@ -0,0 +1,300 @@
+"""
+Purpose: Unified logging interface for agents - terminal output + plain text + YAML sessions
+LLM-Note:
+  Dependencies: imports from [datetime, pathlib, typing, yaml, console.py] | imported by [agent.py, tool_executor.py] | tested by [tests/unit/test_logger.py]
+  Data flow: receives from Agent/tool_executor → delegates to Console for terminal/file → writes YAML sessions to .co/sessions/
+  State/Effects: writes to .co/sessions/{agent_name}.yaml (one file per agent, appends turns) | delegates file logging to Console | session data persisted after each turn
+  Integration: exposes Logger(agent_name, quiet, log), .print(), .log_tool_call(name, args), .log_tool_result(result, timing), .log_llm_response(), .start_session(), .log_turn()
+  Session format: metadata at top → turns summary (with tools_called as function-call style) → system_prompt + messages at end (see docs/session-yaml-format.md)
+  Performance: YAML written after each turn (incremental) | loads existing session file on start | Console delegation is direct passthrough
+  Errors: let I/O errors bubble up (no try-except)
+"""
+
+from datetime import datetime
+from pathlib import Path
+from typing import Optional, Union, Dict, Any
+import yaml
+
+from .console import Console
+
+
+class Logger:
+    """Unified logging: terminal output + plain text + YAML sessions.
+
+    Facade pattern: wraps Console for terminal/file logging, adds YAML sessions.
+
+    Session files use one file per agent (.co/sessions/{agent_name}.yaml) to
+    reduce file clutter. New turns are appended to the same file.
+
+    Args:
+        agent_name: Name of the agent (used in filenames)
+        quiet: Suppress console output (default False)
+        log: Enable file logging (default True, or path string for custom location)
+
+    Files created:
+        - .co/logs/{agent_name}.log: Plain text log with session markers
+        - .co/sessions/{agent_name}.yaml: Structured YAML with all turns
+
+    Examples:
+        # Development (default) - see output + save everything
+        logger = Logger("my-agent")
+
+        # Eval mode - quiet but record sessions
+        logger = Logger("my-agent", quiet=True)
+
+        # Benchmark - completely off
+        logger = Logger("my-agent", log=False)
+
+        # Custom log path
+        logger = Logger("my-agent", log="custom/path.log")
+    """
+
+    def __init__(
+        self,
+        agent_name: str,
+        quiet: bool = False,
+        log: Union[bool, str, Path, None] = None
+    ):
+        self.agent_name = agent_name
+
+        # Determine what to enable
+        self.enable_console = not quiet
+        self.enable_sessions = True  # Sessions on unless log=False
+        self.enable_file = True
+        self.log_file_path = Path(f".co/logs/{agent_name}.log")
+
+        # Parse log parameter
+        if log is False:
+            # log=False: disable everything
+            self.enable_file = False
+            self.enable_sessions = False
+        elif isinstance(log, (str, Path)) and log:
+            # Custom path
+            self.log_file_path = Path(log)
+        # else: log=True or log=None → defaults
+
+        # If quiet=True, also disable file (only keep sessions)
+        if quiet:
+            self.enable_file = False
+
+        # Console for terminal output (only if not quiet)
+        self.console = None
+        if self.enable_console:
+            file_path = self.log_file_path if self.enable_file else None
+            self.console = Console(log_file=file_path)
+
+        # Session state (YAML)
+        self.session_file: Optional[Path] = None
+        self.session_data: Optional[Dict[str, Any]] = None
+
+    # Delegate to Console
+    def print(self, message: str, style: str = None):
+        """Print message to console (if enabled)."""
+        if self.console:
+            self.console.print(message, style)
+
+    def print_xray_table(self, *args, **kwargs):
+        """Print xray table for decorated tools."""
+        if self.console:
+            self.console.print_xray_table(*args, **kwargs)
+
+    def log_llm_response(self, *args, **kwargs):
+        """Log LLM response with token usage."""
+        if self.console:
+            self.console.log_llm_response(*args, **kwargs)
+
+    def log_tool_call(self, tool_name: str, tool_args: dict):
+        """Log tool call."""
+        if self.console:
+            self.console.log_tool_call(tool_name, tool_args)
+
+    def log_tool_result(self, result: str, timing_ms: float):
+        """Log tool result."""
+        if self.console:
+            self.console.log_tool_result(result, timing_ms)
+
+    def _format_tool_call(self, trace_entry: dict) -> str:
+        """Format tool call as natural function-call style: greet(name='Alice')"""
+        tool_name = trace_entry.get('tool_name', '')
+        args = trace_entry.get('arguments', {})
+        parts = []
+        for k, v in args.items():
+            if isinstance(v, str):
+                v_str = v if len(v) <= 50 else v[:50] + "..."
+                parts.append(f"{k}='{v_str}'")
+            else:
+                v_str = str(v)
+                if len(v_str) > 50:
+                    v_str = v_str[:50] + "..."
+                parts.append(f"{k}={v_str}")
+        return f"{tool_name}({', '.join(parts)})"
+
+    # Session logging (YAML)
+    def start_session(self, system_prompt: str = "", session_id: Optional[str] = None):
+        """Initialize session YAML file.
+
+        Uses one file per session_id (for HTTP API) or per agent (for interactive).
+        Loads existing session data if file exists, appends new turns.
+
+        Args:
+            system_prompt: The system prompt for this session
+            session_id: Optional session identifier. If provided, logs to
+                       .co/sessions/{session_id}.yaml for thread-safe HTTP API.
+                       If None, uses agent name for interactive mode.
+        """
+        if not self.enable_sessions:
+            return
+
+        sessions_dir = Path(".co/sessions")
+        sessions_dir.mkdir(parents=True, exist_ok=True)
+
+        # Use session_id if provided (HTTP API), otherwise use agent_name (interactive)
+        filename = session_id if session_id else self.agent_name
+        # Sanitize: keep only safe characters (alphanumeric, dash, underscore)
+        import re
+        filename = re.sub(r'[^a-zA-Z0-9_-]', '_', filename)[:255] or 'default'
+        self.session_file = sessions_dir / f"{filename}.yaml"
+
+        # Load existing session or create new
+        if self.session_file.exists():
+            with open(self.session_file, 'r') as f:
+                self.session_data = yaml.safe_load(f) or {}
+            # Ensure ALL required fields exist (handles empty/corrupted files)
+            if 'name' not in self.session_data:
+                self.session_data['name'] = self.agent_name
+            if 'session_id' not in self.session_data and session_id:
+                self.session_data['session_id'] = session_id
+            if 'created' not in self.session_data:
+                self.session_data['created'] = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+            if 'total_cost' not in self.session_data:
+                self.session_data['total_cost'] = 0.0
+            if 'total_tokens' not in self.session_data:
+                self.session_data['total_tokens'] = 0
+            if 'turns' not in self.session_data:
+                self.session_data['turns'] = []
+            if 'messages' not in self.session_data:
+                self.session_data['messages'] = {}
+            # Update system_prompt if provided
+            if system_prompt:
+                self.session_data['system_prompt'] = system_prompt
+        else:
+            self.session_data = {
+                "name": self.agent_name,
+                "session_id": session_id,
+                "created": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+                "total_cost": 0.0,
+                "total_tokens": 0,
+                "system_prompt": system_prompt,
+                "turns": [],
+                "messages": {}  # Dict keyed by turn number
+            }
+
+    def log_turn(self, user_input: str, result: str, duration_ms: float, session: dict, model: str):
+        """Log turn summary + messages to YAML file.
+
+        Args:
+            user_input: The user's input prompt
+            result: The agent's final response
+            duration_ms: Total duration in milliseconds
+            session: Agent's current_session dict (contains messages, trace)
+            model: Model name string
+        """
+        if not self.enable_sessions or not self.session_data:
+            return
+
+        # Aggregate from trace
+        trace = session.get('trace', [])
+        llm_calls = [t for t in trace if t.get('type') == 'llm_call']
+        tool_calls = [t for t in trace if t.get('type') == 'tool_execution']
+
+        total_tokens = sum(
+            (t.get('usage').input_tokens + t.get('usage').output_tokens)
+            for t in llm_calls if t.get('usage')
+        )
+        total_cost = sum(
+            t.get('usage').cost
+            for t in llm_calls if t.get('usage')
+        )
+
+        turn_data = {
+            'input': user_input,
+            'expected': session.get('expected', ''),
+            'model': model,
+            'duration_ms': int(duration_ms),
+            'tokens': total_tokens,
+            'cost': round(total_cost, 4),
+            'tools_called': [self._format_tool_call(t) for t in tool_calls],
+            'result': result,
+            'evaluation': session.get('evaluation', '')
+        }
+
+        # Update session aggregates
+        self.session_data['updated'] = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        self.session_data['total_cost'] = round(
+            self.session_data.get('total_cost', 0) + turn_data['cost'], 4
+        )
+        self.session_data['total_tokens'] = (
+            self.session_data.get('total_tokens', 0) + turn_data['tokens']
+        )
+
+        # Add turn number and timestamp
+        turn_num = len(self.session_data['turns']) + 1
+        turn_data['turn'] = turn_num
+        turn_data['timestamp'] = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        self.session_data['turns'].append(turn_data)
+
+        # Extract this turn's messages (everything after what we've already saved)
+        all_messages = session.get('messages', [])
+        saved_count = sum(len(msgs) for msgs in self.session_data['messages'].values())
+        turn_messages = all_messages[saved_count + 1:]  # +1 to skip system message
+        self.session_data['messages'][turn_num] = turn_messages
+
+        # Write YAML
+        self._write_session()
+
+    def _write_session(self):
+        """Write session data with turns summary first, detail at end."""
+        # Build ordered dict: compact metadata → turns → detail (system_prompt + messages)
+        ordered = {
+            'name': self.session_data['name'],
+            'session_id': self.session_data.get('session_id'),
+            'created': self.session_data['created'],
+            'updated': self.session_data.get('updated', ''),
+            'total_cost': self.session_data.get('total_cost', 0),
+            'total_tokens': self.session_data.get('total_tokens', 0),
+            'turns': self.session_data['turns'],
+            # Detail section (scroll down)
+            'system_prompt': self.session_data.get('system_prompt', ''),
+            'messages': self.session_data['messages']
+        }
+        with open(self.session_file, 'w') as f:
+            yaml.dump(ordered, f, default_flow_style=False, allow_unicode=True, sort_keys=False)
+
+    def load_messages(self) -> list:
+        """Load and reconstruct full message list from session file.
+
+        Returns:
+            Full message list: [system_message] + all turn messages in order
+        """
+        if not self.session_file or not self.session_file.exists():
+            return []
+        with open(self.session_file, 'r') as f:
+            data = yaml.safe_load(f) or {}
+
+        # Reconstruct: system prompt + all turn messages in order
+        messages = []
+        if data.get('system_prompt'):
+            messages.append({"role": "system", "content": data['system_prompt']})
+
+        turn_messages = data.get('messages', {})
+        for turn_num in sorted(turn_messages.keys()):
+            messages.extend(turn_messages[turn_num])
+
+        return messages
+
+    def load_session(self) -> dict:
+        """Load session data from file."""
+        if not self.session_file or not self.session_file.exists():
+            return {'system_prompt': '', 'turns': [], 'messages': {}}
+        with open(self.session_file, 'r') as f:
+            return yaml.safe_load(f) or {'system_prompt': '', 'turns': [], 'messages': {}}

connectonion/prompt_files/__init__.py

@@ -0,0 +1 @@
+"""Prompts module for ConnectOnion built-in plugins."""

connectonion/prompt_files/analyze_contact.md

@@ -0,0 +1,62 @@
+You are a CRM analyst helping categorize email contacts for a personal CRM.
+
+CRITICAL: Distinguish between REAL CONTACTS (people worth tracking) vs SERVICE EMAILS (automated/marketing).
+
+## First, Determine Contact Type
+
+**REAL CONTACT** (worth tracking):
+- Actual person you've had conversations with
+- Business contacts, clients, partners, colleagues
+- Friends, family, professional connections
+- People who sent you personalized messages
+
+**SERVICE/AUTOMATED** (low priority):
+- Product update emails from tools you use (OneUp, Calendly, etc.)
+- Notification emails (LinkedIn, X/Twitter, GitHub, etc.)
+- Marketing/promotional emails
+- Receipts, invoices, shipping notifications
+- Newsletter subscriptions
+- No-reply addresses
+
+## Analysis Format
+
+### 1. Contact Type
+- **REAL_PERSON**: Worth tracking in CRM
+- **SERVICE_TOOL**: SaaS/tool you use (low priority)
+- **NOTIFICATION**: Social media, platform notifications (skip)
+- **MARKETING**: Promotional/sales emails (skip)
+
+### 2. Priority Score (1-10)
+- 10: Key business contact, active relationship
+- 7-9: Regular professional contact
+- 4-6: Occasional contact, might be useful
+- 1-3: Service/automated, not worth tracking
+
+### 3. If REAL_PERSON, provide:
+- Relationship context (colleague, client, friend, vendor)
+- Key topics discussed
+- Communication pattern
+- Important notes
+- Suggested tags (#client, #technical, #partner, etc.)
+
+### 4. If SERVICE/AUTOMATED, provide:
+- What service/tool this is from
+- Why it's not a real contact
+- Recommendation: SKIP (don't store) or LOW_PRIORITY
+
+## Examples
+
+**Example 1: davis@oneupapp.io**
+- Type: SERVICE_TOOL
+- Priority: 2
+- Analysis: OneUp is a social media scheduling tool. These emails are product updates and marketing, not personal communication.
+- Recommendation: SKIP - not a real relationship
+
+**Example 2: john.smith@acme.com**
+- Type: REAL_PERSON
+- Priority: 8
+- Relationship: Potential client
+- Topics: Discussed product demo, pricing inquiry
+- Tags: #prospect, #sales, #enterprise
+
+Be concise and factual. The goal is to help build a meaningful CRM, not clutter it with service notifications.

connectonion/prompt_files/eval_expected.md

@@ -0,0 +1,12 @@
+You generate expected outcomes for AI agent tasks.
+
+Given a user request and available tools, describe what should happen to complete the task.
+
+Be concise (1-2 sentences). Focus on:
+- What tools should be used
+- What the result should contain
+
+Example:
+- "Read the file, then provide a summary of its contents."
+- "Search for Python tutorials, then list the top 3 results."
+- "Calculate the expression and return the numeric answer."