amiai 0.1.0__py3-none-any.whl

amiai-0.1.0.dist-info/METADATA

@@ -0,0 +1,305 @@
+Metadata-Version: 2.4
+Name: amiai
+Version: 0.1.0
+Summary: AMIAI SDK - Build AI agents with local tool execution
+Project-URL: Homepage, https://github.com/amiai/sdk-python
+Project-URL: Documentation, https://github.com/amiai/sdk-python#readme
+Project-URL: Repository, https://github.com/amiai/sdk-python
+Project-URL: Issues, https://github.com/amiai/sdk-python/issues
+Author-email: AMIAI <hello@amiai.com>
+License-Expression: MIT
+Keywords: agents,ai,amiai,llm,sdk,tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: pydantic>=2.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# amiai
+
+Build AI agents with local tool execution. Write tools that run on your machine, connect to AMIAI, and let agents call them securely over WebSocket.
+
+## Installation
+
+```bash
+pip install amiai
+```
+
+## Quick Start
+
+### 1. Create a tool
+
+```python
+# tools/search.tool.py
+from amiai_sdk import tool
+
+@tool(name="web_search", description="Search the web for information")
+async def search(query: str) -> dict:
+    # Your API key stays local - never sent to AMIAI
+    import httpx
+    async with httpx.AsyncClient() as client:
+        response = await client.get(
+            "https://api.example.com/search",
+            params={"q": query},
+            headers={"x-api-key": os.environ["SEARCH_API_KEY"]}
+        )
+        return response.json()
+```
+
+### 2. Run the harness
+
+```bash
+export AMIAI_API_KEY=amiai_xxx
+amiai dev
+```
+
+Output:
+```
+✓ Connected to AMIAI
+✓ Registered 1 tool: web_search
+✓ Waiting for invocations...
+```
+
+### 3. Create an agent that uses your tool
+
+```bash
+curl -X POST https://backend.amiai.com/api/agents \
+  -H "Authorization: Bearer $AMIAI_API_KEY" \
+  -d '{
+    "name": "Search Agent",
+    "systemPrompt": "Help users search the web.",
+    "tools": [{"name": "web_search", "source": "live"}]
+  }'
+```
+
+When the agent calls `web_search`, it executes **on your machine** with your local API keys.
+
+## How It Works
+
+```
+Your Machine                              AMIAI Backend
+─────────────                             ─────────────
+search.tool.py
+     ↓
+amiai dev ──────────WebSocket────────▶ ToolSessionDO
+                                              │
+     ◀───────── "invoke web_search" ──────────┤
+     │                                        │
+     ├── execute locally with your API keys   │
+     │                                        │
+     └─────────── "result" ──────────────────▶│──▶ Agent gets result
+```
+
+**Benefits:**
+- 🔐 API keys never leave your machine
+- 🚀 No webhooks or public servers needed
+- 🔄 Hot reload - just save and reconnect
+- 🛠️ Full access to local resources (files, databases, etc.)
+
+## API Reference
+
+### `@tool` decorator
+
+Define a tool for AMIAI agents to call.
+
+```python
+from amiai_sdk import tool
+
+@tool(
+    name="my_tool",
+    description="What this tool does"
+)
+async def my_tool(
+    param1: str,      # Required parameter
+    param2: int = 10  # Optional with default
+) -> dict:
+    return {"result": "data"}
+```
+
+Input schema is automatically derived from function signature and type hints.
+
+### Explicit schema
+
+```python
+@tool(
+    name="calculator",
+    description="Evaluate math expressions",
+    input_schema={
+        "type": "object",
+        "properties": {
+            "expression": {"type": "string", "description": "e.g., 2+2"}
+        },
+        "required": ["expression"]
+    }
+)
+def calculate(expression: str) -> dict:
+    return {"result": eval(expression)}
+```
+
+### `Harness` class
+
+Programmatic control over the WebSocket connection.
+
+```python
+from amiai_sdk import Harness
+
+harness = Harness(
+    api_key="amiai_xxx",
+    tools=[my_tool],
+    url="wss://backend.amiai.com/api/tools/live",  # optional
+    on_connect=lambda sid: print(f"Connected: {sid}"),
+    on_disconnect=lambda: print("Disconnected"),
+    on_invoke=lambda tool, args: print(f"Invoking {tool}"),
+    on_result=lambda tool, result: print(f"Result from {tool}"),
+    on_error=lambda e: print(f"Error: {e}"),
+)
+
+# Start and run forever
+await harness.start()
+await harness.run_forever()
+
+# Or manage manually
+await harness.start()
+# ... do other things
+await harness.stop()
+```
+
+### `start_harness` function
+
+Convenience function that creates and starts a harness.
+
+```python
+from amiai_sdk import start_harness
+
+harness = await start_harness(
+    api_key="amiai_xxx",
+    tools=[my_tool],
+)
+```
+
+## CLI Usage
+
+The `amiai` CLI automatically discovers tools in your project.
+
+```bash
+# Discover and register all *.tool.py and tools/*.py files
+amiai dev
+
+# Specify custom patterns
+amiai dev --pattern "src/**/*.py"
+
+# Use a different API endpoint (for local development)
+AMIAI_URL=ws://localhost:8787/api/tools/live amiai dev
+```
+
+## Examples
+
+### Calculator Tool
+
+```python
+from amiai_sdk import tool
+
+@tool(name="calculator", description="Evaluate mathematical expressions")
+def calculate(expression: str) -> dict:
+    """
+    Calculate the result of a math expression.
+    
+    Args:
+        expression: Math expression like "2 + 2 * 3"
+    """
+    result = eval(expression)  # In production, use a safe evaluator
+    return {"expression": expression, "result": result}
+```
+
+### Web Search with Parallel AI
+
+```python
+import os
+import httpx
+from amiai_sdk import tool
+
+@tool(name="web_search", description="Search the web using Parallel AI")
+async def search(query: str) -> dict:
+    async with httpx.AsyncClient() as client:
+        response = await client.post(
+            "https://api.parallel.ai/v1beta/search",
+            headers={
+                "Content-Type": "application/json",
+                "x-api-key": os.environ["PARALLEL_API_KEY"],
+                "parallel-beta": "search-extract-2025-10-10",
+            },
+            json={"search_queries": [query]},
+        )
+        data = response.json()
+        return {
+            "query": query,
+            "results": [
+                {"title": r["title"], "url": r["url"]}
+                for r in data.get("results", [])[:5]
+            ]
+        }
+```
+
+### File Reader
+
+```python
+from pathlib import Path
+from amiai_sdk import tool
+
+@tool(name="read_file", description="Read a file from the local filesystem")
+def read_file(path: str) -> dict:
+    content = Path(path).read_text()
+    return {"path": path, "content": content}
+```
+
+### Database Query
+
+```python
+import sqlite3
+from amiai_sdk import tool
+
+@tool(name="query_db", description="Query the local SQLite database")
+def query_database(sql: str) -> dict:
+    conn = sqlite3.connect("local.db")
+    cursor = conn.execute(sql)
+    columns = [d[0] for d in cursor.description]
+    rows = [dict(zip(columns, row)) for row in cursor.fetchall()]
+    conn.close()
+    return {"columns": columns, "rows": rows}
+```
+
+## Sync vs Async Tools
+
+Both sync and async functions work:
+
+```python
+# Async tool (recommended for I/O operations)
+@tool(name="async_search", description="Async web search")
+async def async_search(query: str) -> dict:
+    async with httpx.AsyncClient() as client:
+        response = await client.get(f"https://api.example.com/search?q={query}")
+        return response.json()
+
+# Sync tool (fine for CPU-bound operations)
+@tool(name="sync_calculate", description="Calculate expression")
+def sync_calculate(expression: str) -> dict:
+    return {"result": eval(expression)}
+```
+
+## License
+
+MIT

