Metadata-Version: 2.4
Name: ahzan-agentforge
Version: 0.1.0
Summary: Production-grade AI agent framework — the Next.js for AI agents
Project-URL: Homepage, https://github.com/ahzan-dev/ahzan-agentforge
Project-URL: Repository, https://github.com/ahzan-dev/ahzan-agentforge
Project-URL: Issues, https://github.com/ahzan-dev/ahzan-agentforge/issues
Author-email: Ahzan <ahzan@trynewways.com>
License: MIT
Keywords: agent,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: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: nanoid>=2.0.0
Requires-Dist: pydantic>=2.0
Provides-Extra: all
Requires-Dist: anthropic>=0.30.0; extra == 'all'
Requires-Dist: openai>=1.30.0; extra == 'all'
Requires-Dist: redis[hiredis]>=5.0.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.30.0; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: openai
Requires-Dist: openai>=1.30.0; extra == 'openai'
Provides-Extra: redis
Requires-Dist: redis[hiredis]>=5.0.0; extra == 'redis'
Description-Content-Type: text/markdown

# ahzan-agentforge

Production-grade AI agent framework — the Next.js for AI agents. Python SDK.

AgentForge owns the agent loop — LLM calls, tool execution, state checkpointing, crash recovery, cost governance, rollback, and full run tracing. You write tools and prompts. Everything else is handled.

[![PyPI](https://img.shields.io/pypi/v/ahzan-agentforge)](https://pypi.org/project/ahzan-agentforge/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/ahzan-dev/ahzan-agentforge/blob/main/LICENSE)

> Also available as a TypeScript package: [`@ahzan-agentforge/core`](https://www.npmjs.com/package/@ahzan-agentforge/core)

## Install

```bash
pip install ahzan-agentforge
```

With LLM providers:

```bash
pip install ahzan-agentforge[anthropic]   # Anthropic Claude
pip install ahzan-agentforge[openai]      # OpenAI GPT
pip install ahzan-agentforge[all]         # All providers + Redis
```

## Quick Start

```python
import asyncio
from agentforge import define_agent, define_tool, create_llm
from pydantic import BaseModel

class OrderInput(BaseModel):
    order_id: str

class OrderOutput(BaseModel):
    id: str
    status: str
    total: float

get_order = define_tool(
    name="get_order",
    description="Fetch order details by ID",
    input_schema=OrderInput,
    output_schema=OrderOutput,
    execute=lambda inp: OrderOutput(id=inp.order_id, status="shipped", total=49.99),
)

agent = define_agent(
    name="support-agent",
    tools=[get_order],
    llm=create_llm(provider="openai", model="gpt-4o"),
    max_steps=15,
    system_prompt="You are a customer support agent. Look up orders and help customers.",
)

async def main():
    result = await agent.run(task="Order #4521 arrived damaged")
    print(result.status)   # 'completed'
    print(result.output)

asyncio.run(main())
```

## Features

- **Execution engine** with checkpointing and crash recovery
- **Pydantic schema validation** on tool inputs and outputs
- **LLM providers**: Anthropic Claude, OpenAI GPT, Ollama (local)
- **Token-level streaming** via `agent.stream()`
- **State stores**: in-memory (dev) and Redis (production)
- **Long-term memory**: in-memory and PgVector with embedding retrieval
- **Budget governor** with token/cost limits and model pricing
- **Autonomy policy** with per-tool allow/deny/escalate rules
- **Rollback** with compensating actions
- **Multi-agent coordination**: pipeline, parallel, supervisor, debate patterns
- **OpenTelemetry** observability — every decision traced
- **MockLLM and TestHarness** for testing without API calls

## LLM Providers

```python
from agentforge import create_llm

llm = create_llm(provider="anthropic", model="claude-sonnet-4-20250514")
llm = create_llm(provider="openai", model="gpt-4o")
llm = create_llm(provider="ollama", model="llama3.1")  # local, zero cost
```

## Streaming

```python
async for event in agent.stream(task="Help customer"):
    if event.type == "llm_token":
        print(event.content, end="", flush=True)
    elif event.type == "tool_start":
        print(f"\nCalling {event.tool_name}...")
    elif event.type == "done":
        print(f"\nResult: {event.result.output}")
```

## Multi-Agent Coordination

```python
from agentforge import pipeline, parallel, supervisor, debate

result = await pipeline([researcher, writer, editor], task="Write a report")
result = await supervisor(manager, {"researcher": researcher, "writer": writer}, task="Complete project")
result = await parallel([agent1, agent2], task="Analyze data", merge_fn=merge_results)
result = await debate([optimist, pessimist], task="Evaluate proposal", judge=judge)
```

## Testing

```python
from agentforge import create_mock_llm, create_test_harness

harness = create_test_harness(
    agent=my_agent_config,
    llm=create_mock_llm(responses=[
        {"tool_calls": [{"name": "get_order", "input": {"order_id": "4521"}}]},
        {"text": "Order found and ticket created."},
    ]),
)

result = await harness.run(task="Handle order issue")
assert result.status == "completed"
assert len(result.tool_calls("get_order")) == 1
```

## API Parity with TypeScript

| TypeScript | Python |
|---|---|
| `defineAgent()` | `define_agent()` |
| `defineTool()` | `define_tool()` |
| `createLLM()` | `create_llm()` |
| `createMockLLM()` | `create_mock_llm()` |
| `createTestHarness()` | `create_test_harness()` |
| `agent.run()` | `agent.run()` |
| `agent.stream()` | `agent.stream()` |
| Zod schemas | Pydantic models |
| `camelCase` | `snake_case` |

## Requirements

- Python >= 3.10
- Redis (optional, for persistent state)
- PostgreSQL + pgvector (optional, for long-term memory)

## License

[MIT](https://github.com/ahzan-dev/ahzan-agentforge/blob/main/LICENSE)
