Metadata-Version: 2.4
Name: ygn-sage
Version: 0.1.0
Summary: Agent Development Kit with 5 cognitive pillars: Topology, Tools, Memory, Evolution, Strategy
Project-URL: Homepage, https://github.com/yannabadie/YGN-SAGE
Project-URL: Repository, https://github.com/yannabadie/YGN-SAGE
Project-URL: Documentation, https://github.com/yannabadie/YGN-SAGE/tree/master/docs
Author: Yann Abadie
License-Expression: MIT
Keywords: agents,llm,multi-agent,routing,topology
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Requires-Dist: aiosqlite>=0.20
Requires-Dist: anyio>=4
Requires-Dist: httpx>=0.28
Requires-Dist: numpy>=1.26
Requires-Dist: pydantic>=2.10
Requires-Dist: rich>=13
Provides-Extra: a2a
Requires-Dist: a2a-sdk[http-server]>=0.3; extra == 'a2a'
Provides-Extra: all
Requires-Dist: a2a-sdk[http-server]>=0.3; extra == 'all'
Requires-Dist: evalplus>=0.3.1; extra == 'all'
Requires-Dist: fastapi>=0.115; extra == 'all'
Requires-Dist: google-genai<2,>=1.20; extra == 'all'
Requires-Dist: mcp>=1.7; extra == 'all'
Requires-Dist: openai<2,>=1.50; extra == 'all'
Requires-Dist: pyarrow>=18; extra == 'all'
Requires-Dist: sentence-transformers>=2.2; extra == 'all'
Requires-Dist: uvicorn>=0.34; extra == 'all'
Requires-Dist: z3-solver>=4.13; extra == 'all'
Provides-Extra: arrow
Requires-Dist: pyarrow>=18; extra == 'arrow'
Provides-Extra: bench
Requires-Dist: evalplus>=0.3.1; extra == 'bench'
Provides-Extra: dev
Requires-Dist: hypothesis>=6.0; extra == 'dev'
Requires-Dist: mypy>=1.15; extra == 'dev'
Requires-Dist: pyarrow>=18; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.25; extra == 'dev'
Requires-Dist: pytest-cov>=6; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.11; extra == 'dev'
Requires-Dist: ulid-py>=1.1; extra == 'dev'
Provides-Extra: embeddings
Requires-Dist: sentence-transformers>=2.2; extra == 'embeddings'
Provides-Extra: google
Requires-Dist: google-genai<2,>=1.20; extra == 'google'
Provides-Extra: mcp
Requires-Dist: mcp>=1.7; extra == 'mcp'
Provides-Extra: openai
Requires-Dist: openai<2,>=1.50; extra == 'openai'
Provides-Extra: protocols
Requires-Dist: a2a-sdk[http-server]>=0.3; extra == 'protocols'
Requires-Dist: mcp>=1.7; extra == 'protocols'
Provides-Extra: ui
Requires-Dist: fastapi>=0.115; extra == 'ui'
Requires-Dist: uvicorn>=0.34; extra == 'ui'
Provides-Extra: z3
Requires-Dist: z3-solver>=4.13; extra == 'z3'
Description-Content-Type: text/markdown

# sage-python

Python SDK for YGN-SAGE (Self-Adaptive Generation Engine) -- an Agent Development Kit built on five cognitive pillars: Topology, Tools, Memory, Evolution, Strategy.

## Installation

```bash
cd sage-python
pip install -e ".[all,dev]"    # All providers + dev tools
pip install -e ".[google]"     # Google Gemini only
pip install -e ".[z3]"         # Z3 formal verification
```

Requires Python 3.12+.

## Quick Start

```python
from sage.boot import boot_agent_system

system = boot_agent_system()           # Auto-detects Codex CLI or Gemini
result = await system.run("Solve X")   # S1/S2/S3 routing + full agent loop
```

## Testing

```bash
python -m pytest tests/ -v             # Unit tests (1426 passed, 111 skipped, 7 pre-existing failures)
ruff check src/                        # Lint
mypy src/                              # Type check
python -m sage.bench --type routing    # Routing benchmark (no API key needed)
python -m sage.bench --type humaneval  # HumanEval 164 (needs LLM provider)
python -m sage.bench --type evalplus --dataset humaneval   # EvalPlus HumanEval+ (80x harder)
python -m sage.bench --type evalplus --dataset mbpp         # EvalPlus MBPP+ (35x harder)
python -m sage.bench --type ablation --limit 20             # Ablation study (6 configs)
python -m sage.bench.eval_protocol --suite humaneval -v     # Official evaluation protocol
```

## Package Structure

| Subpackage | Description |
|------------|-------------|
| `sage/` | Core runtime: boot sequence, agent loop, resilience |
| `sage/agents/` | Composition patterns: sequential, parallel, loop, handoff |
| `sage/contracts/` | Contract IR, DAG verification, Z3 SMT, CEGAR repair |
| `sage/memory/` | 4-tier memory: working (Arrow), episodic (SQLite), semantic (graph), ExoCortex (RAG) |
| `sage/llm/` | LLM providers: Google Gemini, OpenAI Codex CLI, model router |
| `sage/providers/` | Provider discovery, capability matrix, OpenAI-compat adapter |
| `sage/strategy/` | AdaptiveRouter (4-stage learned routing: structural → kNN embeddings → BERT ONNX → entropy probe; stage 3 reserved), KnnRouter (arXiv 2505.12601, 92% accuracy on 50 GT tasks), ComplexityRouter (heuristic fallback), CGRS self-braking |
| `sage/topology/` | MAP-Elites + CMA-ME + MCTS topology search, LLM synthesis, KG-RLVR process reward model |
| `sage/evolution/` | Evolutionary engine, LLM-driven mutation |
| `sage/tools/` | Tool registry, dynamic tool creation (Rust ToolExecutor first, Python fallback), memory tools, ExoCortex tools |
| `sage/events/` | EventBus: in-proc event system for observability |
| `sage/guardrails/` | 3-layer guardrails: input, runtime, output |
| `sage/bench/` | EvalPlus HumanEval+/MBPP+, routing accuracy, routing quality, ablation, evaluation protocol with error logging |
| `sage/sandbox/` | Sandbox manager (host execution disabled by default) |
| `sage/routing/` | ShadowRouter (dual Rust/Python traces) |

## Environment Variables

```bash
export GOOGLE_API_KEY="..."              # Required for Gemini models
export SAGE_MODEL_FAST="gemini-2.5-flash"  # Override any tier model ID
export SAGE_DASHBOARD_TOKEN="..."        # Dashboard auth (optional)
```

## Dependencies

Core: `httpx`, `pydantic`, `rich`, `anyio`, `aiosqlite`, `numpy`.
Optional: `google-genai` (Gemini), `openai` (Codex), `pyarrow` (Arrow memory), `z3-solver` (formal verification), `fastapi`/`uvicorn` (dashboard), `sentence-transformers` (Tier 2 embeddings), `onnxruntime` (Tier 1 RustEmbedder DLL), `sage_core` with `tool-executor` feature (Rust ToolExecutor: tree-sitter validation + Wasm WASI sandbox + subprocess isolation).