amiai-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+amiai_sdk/__init__.py,sha256=mN_LdpdQPAiubDnoN9-Q3xgV6K9lF-QFaAywdHmoklo,656
+amiai_sdk/cli.py,sha256=xJHElzrAHz7TAvIXQRTMAZDIy18Wchf9fSSi4ELq7zU,5097
+amiai_sdk/harness.py,sha256=ZOsvSshindvzHnjWpJc2L2FVnUO30zBVYkSogj_K0e4,10164
+amiai_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+amiai_sdk/tool.py,sha256=cl6XG4EKgjAWqfTJRrB0KJkdxvM0HEmaGi5wY4vow0M,4124
+amiai-0.1.0.dist-info/METADATA,sha256=YT_Ge4mxoLSoXPn7U5ax1g0J6ioA0_3KQ0QEolXS1Vk,8228
+amiai-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+amiai-0.1.0.dist-info/entry_points.txt,sha256=uFFJcsvdAxpkTrDa_rXR6TgH_gXg-dwBhsV65NJtzu0,45
+amiai-0.1.0.dist-info/RECORD,,

amiai-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

amiai-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+amiai = amiai_sdk.cli:main

amiai_sdk/__init__.py

@@ -0,0 +1,25 @@
+"""
+AMIAI SDK - Build AI agents with local tool execution
+
+Example:
+    from amiai_sdk import tool, Harness
+
+    @tool(
+        name="web_search",
+        description="Search the web for information"
+    )
+    async def search(query: str) -> dict:
+        # Your API key stays local
+        response = await fetch(f"https://api.example.com/search?q={query}")
+        return response.json()
+
+    # Start the harness
+    harness = Harness(api_key="amiai_xxx", tools=[search])
+    await harness.start()
+"""
+
+from .tool import tool, Tool
+from .harness import Harness, start_harness
+
+__version__ = "0.1.0"
+__all__ = ["tool", "Tool", "Harness", "start_harness"]

