Metadata-Version: 2.4
Name: ibhax-agentix
Version: 0.1.4
Summary: A lightweight multi-agent framework built on top of pydantic-ai.
Project-URL: Website, https://ibhax.com
Project-URL: Repository, https://github.com/IbhaX/agentix
Project-URL: Documentation, https://github.com/IbhaX/agentix/tree/main/docs/INDEX.md
Author-email: Albin Anthony <albin.anthony.dev@gmail.com>
Maintainer-email: Albin Anthony <albin.anthony.dev@gmail.com>
Requires-Python: >=3.10
Requires-Dist: chromadb>=0.5.0
Requires-Dist: pydantic
Requires-Dist: pydantic-ai
Provides-Extra: exa
Requires-Dist: exa-py; extra == 'exa'
Requires-Dist: python-dotenv; extra == 'exa'
Provides-Extra: openai
Requires-Dist: openai; extra == 'openai'
Requires-Dist: python-dotenv; extra == 'openai'
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-asyncio; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Description-Content-Type: text/markdown

# agentix

A lightweight multi-agent framework built on top of [`pydantic-ai`](https://github.com/pydantic/pydantic-ai).

## Documentation

Full documentation is in the `docs/` directory. Start at [`docs/INDEX.md`](https://github.com/IbhaX/agentix/tree/main/docs/INDEX.md).

## Install

From PyPI:

```bash
pip install ibhax-agentix
# or with the OpenAI provider used by the demo:
pip install ibhax-agentix[openai]
```

For local development:

```bash
pip install -e .
# or with the OpenAI provider used by the demo:
pip install -e '.[openai]'
```

## Quick start

```python
from pydantic import BaseModel
from agentix import AgentBuilder, AgentConfig, run

class Summary(BaseModel):
    text: str

cfg = AgentConfig.from_env("OPENROUTER_API_KEY", model="openai/gpt-4o-mini")

agent = (
    AgentBuilder("summariser", cfg, output_type=Summary)
    .system_prompt("Summarise the user's text in one sentence.")
    .build()
)

result = run(agent, "pydantic-ai is a Python framework for building production-grade LLM apps")
print(result.output.text)
print(f"({result.elapsed_ms:.0f} ms)")
```

## Core concepts

### `AgentConfig`
Holds provider + model config. **Never hardcode API keys.**

```python
# From environment variable (recommended)
cfg = AgentConfig.from_env("OPENROUTER_API_KEY", model="minimax/minimax-m3", temperature=0.7)

# Or directly (e.g. in tests)
cfg = AgentConfig(api_key="sk-...", model="openai/gpt-4o")
```

### `AgentBuilder`
Fluent builder that wraps pydantic-ai's `Agent`. Fully type-safe via generics.

```python
agent = (
    AgentBuilder("my_agent", cfg, output_type=MySchema)
    .system_prompt("You are ...")
    .tool(my_python_function)       # plain callable → tool
    .sub_agent("other_agent")       # registered agent → tool (lazy lookup)
    .temperature(0.3)
    .max_tokens(512)
    .build()
)
```

### `AgentRegistry`
Thread-safe global registry. `build(register=True)` handles it automatically.

```python
from agentix import AgentRegistry

AgentRegistry.names()               # ["math_joker", "critic", ...]
AgentRegistry.get("math_joker")     # → Agent
AgentRegistry.clear()               # useful in tests
```

### `Pipeline`
Chain agents sequentially. Each step's output becomes the next step's input (via `str()`).

```python
from agentix import Pipeline

result = (
    Pipeline("draft → critique → polish")
    .step(drafter_agent)
    .step(critic_agent)
    .step(polisher_agent)
    .run("Write a haiku about distributed systems.")
)
```

Supply a custom `adapter` to control how output is forwarded:

```python
pipeline.step(critic_agent, adapter=lambda out: f"Critique this: {out.text}")
```

### `run` / `run_async`
```python
from agentix import run, run_async

result = run(agent, "Hello")
print(result.output)       # typed output (your Pydantic model)
print(result.elapsed_ms)   # wall-clock time in ms

# Async
result = await run_async(agent, "Hello")
```

### Persistent memory

agentix provides a persistent, tiered memory layer backed by ChromaDB.
Four memory types are enabled by default:

- **Short-term**: recent conversation turns within the current session.
- **Long-term**: vector-retrieved relevant memories across sessions.
- **State**: structured key/value state for the session/user.
- **Session**: lightweight per-session metadata/summary.

To activate memory, provide a `session_id` when running:

```python
from agentix import run, MemoryConfig

# All four memory types are on by default.
result = run(agent, "Hello again", session_id="session-123")

# Seed state memory at the start of a run.
result = run(agent, "How am I?", session_id="session-123", state={"mood": "happy"})

# Disable specific memory types during agent creation.
agent = (
    AgentBuilder(
        "my_agent",
        cfg,
        output_type=MySchema,
        memory=MemoryConfig(long_term=False, state=False),
    )
    .system_prompt("You are a helpful assistant.")
    .build()
)

# Or use the fluent method.
agent = (
    AgentBuilder("my_agent", cfg, output_type=MySchema)
    .with_memory(MemoryConfig(short_term=False, session=False))
    .build()
)
```

## Examples

- `examples/single_agent.py` — one agent with structured output.
- `examples/multi_agent.py` — orchestrator that delegates to sub-agents.
- `examples/sequential_pipeline.py` — chained agents with custom adapters.
- `examples/parallel_agents.py` — run multiple agents concurrently.
- `examples/web_search_agent.py` — agent with an Exa AI web-search tool.
- `examples/agent_team.py` — research → draft → edit pipeline.
- `examples/agentix_demo.py` — basic multi-agent builder, registry, and pipeline demo.
- `examples/exa_memory_demo.py` — research agent with web search and all four memory types.

## Project layout

```
.
├── pyproject.toml
├── README.md
├── examples/
│   ├── single_agent.py
│   ├── multi_agent.py
│   ├── sequential_pipeline.py
│   ├── parallel_agents.py
│   ├── web_search_agent.py
│   ├── agent_team.py
│   ├── agentix_demo.py
│   └── exa_memory_demo.py
└── src/
    └── agentix/
        ├── __init__.py          # public API
        ├── py.typed             # typed package marker
        ├── builder/             # AgentBuilder
        ├── config/              # AgentConfig
        ├── exceptions/          # AgentixError hierarchy
        ├── memory/              # MemoryConfig / MemoryManager
        ├── pipeline/            # Pipeline
        ├── registry/            # AgentRegistry
        └── runner/              # run / run_async / RunResult
```

## Author

- **Albin Anthony** — [@IbhaX](https://github.com/IbhaX)
- Email: [albin.anthony.dev@gmail.com](mailto:albin.anthony.dev@gmail.com)
- Website: [https://ibhax.com](https://ibhax.com)
