pop-framework 0.1.0__tar.gz

pop_framework-0.1.0/.claude/scheduled_tasks.lock

@@ -0,0 +1 @@
+{"sessionId":"8ece6f4d-7253-482f-a1fe-c9f20d8e45ae","pid":82460,"acquiredAt":1774307712777}

pop_framework-0.1.0/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python benchmarks/bench_startup.py)"
+    ]
+  }
+}

pop_framework-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Type checking & linting
+.mypy_cache/
+.ruff_cache/
+
+# Environment
+.env
+.env.local
+.venv/
+venv/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo

pop_framework-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

pop_framework-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chester Lee
+
+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.

pop_framework-0.1.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: pop-framework
+Version: 0.1.0
+Summary: Fast, lean AI agents. 5 lines to production.
+Project-URL: Homepage, https://github.com/WYSIATI/pop
+Project-URL: Documentation, https://github.com/WYSIATI/pop/tree/main/docs
+Project-URL: Repository, https://github.com/WYSIATI/pop
+Project-URL: Issues, https://github.com/WYSIATI/pop/issues
+Author: Chester Lee
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,anthropic,framework,llm,openai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Provides-Extra: all
+Requires-Dist: anthropic>=0.30; extra == 'all'
+Requires-Dist: google-genai>=1.0; extra == 'all'
+Requires-Dist: openai>=1.0; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.30; extra == 'anthropic'
+Provides-Extra: gemini
+Requires-Dist: google-genai>=1.0; extra == 'gemini'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/logo.svg" alt="pop" width="300">
+</p>
+
+<p align="center">
+  <em>Fast, lean AI agents. 5 lines to production.</em>
+</p>
+
+<p align="center">
+  <a href="https://github.com/WYSIATI/pop/actions"><img src="https://img.shields.io/github/actions/workflow/status/WYSIATI/pop/ci.yml?label=CI" alt="CI"></a>
+  <a href="https://github.com/WYSIATI/pop"><img src="https://img.shields.io/badge/coverage-99%25-brightgreen" alt="Coverage"></a>
+  <a href="https://pypi.org/project/pop-framework/"><img src="https://img.shields.io/pypi/v/pop-framework" alt="PyPI"></a>
+  <a href="https://pypi.org/project/pop-framework/"><img src="https://img.shields.io/pypi/pyversions/pop-framework" alt="Python"></a>
+  <img src="https://img.shields.io/badge/license-MIT-blue" alt="License">
+</p>
+
+<p align="center">
+  <a href="docs/">Documentation</a> |
+  <a href="https://github.com/WYSIATI/pop">Source Code</a> |
+  <a href="https://discord.gg/pop">Discord</a>
+</p>
+
+---
+
+**pop** is a lightweight Python framework for building AI agents. It supports multiple LLM providers, has 5 core concepts, and gets you from install to a working agent in under 2 minutes.
+
+## Why pop?
+
+- **5 lines to a working agent** -- define a tool, create an agent, call `run`.
+- **7 LLM providers built-in** -- OpenAI, Anthropic, Gemini, DeepSeek, Kimi, MiniMax, GLM. Switch by changing one string.
+- **~2,500 lines of code** -- read the entire framework in an afternoon.
+- **2 runtime dependencies** -- `httpx` and `pydantic`. Import time under 1ms (lazy imports).
+- **Zero commercial dependencies** -- no forced telemetry, no vendor lock-in.
+
+## Install
+
+```bash
+# Recommended
+uv add pop-framework
+
+# With a provider extra
+uv add "pop-framework[openai]"
+uv add "pop-framework[anthropic]"
+uv add "pop-framework[all]"
+```
+
+Or with pip:
+
+```bash
+pip install pop-framework
+pip install "pop-framework[openai]"
+```
+
+## Quick Start
+
+```python
+from pop import Agent, tool
+
+@tool
+def search(query: str) -> str:
+    """Search the web for current information."""
+    return web_search(query)  # your implementation
+
+agent = Agent(model="openai:gpt-4o", tools=[search])
+result = agent.run("What happened in AI today?")
+print(result.output)
+```
+
+That's it. No `StateGraph`, no `RunnableSequence`, no `ChannelWrite`.
+
+## Docs
+
+| Guide | What it covers |
+|-------|---------------|
+| [Providers](docs/providers.md) | Switching LLMs, failover, model adapters |
+| [Streaming](docs/streaming.md) | Real-time events, pattern matching |
+| [Workflows](docs/workflows.md) | Chain, route, parallel, agent, orchestration |
+| [Multi-Agent](docs/multi-agent.md) | Handoff, pipeline, debate, fan_out |
+| [Memory](docs/memory.md) | In-memory and markdown-based persistence |
+| [Skills](SKILLS.md) | Complete API guide for building agents |
+| [Benchmarks](docs/benchmarks.md) | Performance numbers, framework comparison |
+
+## Benchmarks
+
+| Metric | pop | LangChain + LangGraph | Delta |
+|--------|-----|----------------------|-------|
+| Framework overhead | ~0.15ms | ~45ms | ~300x faster |
+| Import time | ~0.17ms | ~1,200ms | ~7,000x faster |
+| Lines of code (avg task) | ~12 | ~42 | 71% less |
+| Dependencies | 2 | 20+ | 90% fewer |
+
+Details: [docs/benchmarks.md](docs/benchmarks.md)
+
+## Community
+
+- [Discord](https://discord.gg/pop) -- questions, help, showcase
+- [GitHub Issues](https://github.com/WYSIATI/pop/issues) -- bug reports
+- [GitHub Discussions](https://github.com/WYSIATI/pop/discussions) -- feature ideas, Q&A
+
+## Contributing
+
+```bash
+git clone https://github.com/WYSIATI/pop.git
+cd pop
+uv sync --group dev
+uv run pytest
+```
+
+## License
+
+MIT

pop_framework-0.1.0/README.md

@@ -0,0 +1,111 @@
+<p align="center">
+  <img src="assets/logo.svg" alt="pop" width="300">
+</p>
+
+<p align="center">
+  <em>Fast, lean AI agents. 5 lines to production.</em>
+</p>
+
+<p align="center">
+  <a href="https://github.com/WYSIATI/pop/actions"><img src="https://img.shields.io/github/actions/workflow/status/WYSIATI/pop/ci.yml?label=CI" alt="CI"></a>
+  <a href="https://github.com/WYSIATI/pop"><img src="https://img.shields.io/badge/coverage-99%25-brightgreen" alt="Coverage"></a>
+  <a href="https://pypi.org/project/pop-framework/"><img src="https://img.shields.io/pypi/v/pop-framework" alt="PyPI"></a>
+  <a href="https://pypi.org/project/pop-framework/"><img src="https://img.shields.io/pypi/pyversions/pop-framework" alt="Python"></a>
+  <img src="https://img.shields.io/badge/license-MIT-blue" alt="License">
+</p>
+
+<p align="center">
+  <a href="docs/">Documentation</a> |
+  <a href="https://github.com/WYSIATI/pop">Source Code</a> |
+  <a href="https://discord.gg/pop">Discord</a>
+</p>
+
+---
+
+**pop** is a lightweight Python framework for building AI agents. It supports multiple LLM providers, has 5 core concepts, and gets you from install to a working agent in under 2 minutes.
+
+## Why pop?
+
+- **5 lines to a working agent** -- define a tool, create an agent, call `run`.
+- **7 LLM providers built-in** -- OpenAI, Anthropic, Gemini, DeepSeek, Kimi, MiniMax, GLM. Switch by changing one string.
+- **~2,500 lines of code** -- read the entire framework in an afternoon.
+- **2 runtime dependencies** -- `httpx` and `pydantic`. Import time under 1ms (lazy imports).
+- **Zero commercial dependencies** -- no forced telemetry, no vendor lock-in.
+
+## Install
+
+```bash
+# Recommended
+uv add pop-framework
+
+# With a provider extra
+uv add "pop-framework[openai]"
+uv add "pop-framework[anthropic]"
+uv add "pop-framework[all]"
+```
+
+Or with pip:
+
+```bash
+pip install pop-framework
+pip install "pop-framework[openai]"
+```
+
+## Quick Start
+
+```python
+from pop import Agent, tool
+
+@tool
+def search(query: str) -> str:
+    """Search the web for current information."""
+    return web_search(query)  # your implementation
+
+agent = Agent(model="openai:gpt-4o", tools=[search])
+result = agent.run("What happened in AI today?")
+print(result.output)
+```
+
+That's it. No `StateGraph`, no `RunnableSequence`, no `ChannelWrite`.
+
+## Docs
+
+| Guide | What it covers |
+|-------|---------------|
+| [Providers](docs/providers.md) | Switching LLMs, failover, model adapters |
+| [Streaming](docs/streaming.md) | Real-time events, pattern matching |
+| [Workflows](docs/workflows.md) | Chain, route, parallel, agent, orchestration |
+| [Multi-Agent](docs/multi-agent.md) | Handoff, pipeline, debate, fan_out |
+| [Memory](docs/memory.md) | In-memory and markdown-based persistence |
+| [Skills](SKILLS.md) | Complete API guide for building agents |
+| [Benchmarks](docs/benchmarks.md) | Performance numbers, framework comparison |
+
+## Benchmarks
+
+| Metric | pop | LangChain + LangGraph | Delta |
+|--------|-----|----------------------|-------|
+| Framework overhead | ~0.15ms | ~45ms | ~300x faster |
+| Import time | ~0.17ms | ~1,200ms | ~7,000x faster |
+| Lines of code (avg task) | ~12 | ~42 | 71% less |
+| Dependencies | 2 | 20+ | 90% fewer |
+
+Details: [docs/benchmarks.md](docs/benchmarks.md)
+
+## Community
+
+- [Discord](https://discord.gg/pop) -- questions, help, showcase
+- [GitHub Issues](https://github.com/WYSIATI/pop/issues) -- bug reports
+- [GitHub Discussions](https://github.com/WYSIATI/pop/discussions) -- feature ideas, Q&A
+
+## Contributing
+
+```bash
+git clone https://github.com/WYSIATI/pop.git
+cd pop
+uv sync --group dev
+uv run pytest
+```
+
+## License
+
+MIT

pop_framework-0.1.0/SKILLS.md

@@ -0,0 +1,368 @@
+# Skills Guide
+
+How to build AI agents with pop. This guide is written for coding agents (Claude, Cursor, Copilot) and humans alike.
+
+## 5 Core Concepts
+
+| Concept | What it does |
+|---------|-------------|
+| `Agent` | ReAct loop: thinks, calls tools, repeats until done |
+| `@tool` | Turns a Python function into a tool the LLM can call |
+| `Runner` | Streams events from an agent run |
+| Memory | Pluggable storage (in-memory or markdown files) |
+| Patterns | Multi-agent composition: `handoff`, `pipeline`, `debate`, `orchestrate`, `fan_out` |
+
+## Install
+
+```bash
+uv add pop-framework
+# With a provider
+uv add "pop-framework[openai]"
+uv add "pop-framework[anthropic]"
+```
+
+## 1. Minimal Agent
+
+```python
+from pop import Agent, tool
+
+@tool
+def add(a: float, b: float) -> float:
+    """Add two numbers.
+
+    Args:
+        a: First number.
+        b: Second number.
+    """
+    return a + b
+
+agent = Agent(model="openai:gpt-4o-mini", tools=[add])
+result = agent.run("What is 42 + 17?")
+print(result.output)
+```
+
+**Key points:**
+- `@tool` reads the function signature and docstring to generate JSON Schema automatically
+- Use Google-style docstrings with `Args:` section for parameter descriptions
+- `model` is a string in `provider:model-name` format
+
+## 2. Defining Tools
+
+```python
+from pop import tool
+
+# Simple tool
+@tool
+def search(query: str) -> str:
+    """Search the web."""
+    return f"Results for {query}"
+
+# Tool with optional params
+@tool
+def fetch_page(url: str, max_length: int = 5000) -> str:
+    """Fetch a web page.
+
+    Args:
+        url: The URL to fetch.
+        max_length: Max characters to return.
+    """
+    return httpx.get(url).text[:max_length]
+
+# Tool with Pydantic input
+from pydantic import BaseModel, Field
+
+class Contact(BaseModel):
+    name: str = Field(description="Full name")
+    email: str = Field(description="Email address")
+
+@tool
+def save_contact(contact: Contact) -> str:
+    """Save a contact to the database.
+
+    Args:
+        contact: Contact information.
+    """
+    return f"Saved {contact.name}"
+```
+
+**Supported types:** `str`, `int`, `float`, `bool`, `list[T]`, `dict`, Pydantic models, `Optional[T]`.
+
+## 3. Agent Configuration
+
+```python
+agent = Agent(
+    model="openai:gpt-4o",          # or "anthropic:claude-sonnet-4-20250514"
+    name="researcher",                # name for multi-agent identification
+    tools=[search, fetch_page],       # list of @tool-decorated functions
+    instructions="You are a research assistant. Cite sources.",
+    max_steps=10,                     # max ReAct loop iterations (default: 10)
+    max_cost=0.50,                    # USD budget cap (optional)
+    max_retries=3,                    # retries on transient errors
+    reflect_on_failure=False,         # enable Reflexion loop on errors
+    output_guardrails=[is_safe],      # validators for final answer
+)
+```
+
+**Model fallback:** pass a list to try models in order.
+
+```python
+agent = Agent(
+    model=["anthropic:claude-sonnet-4-20250514", "openai:gpt-4o", "openai:gpt-4o-mini"],
+    tools=[search],
+)
+```
+
+## 4. Running Agents
+
+### Sync
+
+```python
+result = agent.run("What happened in AI today?")
+print(result.output)        # final answer string
+print(result.cost)           # total USD cost
+print(result.token_usage)    # TokenUsage(input_tokens=..., output_tokens=...)
+print(result.steps)          # list[Step] -- full execution trace
+```
+
+### Async
+
+```python
+result = await agent.arun("What happened in AI today?")
+```
+
+### Streaming
+
+```python
+import asyncio
+from pop import Agent, Runner, ToolCallEvent, ToolResultEvent, TextDeltaEvent, DoneEvent, tool
+
+runner = Runner(agent)
+
+async for event in runner.stream("What should I wear in SF?"):
+    match event:
+        case ToolCallEvent(name=name, args=args):
+            print(f"Calling {name}({args})")
+        case ToolResultEvent(name=name, output=output):
+            print(f"{name} -> {output}")
+        case TextDeltaEvent(delta=text):
+            print(text, end="")
+        case DoneEvent(result=result):
+            print(f"\nCost: ${result.cost:.6f}")
+```
+
+## 5. Multi-Agent Patterns
+
+### Handoff
+
+Route to specialist agents based on the task.
+
+```python
+from pop import Agent, handoff, tool
+
+billing = Agent(model="openai:gpt-4o-mini", tools=[lookup_invoice],
+                instructions="Handle billing questions.")
+tech = Agent(model="openai:gpt-4o-mini", tools=[check_logs],
+             instructions="Handle technical issues.")
+
+triage = Agent(
+    model="openai:gpt-4o-mini",
+    tools=[
+        handoff(billing, when="billing or payment issues"),
+        handoff(tech, when="technical problems or errors"),
+    ],
+)
+result = triage.run("I was charged twice")
+```
+
+### Pipeline
+
+Sequential: each agent's output feeds into the next.
+
+```python
+from pop import Agent, pipeline
+
+result = await pipeline(
+    [researcher, writer, editor],
+    task="Report on AI agent frameworks",
+)
+```
+
+### Debate
+
+Generator proposes, critic reviews, loop until approved.
+
+```python
+from pop import Agent, debate
+
+result = await debate(writer, editor, task="Write a product announcement", max_rounds=3)
+```
+
+### Orchestrate
+
+A boss agent dynamically delegates to workers.
+
+```python
+from pop import Agent, orchestrate
+
+boss = Agent(model="openai:gpt-4o", name="boss",
+             instructions="Coordinate research, writing, and SEO.")
+result = await orchestrate(boss, [researcher, writer, seo_optimizer], task="Write a blog post")
+```
+
+### Fan Out
+
+Run multiple agents in parallel, aggregate results.
+
+```python
+from pop import Agent, fan_out
+
+result = await fan_out(
+    [analyst_a, analyst_b, analyst_c],
+    task="Analyze Q4 earnings",
+    strategy="majority",  # or "first", "weighted_vote"
+)
+```
+
+## 6. Workflows (No Agent Loop)
+
+For simpler LLM patterns that don't need tool-calling or a ReAct loop.
+
+```python
+from pop import chain, route, parallel, model
+
+m = model("openai:gpt-4o")
+
+# Chain: sequential prompts, {prev} is replaced with the previous output
+result = await chain(m, steps=[
+    "Summarize: {input}",
+    "Translate to French: {prev}",
+], input_text="...")
+
+# Route: classify and dispatch
+result = await route(m, "refund request", {
+    "refund": handle_refund,
+    "support": handle_support,
+})
+
+# Parallel: concurrent LLM calls
+results = await parallel(m, [
+    "Summarize: {context}",
+    "Extract keywords: {context}",
+], context="...")
+```
+
+## 7. Memory
+
+### In-Memory (Default)
+
+No configuration needed. State is lost when the process exits.
+
+### Markdown Memory (Persistent)
+
+```python
+from pop.memory import MarkdownMemory
+
+# Default: stores in ~/.pop/memory
+memory = MarkdownMemory()
+
+# Or specify a custom directory
+memory = MarkdownMemory(base_dir="./agent_memory")
+
+agent = Agent(
+    model="openai:gpt-4o",
+    tools=[search],
+    memory=memory,
+    core_memory={
+        "user_name": "Chester",
+        "preferences": "Concise answers. No fluff.",
+    },
+)
+```
+
+Default directory: `~/.pop/memory`. Override with `POP_MEMORY_DIR` env var or the `base_dir` argument.
+
+Core memory (`dict[str, str]`) is always included in context. Episodes and conversations persist as markdown files on disk.
+
+## 8. Hooks
+
+```python
+from pop.hooks import ConsoleHook, CostHook, FileLogHook
+
+runner = Runner(agent, hooks=[
+    ConsoleHook(),                       # print steps to stdout
+    CostHook(budget=1.00),               # track cumulative cost
+    FileLogHook(path="./agent.log"),     # append steps to JSON file
+])
+```
+
+## 9. Providers
+
+7 built-in: OpenAI, Anthropic, Gemini, DeepSeek, Kimi, MiniMax, GLM.
+
+```python
+# Switch by changing the string
+Agent(model="openai:gpt-4o")
+Agent(model="anthropic:claude-sonnet-4-20250514")
+Agent(model="gemini:gemini-2.0-flash")
+Agent(model="deepseek:deepseek-chat")
+```
+
+Custom providers implement `ModelAdapter`:
+
+```python
+from pop.models import ModelAdapter, register_provider
+
+class MyAdapter(ModelAdapter):
+    async def chat(self, messages, tools=None):
+        ...  # return ModelResponse
+
+    async def chat_stream(self, messages, tools=None):
+        ...  # yield StreamChunk
+
+register_provider("my_provider", MyAdapter)
+Agent(model="my_provider:my-model")
+```
+
+## 10. Inspecting Results
+
+Every run returns `AgentResult` with a full trace:
+
+```python
+result = agent.run("...")
+
+# Walk the step trace
+for step in result.steps:
+    print(f"Step {step.index}: {step.tool_name or 'final answer'}")
+    if step.tool_name:
+        print(f"  Args: {step.tool_args}")
+        print(f"  Result: {step.tool_result}")
+    print(f"  Tokens: {step.token_usage.total}")
+    print(f"  Cost: ${step.cost_usd:.6f}")
+
+# Totals
+print(f"Total cost: ${result.cost:.6f}")
+print(f"Total tokens: {result.token_usage.total}")
+print(f"Run ID: {result.run_id}")
+```
+
+## Quick Reference
+
+```python
+from pop import (
+    # Core
+    Agent, tool, Runner, run,
+    # Multi-agent
+    handoff, pipeline, orchestrate, debate, fan_out,
+    # Workflows
+    chain, route, parallel,
+    # Models
+    chat, model, register_provider,
+    # Types
+    AgentResult, Step, TokenUsage, Message,
+    # Stream events
+    ThinkEvent, ToolCallEvent, ToolResultEvent, TextDeltaEvent, DoneEvent,
+)
+
+from pop.memory import MarkdownMemory, InMemoryStore
+from pop.hooks import ConsoleHook, CostHook, FileLogHook
+```