scope-oaf 0.1.0__tar.gz

scope_oaf-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,53 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build release distributions
+        run: |
+          python -m pip install build
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      id-token: write
+
+    environment:
+      name: pypi
+      url: https://pypi.org/p/scope-oaf
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

scope_oaf-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+
+# Testing
+.pytest_cache/
+htmlcov/
+.coverage

scope_oaf-0.1.0/DESIGN.md

@@ -0,0 +1,594 @@
+# OpenAgentFramework (OAF) — Design Document
+
+## Vision
+
+A minimal, fast, transparent agent framework built on top of `llmclient`. Unlike LangChain's deep abstraction layers, OAF is **flat, debuggable, and composable** — you can always see exactly what's happening.
+
+```
+┌──────────────────────────────────────────────────┐
+│                  Your Application                │
+├──────────────────────────────────────────────────┤
+│              OpenAgentFramework (OAF)            │
+│  ┌──────────┐ ┌──────────┐ ┌───────────────┐    │
+│  │  Agents  │ │  Tools   │ │    Context     │    │
+│  │          │ │          │ │  Engineering   │    │
+│  └──────────┘ └──────────┘ └───────────────┘    │
+├──────────────────────────────────────────────────┤
+│                  llmclient                       │
+│          (OpenAI + Anthropic SDKs)               │
+└──────────────────────────────────────────────────┘
+```
+
+---
+
+## Core Principles
+
+1. **No magic** — Every prompt, tool call, and decision is inspectable via `request_payload` and event hooks
+2. **Parallel by default** — Multiple tool calls execute concurrently with `asyncio.gather`
+3. **Context is king** — Smart context window management, not naive concatenation
+4. **Tools are just functions** — Decorate any async/sync function → it's a tool
+5. **Composable agents** — Agents can call other agents as tools (agent-as-a-tool)
+6. **Provider agnostic** — Works with any model via `llmclient`
+
+---
+
+## Architecture
+
+### Directory Structure
+
+```
+oaf/
+├── __init__.py
+├── agent.py            # Agent class — the core loop
+├── tool.py             # @tool decorator, ToolDef, ToolResult
+├── context.py          # ContextWindow — smart prompt assembly
+├── memory.py           # Conversation + long-term memory
+├── hooks.py            # Event system (before_call, after_call, on_tool, on_error)
+├── router.py           # Multi-agent routing / handoff
+├── types.py            # AgentResponse, Turn, ToolCall, etc.
+├── errors.py           # Agent-level errors
+└── tools/              # Built-in tool library
+    ├── __init__.py
+    ├── web.py           # web_search, fetch_url, scrape
+    ├── filesystem.py    # read_file, write_file, list_dir
+    ├── code.py          # python_exec, shell_exec
+    ├── math.py          # calculator, unit_convert
+    └── time.py          # current_time, sleep, timer
+```
+
+---
+
+## 1. Tool System
+
+### 1.1 Tool Definition — `@tool` Decorator
+
+Tools are just functions. The decorator extracts the JSON schema from type hints and docstring automatically.
+
+```python
+from oaf import tool
+
+@tool
+async def get_weather(city: str, units: str = "celsius") -> str:
+    """Get the current weather for a city.
+    
+    Args:
+        city: The city name (e.g. "Tokyo", "New York")
+        units: Temperature units — "celsius" or "fahrenheit"
+    """
+    # your implementation
+    return f"72°F in {city}"
+
+# What the decorator produces internally:
+# ToolDef(
+#     name="get_weather",
+#     description="Get the current weather for a city.",
+#     parameters={
+#         "type": "object",
+#         "properties": {
+#             "city": {"type": "string", "description": "The city name (e.g. \"Tokyo\", \"New York\")"},
+#             "units": {"type": "string", "description": "Temperature units", "default": "celsius"}
+#         },
+#         "required": ["city"]
+#     },
+#     fn=get_weather
+# )
+```
+
+### 1.2 Tool Types
+
+```python
+@dataclass
+class ToolDef:
+    name: str
+    description: str
+    parameters: dict[str, Any]          # JSON Schema
+    fn: Callable                         # the actual function
+    requires_confirmation: bool = False  # ask user before executing
+    timeout: float = 30.0               # per-call timeout
+    
+@dataclass
+class ToolCall:
+    id: str
+    name: str
+    arguments: dict[str, Any]
+
+@dataclass
+class ToolResult:
+    tool_call_id: str
+    name: str
+    content: str                         # stringified result
+    is_error: bool = False
+    duration_ms: float = 0
+```
+
+### 1.3 Parallel Tool Execution
+
+When the model returns multiple tool calls in a single response, they execute in parallel:
+
+```python
+# Inside the agent loop:
+async def _execute_tools(self, tool_calls: list[ToolCall]) -> list[ToolResult]:
+    """Execute all tool calls concurrently."""
+    tasks = [self._execute_one(tc) for tc in tool_calls]
+    return await asyncio.gather(*tasks)
+
+async def _execute_one(self, tc: ToolCall) -> ToolResult:
+    tool = self._tools[tc.name]
+    try:
+        result = await asyncio.wait_for(
+            tool.fn(**tc.arguments),
+            timeout=tool.timeout,
+        )
+        return ToolResult(
+            tool_call_id=tc.id,
+            name=tc.name,
+            content=str(result),
+        )
+    except Exception as e:
+        return ToolResult(
+            tool_call_id=tc.id,
+            name=tc.name,
+            content=f"Error: {e}",
+            is_error=True,
+        )
+```
+
+### 1.4 Sync Function Support
+
+Sync tools run in the thread pool automatically:
+
+```python
+@tool
+def read_file(path: str) -> str:
+    """Read a file from disk."""
+    return open(path).read()
+
+# Internally wraps with asyncio.to_thread:
+# async def wrapper(**kwargs):
+#     return await asyncio.to_thread(original_fn, **kwargs)
+```
+
+---
+
+## 2. Agent — The Core Loop
+
+### 2.1 Agent Class
+
+```python
+class Agent:
+    def __init__(
+        self,
+        name: str = "agent",
+        model: str = "gpt-4.1-nano",
+        system: str = "",
+        tools: list[ToolDef] = [],
+        context: ContextWindow | None = None,
+        hooks: Hooks | None = None,
+        max_turns: int = 20,            # safety limit
+        max_parallel_tools: int = 10,   # concurrency cap
+        client: LLMClient | None = None,
+    ): ...
+    
+    async def run(self, message: str, **kwargs) -> AgentResponse:
+        """Run the agent loop to completion."""
+        ...
+    
+    async def run_stream(self, message: str, **kwargs) -> AsyncIterator[AgentEvent]:
+        """Stream the agent loop — yields events as they happen."""
+        ...
+```
+
+### 2.2 Agent Loop (the core)
+
+```
+User message
+    │
+    ▼
+┌─────────────────────────┐
+│   Assemble context      │◄──── ContextWindow manages what fits
+│   (system + history +   │
+│    tool defs + user msg) │
+└────────────┬────────────┘
+             │
+             ▼
+┌─────────────────────────┐
+│   LLM call via          │
+│   llmclient.chat()      │──── request_payload available for inspection
+└────────────┬────────────┘
+             │
+         ┌───┴───┐
+         │       │
+    text only   tool_calls
+         │       │
+         ▼       ▼
+      Return  ┌──────────────────┐
+              │ Execute tools    │
+              │ (parallel)       │
+              └────────┬─────────┘
+                       │
+                       ▼
+              ┌──────────────────┐
+              │ Append results   │
+              │ to conversation  │
+              └────────┬─────────┘
+                       │
+                       ▼
+              Loop back to "Assemble context"
+              (until text response or max_turns)
+```
+
+### 2.3 Agent Response
+
+```python
+@dataclass
+class Turn:
+    """One LLM call + its tool executions."""
+    request_payload: dict[str, Any]      # what was sent to the API
+    response: ChatResponse               # raw llmclient response
+    tool_calls: list[ToolCall]           # tools the model requested
+    tool_results: list[ToolResult]       # results from execution
+    duration_ms: float
+
+@dataclass 
+class AgentResponse:
+    text: str                            # final text answer
+    turns: list[Turn]                    # full history of all turns
+    total_tokens: int                    # sum of all turns
+    total_duration_ms: float
+    model: str
+```
+
+---
+
+## 3. Context Engineering
+
+### 3.1 ContextWindow
+
+The most important part. Naive frameworks just concatenate everything and hit token limits. OAF actively manages what goes into the prompt.
+
+```python
+class ContextWindow:
+    def __init__(
+        self,
+        max_tokens: int = 128_000,      # model context limit
+        reserve_output: int = 4_096,     # tokens reserved for response
+        strategy: str = "sliding",       # "sliding" | "summary" | "priority"
+    ): ...
+    
+    def assemble(
+        self,
+        system: str,
+        tools: list[ToolDef],
+        history: list[Message],
+        user_message: str,
+    ) -> list[Message]:
+        """Build the final message list that fits within the token budget."""
+        ...
+```
+
+### 3.2 Strategies
+
+| Strategy | How it works | Best for |
+|----------|-------------|----------|
+| `sliding` | Keeps system + tools + last N turns that fit | Most use cases |
+| `summary` | When history overflows, summarize older turns into a condensed message | Long conversations |
+| `priority` | Each message has a priority score; lowest priority gets dropped first | Complex multi-step tasks |
+
+### 3.3 Token Counting
+
+```python
+class TokenCounter:
+    """Fast approximate token counting (no tiktoken dependency required)."""
+    
+    @staticmethod
+    def estimate(text: str) -> int:
+        """~4 chars per token heuristic, good enough for budget decisions."""
+        return len(text) // 4
+    
+    @staticmethod
+    def exact(text: str, model: str) -> int:
+        """Exact count via tiktoken (optional dependency)."""
+        import tiktoken
+        enc = tiktoken.encoding_for_model(model)
+        return len(enc.encode(text))
+```
+
+### 3.4 Assembled Prompt Inspection
+
+Every agent response includes the full request payload so you can see exactly what was sent:
+
+```python
+result = await agent.run("What's the weather in Tokyo and NYC?")
+
+# See exactly what the model received on each turn:
+for i, turn in enumerate(result.turns):
+    print(f"Turn {i}: {len(turn.request_payload['messages'])} messages")
+    print(f"  Tools called: {[tc.name for tc in turn.tool_calls]}")
+    print(f"  Payload: {turn.request_payload}")
+```
+
+---
+
+## 4. Event Hooks
+
+### 4.1 Hook System
+
+Hooks let you observe/modify behavior without subclassing:
+
+```python
+@dataclass
+class Hooks:
+    before_llm_call: Callable | None = None     # (messages, tools) → messages
+    after_llm_call: Callable | None = None      # (response) → None
+    before_tool_call: Callable | None = None    # (tool_call) → tool_call | None (None = skip)
+    after_tool_call: Callable | None = None     # (tool_call, result) → result
+    on_error: Callable | None = None            # (error) → None
+    on_turn_complete: Callable | None = None    # (turn) → None
+```
+
+### 4.2 Example: Logging Hook
+
+```python
+async def log_everything(response):
+    print(f"[LLM] {response.model} → {response.usage.total_tokens} tokens")
+    print(f"[LLM] {response.text[:100]}...")
+
+agent = Agent(
+    model="gpt-4.1-nano",
+    tools=[get_weather],
+    hooks=Hooks(after_llm_call=log_everything),
+)
+```
+
+### 4.3 Example: Confirmation Hook
+
+```python
+async def confirm_dangerous(tool_call):
+    if tool_call.name in ("shell_exec", "write_file"):
+        answer = input(f"Allow {tool_call.name}({tool_call.arguments})? [y/n] ")
+        if answer != "y":
+            return None  # skip this tool call
+    return tool_call
+
+agent = Agent(
+    tools=[shell_exec, write_file, read_file],
+    hooks=Hooks(before_tool_call=confirm_dangerous),
+)
+```
+
+---
+
+## 5. Streaming Events
+
+For real-time UIs, `run_stream` yields typed events:
+
+```python
+class AgentEvent:
+    type: str   # "text_delta" | "tool_start" | "tool_end" | "turn_end" | "error" | "done"
+
+async for event in agent.run_stream("Analyze this data"):
+    match event.type:
+        case "text_delta":
+            print(event.text, end="", flush=True)
+        case "tool_start":
+            print(f"\n🔧 Calling {event.tool_call.name}...")
+        case "tool_end":
+            print(f"  ✓ {event.result.content[:100]}")
+        case "done":
+            print(f"\n[{event.total_tokens} tokens, {event.turns} turns]")
+```
+
+---
+
+## 6. Multi-Agent / Router
+
+### 6.1 Agent-as-a-Tool
+
+Any agent can be exposed as a tool for another agent:
+
+```python
+researcher = Agent(
+    name="researcher",
+    model="gpt-4.1-mini",
+    system="You research topics thoroughly using web search.",
+    tools=[web_search, fetch_url],
+)
+
+writer = Agent(
+    name="writer",
+    model="gpt-4.1-nano",
+    system="You write polished content based on research.",
+    tools=[researcher.as_tool()],  # researcher becomes a callable tool
+)
+
+result = await writer.run("Write a blog post about quantum computing")
+```
+
+### 6.2 Router Agent
+
+A router dispatches to specialized agents:
+
+```python
+router = Router(
+    agents=[researcher, writer, coder, analyst],
+    model="gpt-4.1-nano",   # cheap model for routing decisions
+)
+
+# Router picks the right agent based on the query
+result = await router.run("Debug this Python error: ...")
+# → Routes to coder agent
+```
+
+---
+
+## 7. Built-in Tools
+
+### Standard Library
+
+| Tool | Module | Description |
+|------|--------|-------------|
+| `web_search` | `tools.web` | Search the web (via SerpAPI/Tavily) |
+| `fetch_url` | `tools.web` | Fetch and extract text from a URL |
+| `read_file` | `tools.filesystem` | Read a file |
+| `write_file` | `tools.filesystem` | Write/create a file |
+| `list_dir` | `tools.filesystem` | List directory contents |
+| `python_exec` | `tools.code` | Execute Python code in a sandbox |
+| `shell_exec` | `tools.code` | Run a shell command |
+| `calculator` | `tools.math` | Evaluate math expressions safely |
+| `current_time` | `tools.time` | Get current date/time |
+
+All built-in tools are opt-in — you import only what you need:
+
+```python
+from oaf.tools.web import web_search, fetch_url
+from oaf.tools.filesystem import read_file, write_file
+```
+
+---
+
+## 8. Memory
+
+### 8.1 Conversation Memory
+
+Tracks the full history of the current session:
+
+```python
+class ConversationMemory:
+    messages: list[Message]
+    
+    def add(self, message: Message) -> None: ...
+    def get_recent(self, n: int) -> list[Message]: ...
+    def summarize(self, model: str) -> str: ...  # compress old history
+    def clear(self) -> None: ...
+    def save(self, path: str) -> None: ...
+    def load(self, path: str) -> None: ...
+```
+
+### 8.2 Persistent Memory (Key-Value)
+
+For facts that persist across conversations:
+
+```python
+class PersistentMemory:
+    """SQLite-backed key-value store."""
+    
+    def store(self, key: str, value: str, metadata: dict = {}) -> None: ...
+    def recall(self, query: str, top_k: int = 5) -> list[MemoryEntry]: ...
+    def forget(self, key: str) -> None: ...
+```
+
+---
+
+## 9. Usage Examples
+
+### 9.1 Simple Agent
+
+```python
+from oaf import Agent, tool
+
+@tool
+async def get_weather(city: str) -> str:
+    """Get weather for a city."""
+    return f"Sunny, 72°F in {city}"
+
+agent = Agent(
+    model="gpt-4.1-nano",
+    system="You are a helpful assistant.",
+    tools=[get_weather],
+)
+
+result = await agent.run("What's the weather in Tokyo?")
+print(result.text)
+# "The weather in Tokyo is sunny and 72°F!"
+print(result.turns[0].tool_calls[0].name)
+# "get_weather"
+```
+
+### 9.2 Parallel Tool Calls
+
+```python
+result = await agent.run("What's the weather in Tokyo, NYC, and London?")
+# Model returns 3 tool_calls → all 3 execute in parallel
+print(len(result.turns[0].tool_calls))  # 3
+print(result.turns[0].tool_results)     # all 3 results, fetched concurrently
+```
+
+### 9.3 Full Inspection
+
+```python
+result = await agent.run("Analyze the weather patterns")
+
+for turn in result.turns:
+    print(f"=== Turn ===")
+    print(f"Prompt: {turn.request_payload}")
+    print(f"Response: {turn.response.text}")
+    for tc, tr in zip(turn.tool_calls, turn.tool_results):
+        print(f"  Tool: {tc.name}({tc.arguments}) → {tr.content}")
+print(f"Total: {result.total_tokens} tokens, {len(result.turns)} turns")
+```
+
+---
+
+## 10. Implementation Priority
+
+### Phase 1 — Core (build first)
+1. `tool.py` — `@tool` decorator, schema extraction from type hints
+2. `types.py` — `ToolDef`, `ToolCall`, `ToolResult`, `Turn`, `AgentResponse`, `AgentEvent`
+3. `agent.py` — Agent loop with parallel tool execution
+4. `context.py` — `ContextWindow` with sliding strategy
+
+### Phase 2 — Usability
+5. `hooks.py` — Event hooks
+6. `memory.py` — Conversation memory
+7. Streaming (`run_stream` + `AgentEvent`)
+
+### Phase 3 — Power Features
+8. `router.py` — Multi-agent routing, agent-as-a-tool
+9. `tools/` — Built-in tool library
+10. `memory.py` — Persistent memory with embeddings search
+
+---
+
+## 11. Dependencies
+
+| Package | Purpose | Required? |
+|---------|---------|-----------|
+| `llmclient` | LLM calls (already built) | Yes |
+| `docstring-parser` | Extract param docs from docstrings | Yes |
+| `tiktoken` | Exact token counting | Optional |
+| `aiosqlite` | Persistent memory storage | Optional |
+| `httpx` | Built-in web tools | Optional |
+
+---
+
+## 12. Anti-Patterns to Avoid (lessons from LangChain)
+
+| LangChain problem | OAF solution |
+|-------------------|-------------|
+| 15 abstraction layers deep | **Flat** — Agent → LLMClient, that's it |
+| Can't see the prompt | **`request_payload`** on every response and turn |
+| "Chain" concept is confusing | **Agent loop** — one clear concept |
+| Massive dependency tree | **Minimal deps** — just llmclient + docstring-parser |
+| Hard to debug tool errors | **`ToolResult.is_error`** + hooks + full turn history |
+| Sequential tool execution | **Parallel by default** with `asyncio.gather` |
+| Opaque memory management | **Explicit `ContextWindow`** with inspectable strategy |

scope_oaf-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 devin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.