Metadata-Version: 2.4
Name: zubbl-sdk
Version: 0.4.0
Summary: Self-Evolving AI Agent SDK - Make any AI agent 20-50% smarter automatically
Project-URL: Homepage, https://zubbl.in
Project-URL: Documentation, https://docs.zubbl.in
Project-URL: Repository, https://github.com/anupammaurya6767/zubbl-sdk-public
Project-URL: Changelog, https://docs.zubbl.in/changelog/
Project-URL: Discord, https://discord.gg/68cCeavPVK
Author-email: Zubbl <anupammaurya981@gmail.com>
License-Expression: MIT
Keywords: agents,ai,llm,reinforcement-learning,self-evolving
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.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: api
Requires-Dist: fastapi>=0.104.0; extra == 'api'
Requires-Dist: neo4j>=5.20.0; extra == 'api'
Requires-Dist: pinecone[asyncio]>=5.0.0; extra == 'api'
Requires-Dist: psycopg2-binary>=2.9.0; extra == 'api'
Requires-Dist: python-jose[cryptography]>=3.3.0; extra == 'api'
Requires-Dist: redis[hiredis]>=5.0.0; extra == 'api'
Requires-Dist: uvicorn[standard]>=0.24.0; extra == 'api'
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: ml
Requires-Dist: accelerate>=0.28.0; extra == 'ml'
Requires-Dist: datasets>=2.18.0; extra == 'ml'
Requires-Dist: peft>=0.10.0; extra == 'ml'
Requires-Dist: torch>=2.2.0; extra == 'ml'
Requires-Dist: transformers>=4.40.0; extra == 'ml'
Requires-Dist: trl>=0.12.0; extra == 'ml'
Description-Content-Type: text/markdown

# Zubbl SDK

**Self-Evolving AI Agent SDK** — Wrap any AI agent. It learns, recovers from failures, and gets better over time.

## Install

```bash
pip install zubbl-sdk
```

## Quick Start (3 Lines)

```python
from zubbl import ZubblClient

zubbl = ZubblClient(api_key="zubbl_xxx")
agent = zubbl.wrap(your_agent)

result = agent("Review this PR for security issues")
```

That's it. Your agent now:

1. **Auto-recovers from failures** — retries with fixes, no crash
2. **Learns from every run** — records trajectories, extracts patterns
3. **Injects proven strategies** — prepends natural-language guidance before each task
4. **Gets better over time** — policies improve as data accumulates

## How It Works

```
wrap(agent) → Agent runs → Trajectory recorded
                              ↓
                     Patterns extracted by task type
                              ↓
                     Policy built (confidence grows with data)
                              ↓
                     Next run: natural-language guidance prepended
                              ↓
                     Agent performs better — zero code changes
```

## Framework Examples

### OpenAI

```python
import openai
from zubbl import ZubblClient

client = openai.OpenAI()
zubbl = ZubblClient(api_key="zubbl_xxx")

def my_agent(task):
    return client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": task}],
    ).choices[0].message.content

agent = zubbl.wrap(my_agent)
result = agent("Write unit tests for auth.py")
```

### LangChain

```python
from langchain_openai import ChatOpenAI
from zubbl import ZubblClient

llm = ChatOpenAI(model="gpt-4o")
zubbl = ZubblClient(api_key="zubbl_xxx")

agent = zubbl.wrap(llm.invoke)
result = agent("Explain this error traceback")
```

### Any Callable

```python
zubbl = ZubblClient(api_key="zubbl_xxx")
agent = zubbl.wrap(any_function_that_takes_a_task)
```

## Auto-Recovery

When your agent fails, Zubbl catches the error and retries with a fix:

```python
agent = zubbl.wrap(my_agent)  # auto_recover=True by default

# If my_agent crashes internally:
# 1. Zubbl catches the error
# 2. Applies a fix (prompt patch, retry, model swap)
# 3. Returns the correct result
# No crash. No code change.
```

## Custom Policy Hook

Control exactly how learned strategies are injected:

```python
def my_hook(args, policy):
    task = args[0]
    tips = "\n".join(policy.recommended_actions[:3])
    return (f"Tips from past runs:\n{tips}\n\nTask: {task}",) + args[1:]

agent = zubbl.wrap(my_agent, policy_hook=my_hook)
```

## Dashboard

1. Agent runs are recorded automatically
2. Visit [app.zubbl.in](https://app.zubbl.in) to view trajectories and rate runs
3. Your feedback improves policies — no code changes needed

## Research Foundations

Built on peer-reviewed research:
- Training-Free GRPO (2025) — compact policy injection
- AgentHER (2026) — learn from failures via hindsight relabeling
- ETO (ACL 2024) — contrastive trajectory optimization
- Reflexion (NeurIPS 2023) — verbal self-reflection on failures

## Links

- [Documentation](https://docs.zubbl.in)
- [Dashboard](https://app.zubbl.in)
- [Website](https://zubbl.in)
- [Discord](https://discord.gg/68cCeavPVK)
- [PyPI](https://pypi.org/project/zubbl-sdk/)

## License

MIT