amiai_sdk/cli.py

@@ -0,0 +1,177 @@
+"""
+AMIAI CLI - Run the tool harness
+
+Usage:
+    amiai dev                    # Discover and run tools
+    amiai dev --pattern "*.py"   # Custom pattern
+"""
+
+import argparse
+import asyncio
+import importlib.util
+import os
+import sys
+from glob import glob
+from pathlib import Path
+from typing import List
+
+from .tool import Tool
+from .harness import Harness
+
+
+def discover_tools(patterns: List[str]) -> List[Tool]:
+    """Discover tools from Python files matching patterns."""
+    tools: List[Tool] = []
+    seen_files: set = set()
+    
+    for pattern in patterns:
+        for file_path in glob(pattern, recursive=True):
+            abs_path = os.path.abspath(file_path)
+            if abs_path in seen_files:
+                continue
+            seen_files.add(abs_path)
+            
+            # Skip __pycache__ and hidden files
+            if "__pycache__" in file_path or file_path.startswith("."):
+                continue
+            
+            try:
+                tools.extend(load_tools_from_file(file_path))
+            except Exception as e:
+                print(f"Warning: Failed to load {file_path}: {e}")
+    
+    return tools
+
+
+def load_tools_from_file(file_path: str) -> List[Tool]:
+    """Load Tool instances from a Python file."""
+    tools: List[Tool] = []
+    
+    spec = importlib.util.spec_from_file_location("tool_module", file_path)
+    if spec is None or spec.loader is None:
+        return tools
+    
+    module = importlib.util.module_from_spec(spec)
+    
+    try:
+        spec.loader.exec_module(module)
+    except Exception as e:
+        print(f"Warning: Error loading {file_path}: {e}")
+        return tools
+    
+    # Find all Tool instances in the module
+    for name in dir(module):
+        obj = getattr(module, name)
+        if isinstance(obj, Tool):
+            tools.append(obj)
+    
+    return tools
+
+
+async def run_harness(api_key: str, tools: List[Tool], url: str) -> None:
+    """Run the harness with discovered tools."""
+    print(f"\n{'='*50}")
+    print("AMIAI Tool Harness")
+    print(f"{'='*50}\n")
+    
+    if not tools:
+        print("No tools found!")
+        print("\nCreate a tool file like this:")
+        print("  # tools/search.py")
+        print("  from amiai_sdk import tool")
+        print("")
+        print("  @tool(name='web_search', description='Search the web')")
+        print("  async def search(query: str) -> dict:")
+        print("      return {'results': [...]}")
+        return
+    
+    print(f"Found {len(tools)} tool(s):")
+    for t in tools:
+        print(f"  - {t.name}: {t.description[:50]}...")
+    print()
+    
+    def on_connect(session_id: str) -> None:
+        print(f"✓ Connected to AMIAI")
+        print(f"  Session ID: {session_id}")
+        print(f"\n✓ Waiting for invocations...\n")
+    
+    def on_disconnect() -> None:
+        print("⚠ Disconnected from AMIAI")
+    
+    def on_invoke(tool_name: str, args: dict) -> None:
+        print(f"→ Invoking: {tool_name}")
+        print(f"  Args: {args}")
+    
+    def on_result(tool_name: str, result: any) -> None:
+        result_str = str(result)
+        if len(result_str) > 100:
+            result_str = result_str[:100] + "..."
+        print(f"← Result: {result_str}")
+    
+    def on_error(error: Exception) -> None:
+        print(f"✗ Error: {error}")
+    
+    harness = Harness(
+        api_key=api_key,
+        tools=tools,
+        url=url,
+        on_connect=on_connect,
+        on_disconnect=on_disconnect,
+        on_invoke=on_invoke,
+        on_result=on_result,
+        on_error=on_error,
+    )
+    
+    try:
+        await harness.run_forever()
+    except KeyboardInterrupt:
+        print("\n\nStopping...")
+        await harness.stop()
+        print("Done!")
+
+
+def main() -> None:
+    """CLI entry point."""
+    parser = argparse.ArgumentParser(
+        description="AMIAI Tool Harness - Run local tools for AI agents"
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Commands")
+    
+    # dev command
+    dev_parser = subparsers.add_parser("dev", help="Run the tool harness")
+    dev_parser.add_argument(
+        "--pattern",
+        "-p",
+        action="append",
+        default=None,
+        help="Glob pattern for tool files (default: **/*.tool.py, **/tools/*.py)",
+    )
+    dev_parser.add_argument(
+        "--url",
+        default=os.environ.get("AMIAI_URL", "wss://backend.amiai.com/api/tools/live"),
+        help="AMIAI WebSocket URL",
+    )
+    
+    args = parser.parse_args()
+    
+    if args.command is None:
+        parser.print_help()
+        sys.exit(1)
+    
+    if args.command == "dev":
+        api_key = os.environ.get("AMIAI_API_KEY")
+        if not api_key:
+            print("Error: AMIAI_API_KEY environment variable is required")
+            print("\nUsage:")
+            print("  export AMIAI_API_KEY=amiai_xxx")
+            print("  amiai dev")
+            sys.exit(1)
+        
+        patterns = args.pattern or ["**/*.tool.py", "**/tools/*.py"]
+        tools = discover_tools(patterns)
+        
+        asyncio.run(run_harness(api_key, tools, args.url))
+
+
+if __name__ == "__main__":
+    main()

amiai_sdk/harness.py

@@ -0,0 +1,321 @@
+"""
+AMIAI Harness - WebSocket client for local tool execution
+
+Connects to AMIAI backend and registers tools. When the agent needs to
+call a tool, the invocation is routed here and executed locally.
+"""
+
+import asyncio
+import json
+import logging
+from typing import Any, Callable, Dict, List, Optional
+from dataclasses import dataclass, field
+
+import websockets
+from websockets.client import WebSocketClientProtocol
+
+from .tool import Tool
+
+logger = logging.getLogger("amiai_sdk")
+
+DEFAULT_URL = "wss://backend.amiai.com/api/tools/live"
+RECONNECT_DELAY_SEC = 5
+HEARTBEAT_INTERVAL_SEC = 30
+
+
+@dataclass
+class HarnessOptions:
+    """Configuration for the Harness."""
+    api_key: str
+    tools: List[Tool]
+    url: str = DEFAULT_URL
+    on_connect: Optional[Callable[[str], None]] = None
+    on_disconnect: Optional[Callable[[], None]] = None
+    on_invoke: Optional[Callable[[str, Dict[str, Any]], None]] = None
+    on_result: Optional[Callable[[str, Any], None]] = None
+    on_error: Optional[Callable[[Exception], None]] = None
+    auto_reconnect: bool = True
+
+
+class Harness:
+    """
+    WebSocket client for local tool execution.
+    
+    Example:
+        harness = Harness(
+            api_key="amiai_xxx",
+            tools=[my_tool],
+            on_connect=lambda sid: print(f"Connected: {sid}"),
+        )
+        await harness.start()
+    """
+    
+    def __init__(
+        self,
+        api_key: str,
+        tools: List[Tool],
+        url: str = DEFAULT_URL,
+        on_connect: Optional[Callable[[str], None]] = None,
+        on_disconnect: Optional[Callable[[], None]] = None,
+        on_invoke: Optional[Callable[[str, Dict[str, Any]], None]] = None,
+        on_result: Optional[Callable[[str, Any], None]] = None,
+        on_error: Optional[Callable[[Exception], None]] = None,
+        auto_reconnect: bool = True,
+    ):
+        self.api_key = api_key
+        self.tools = {t.name: t for t in tools}
+        self.tools_list = tools
+        self.url = url
+        self.on_connect = on_connect
+        self.on_disconnect = on_disconnect
+        self.on_invoke = on_invoke
+        self.on_result = on_result
+        self.on_error = on_error
+        self.auto_reconnect = auto_reconnect
+        
+        self._ws: Optional[WebSocketClientProtocol] = None
+        self._session_id: Optional[str] = None
+        self._running = False
+        self._heartbeat_task: Optional[asyncio.Task] = None
+        self._receive_task: Optional[asyncio.Task] = None
+    
+    @property
+    def session_id(self) -> Optional[str]:
+        """Get the current session ID."""
+        return self._session_id
+    
+    @property
+    def is_connected(self) -> bool:
+        """Check if connected to AMIAI."""
+        return self._ws is not None and self._session_id is not None
+    
+    async def start(self) -> str:
+        """
+        Start the harness and connect to AMIAI.
+        
+        Returns:
+            The session ID
+        """
+        self._running = True
+        return await self._connect()
+    
+    async def stop(self) -> None:
+        """Stop the harness and disconnect."""
+        self._running = False
+        self.auto_reconnect = False
+        
+        if self._heartbeat_task:
+            self._heartbeat_task.cancel()
+            try:
+                await self._heartbeat_task
+            except asyncio.CancelledError:
+                pass
+        
+        if self._receive_task:
+            self._receive_task.cancel()
+            try:
+                await self._receive_task
+            except asyncio.CancelledError:
+                pass
+        
+        if self._ws:
+            await self._ws.close()
+            self._ws = None
+        
+        self._session_id = None
+    
+    async def run_forever(self) -> None:
+        """Run the harness until stopped."""
+        await self.start()
+        
+        while self._running:
+            await asyncio.sleep(1)
+    
+    async def _connect(self) -> str:
+        """Connect to AMIAI and register tools."""
+        try:
+            self._ws = await websockets.connect(self.url)
+            
+            # Send hello
+            await self._send({
+                "type": "hello",
+                "apiKey": self.api_key,
+                "tools": [t.to_manifest() for t in self.tools_list],
+            })
+            
+            # Wait for ack
+            response = await self._ws.recv()
+            message = json.loads(response)
+            
+            if message.get("type") == "ack":
+                self._session_id = message.get("sessionId")
+                if self._session_id and self.on_connect:
+                    self.on_connect(self._session_id)
+                
+                # Start background tasks
+                self._heartbeat_task = asyncio.create_task(self._heartbeat_loop())
+                self._receive_task = asyncio.create_task(self._receive_loop())
+                
+                return self._session_id or ""
+            elif message.get("type") == "error":
+                raise Exception(f"Connection error: {message.get('message')}")
+            else:
+                raise Exception(f"Unexpected response: {message}")
+                
+        except Exception as e:
+            if self.on_error:
+                self.on_error(e)
+            raise
+    
+    async def _send(self, message: Dict[str, Any]) -> None:
+        """Send a message to the server."""
+        if self._ws:
+            await self._ws.send(json.dumps(message))
+    
+    async def _heartbeat_loop(self) -> None:
+        """Send periodic heartbeats."""
+        while self._running and self._ws:
+            try:
+                await asyncio.sleep(HEARTBEAT_INTERVAL_SEC)
+                await self._send({"type": "heartbeat"})
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.debug(f"Heartbeat error: {e}")
+    
+    async def _receive_loop(self) -> None:
+        """Receive and handle messages from server."""
+        while self._running and self._ws:
+            try:
+                message_str = await self._ws.recv()
+                message = json.loads(message_str)
+                await self._handle_message(message)
+            except websockets.ConnectionClosed:
+                logger.info("Connection closed")
+                self._session_id = None
+                if self.on_disconnect:
+                    self.on_disconnect()
+                
+                if self.auto_reconnect and self._running:
+                    await self._reconnect()
+                break
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error(f"Receive error: {e}")
+                if self.on_error:
+                    self.on_error(e)
+    
+    async def _reconnect(self) -> None:
+        """Attempt to reconnect after disconnection."""
+        logger.info(f"Reconnecting in {RECONNECT_DELAY_SEC}s...")
+        await asyncio.sleep(RECONNECT_DELAY_SEC)
+        
+        if self._running:
+            try:
+                await self._connect()
+            except Exception as e:
+                logger.error(f"Reconnection failed: {e}")
+                if self._running:
+                    await self._reconnect()
+    
+    async def _handle_message(self, message: Dict[str, Any]) -> None:
+        """Handle an incoming message."""
+        msg_type = message.get("type")
+        
+        if msg_type == "invoke":
+            call_id = message.get("callId")
+            tool_name = message.get("tool")
+            args = message.get("args", {})
+            
+            if call_id and tool_name:
+                await self._handle_invoke(call_id, tool_name, args)
+        
+        elif msg_type == "cancel":
+            call_id = message.get("callId")
+            logger.info(f"Cancellation requested for {call_id}")
+        
+        elif msg_type == "ping":
+            await self._send({"type": "heartbeat"})
+        
+        elif msg_type == "error":
+            error_msg = message.get("message", "Unknown error")
+            logger.error(f"Server error: {error_msg}")
+            if self.on_error:
+                self.on_error(Exception(error_msg))
+    
+    async def _handle_invoke(
+        self,
+        call_id: str,
+        tool_name: str,
+        args: Dict[str, Any],
+    ) -> None:
+        """Handle a tool invocation."""
+        tool = self.tools.get(tool_name)
+        
+        if not tool:
+            await self._send({
+                "type": "error",
+                "callId": call_id,
+                "message": f"Tool not found: {tool_name}",
+            })
+            return
+        
+        if self.on_invoke:
+            self.on_invoke(tool_name, args)
+        
+        try:
+            # Send started event
+            await self._send({
+                "type": "event",
+                "callId": call_id,
+                "event": "started",
+                "data": {"tool": tool_name},
+            })
+            
+            # Execute the tool
+            if asyncio.iscoroutinefunction(tool.execute):
+                result = await tool.execute(**args)
+            else:
+                result = tool.execute(**args)
+            
+            # Send result
+            await self._send({
+                "type": "result",
+                "callId": call_id,
+                "output": result,
+            })
+            
+            if self.on_result:
+                self.on_result(tool_name, result)
+                
+        except Exception as e:
+            error_msg = str(e)
+            await self._send({
+                "type": "error",
+                "callId": call_id,
+                "message": error_msg,
+            })
+            
+            if self.on_error:
+                self.on_error(e)
+
+
+async def start_harness(
+    api_key: str,
+    tools: List[Tool],
+    url: str = DEFAULT_URL,
+    **kwargs,
+) -> Harness:
+    """
+    Create and start a harness.
+    
+    Example:
+        harness = await start_harness(
+            api_key="amiai_xxx",
+            tools=[my_tool],
+        )
+    """
+    harness = Harness(api_key=api_key, tools=tools, url=url, **kwargs)
+    await harness.start()
+    return harness

amiai_sdk/tool.py

@@ -0,0 +1,147 @@
+"""
+Tool definition and decorator for AMIAI SDK
+
+Example:
+    from amiai_sdk import tool
+
+    @tool(name="calculator", description="Evaluate math expressions")
+    async def calculate(expression: str) -> dict:
+        result = eval(expression)
+        return {"expression": expression, "result": result}
+"""
+
+from typing import Any, Callable, Dict, List, Optional, Type, get_type_hints
+from dataclasses import dataclass
+import inspect
+import json
+
+
+@dataclass
+class InputField:
+    """Schema for a tool input field."""
+    type: str
+    description: Optional[str] = None
+    required: bool = True
+    default: Any = None
+    enum: Optional[List[str]] = None
+
+
+@dataclass
+class Tool:
+    """A tool that can be registered with AMIAI."""
+    name: str
+    description: str
+    input_schema: Dict[str, Any]
+    execute: Callable[..., Any]
+
+    def to_manifest(self) -> Dict[str, Any]:
+        """Convert to manifest format for registration."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "inputSchema": self.input_schema,
+        }
+
+
+def _python_type_to_json_type(python_type: Type) -> str:
+    """Convert Python type hints to JSON Schema types."""
+    type_map = {
+        str: "string",
+        int: "number",
+        float: "number",
+        bool: "boolean",
+        list: "array",
+        dict: "object",
+        List: "array",
+        Dict: "object",
+    }
+    
+    # Handle generic types like List[str], Dict[str, Any]
+    origin = getattr(python_type, "__origin__", None)
+    if origin is not None:
+        if origin is list:
+            return "array"
+        if origin is dict:
+            return "object"
+    
+    return type_map.get(python_type, "string")
+
+
+def _derive_schema_from_function(func: Callable) -> Dict[str, Any]:
+    """Derive JSON Schema from function signature."""
+    sig = inspect.signature(func)
+    hints = get_type_hints(func) if hasattr(func, "__annotations__") else {}
+    
+    properties: Dict[str, Any] = {}
+    required: List[str] = []
+    
+    for name, param in sig.parameters.items():
+        if name in ("self", "cls"):
+            continue
+        
+        # Get type from hints or default to string
+        param_type = hints.get(name, str)
+        json_type = _python_type_to_json_type(param_type)
+        
+        properties[name] = {
+            "type": json_type,
+        }
+        
+        # Check if parameter has a default
+        if param.default is inspect.Parameter.empty:
+            required.append(name)
+        else:
+            properties[name]["default"] = param.default
+    
+    return {
+        "type": "object",
+        "properties": properties,
+        "required": required,
+    }
+
+
+def tool(
+    name: str,
+    description: str,
+    input_schema: Optional[Dict[str, Any]] = None,
+) -> Callable[[Callable], Tool]:
+    """
+    Decorator to define a tool for AMIAI agents.
+    
+    Args:
+        name: Unique name for the tool
+        description: Description shown to the AI
+        input_schema: Optional JSON Schema for inputs (auto-derived if not provided)
+    
+    Example:
+        @tool(name="web_search", description="Search the web")
+        async def search(query: str) -> dict:
+            response = await fetch(f"https://api.example.com/search?q={query}")
+            return response.json()
+    
+    Example with explicit schema:
+        @tool(
+            name="calculator",
+            description="Evaluate math expressions",
+            input_schema={
+                "type": "object",
+                "properties": {
+                    "expression": {"type": "string", "description": "e.g., 2+2"}
+                },
+                "required": ["expression"]
+            }
+        )
+        async def calculate(expression: str) -> dict:
+            return {"result": eval(expression)}
+    """
+    def decorator(func: Callable) -> Tool:
+        schema = input_schema or _derive_schema_from_function(func)
+        
+        return Tool(
+            name=name,
+            description=description,
+            input_schema=schema,
+            execute=func,
+        )
+    
+    return decorator