Metadata-Version: 2.4
Name: zubbl-sdk
Version: 0.3.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/zubbl/zubbl
Project-URL: Changelog, https://docs.zubbl.in/changelog/
Author-email: Zubbl <hello@zubbl.in>
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

**Self-Evolving AI Agent SDK** — Make any AI agent 20-50% smarter, automatically.

Zubbl combines **trajectory learning** (cross-task pattern extraction) with **reflexion** (per-task verbal self-correction) to create a dual-loop improvement system. Your agent fails, Zubbl captures it, reflects on what went wrong, learns a reusable policy, and improves next time. No code changes, no redeployment.

**Eval results:** Baseline 82% → Post-Zubbl 88% (+6 points) on HotPotQA hard reasoning tasks. 3 of 9 failures recovered via reflexion.

## Install

```bash
pip install zubbl
```

## Quick Start

```python
from zubbl import ZubblClient

zubbl = ZubblClient(api_key="your-api-key")
agent = zubbl.wrap(your_agent)  # That's it.
```

## How It Works — Dual Learning Loop

```
Agent fails a task
        │
        ├──► Trajectory Learning (cross-task)
        │      Captures execution trajectory → extracts patterns →
        │      scores policies → serves recommendations for similar tasks
        │
        └──► Reflexion (per-task, NeurIPS 2023)
               LLM generates verbal self-reflection on failure →
               agent retries with reflection in-context →
               successful retry becomes a new trajectory for cross-task learning
```

Based on: Reflexion (NeurIPS 2023), ExpeL (AAAI 2024), ACE (ICLR 2026).

## Project Structure

```
src/
  zubbl/       SDK package (core client, LLM wrapper, guardrails, interceptor)
  api/         FastAPI backend with migrations
  db/          Database client
  worker/      Background jobs (validator, reflector, RL worker)
edge/          Cloudflare Workers edge function
eval/          Benchmark eval harness (HotPotQA, MBPP)
k8s/           Kubernetes deployment configs
tests/         Test suite (pytest)
docs/          Documentation
scripts/       Deployment scripts
examples/      Usage examples
```

## Development

```bash
pip install -e ".[dev]"
pytest tests/
```

## Deployment

```bash
bash scripts/deploy.sh
```

See [docs/Deployment-Guide.md](docs/Deployment-Guide.md) for full instructions.

## Links

- **Docs:** https://docs.zubbl.ai
- **Website:** https://zubbl.ai

## License

MIT
