Metadata-Version: 2.4
Name: learn-env
Version: 0.1.0
Summary: Learning Environment for Agent Reasoning Networks — Unified framework for specifying, composing, optimizing, and evaluating LLM-based systems
Keywords: llm,agents,optimization,textual-gradient-descent,multi-agent,prompt-optimization,natural-language-programming
Author: nghiatrngo
Author-email: nghiatrngo <nghian@uoregon.edu>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: pytest>=8.0 ; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23 ; extra == 'dev'
Requires-Dist: pytest-cov>=5.0 ; extra == 'dev'
Requires-Dist: mypy>=1.10 ; extra == 'dev'
Requires-Dist: ruff>=0.4 ; extra == 'dev'
Requires-Dist: python-dotenv>=1.0 ; extra == 'dev'
Requires-Dist: openai>=1.0 ; extra == 'dev'
Requires-Dist: openai>=1.0 ; extra == 'engines'
Requires-Dist: anthropic>=0.20 ; extra == 'engines'
Requires-Dist: google-generativeai>=0.5 ; extra == 'engines'
Requires-Dist: chromadb>=0.4 ; extra == 'memory'
Requires-Python: >=3.12
Project-URL: Bug Tracker, https://github.com/ngotrnghia1811/learn/issues
Project-URL: Documentation, https://github.com/ngotrnghia1811/learn#readme
Project-URL: Homepage, https://github.com/ngotrnghia1811/learn
Project-URL: Repository, https://github.com/ngotrnghia1811/learn
Provides-Extra: dev
Provides-Extra: engines
Provides-Extra: memory
Description-Content-Type: text/markdown

<h1 align="center">learn</h1>

<p align="center">
  <b>Learning Environment for Agent Reasoning Networks</b><br>
  A unified framework for specifying, composing, optimizing, and evaluating LLM-based systems through natural language.
</p>

<p align="center">
  <a href="https://pypi.org/project/learn-env/"><img alt="PyPI" src="https://img.shields.io/pypi/v/learn-env"></a>
  <a href="https://pypi.org/project/learn-env/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/learn-env"></a>
  <a href="https://github.com/ngotrnghia1811/learn/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
</p>

---

## What is `learn`?

**`learn`** is PyTorch, but for text-space optimization and multi-agent systems. It unifies four research communities — workflow optimization, self-evolving agents, textual gradient descent, and agentic workflow automation — under one composable API.

| PyTorch | learn | Role |
|---------|-------|------|
| `torch.Tensor` | `Variable` | Text container + computation graph node |
| `nn.Parameter` | `Parameter` | Learnable text variable |
| `nn.Module` | `Component` / `Agent` | Composable unit |
| `nn.Sequential` | `Program` | Composition of units |
| `optim.SGD` | `TGD` | Optimizer (textual gradient descent) |
| `loss.backward()` | `loss.backward(engine)` | Gradient computation |
| `optimizer.step()` | `optimizer.step()` | Parameter update |
| Training loop | `Trainer` | Orchestration |

## Installation

```bash
pip install learn-env
```

With optional engine support:

```bash
pip install learn-env[engines]    # OpenAI, Anthropic, Google
pip install learn-env[memory]     # ChromaDB vector memory
pip install learn-env[dev]        # Development tools
```

Or install from source with [uv](https://docs.astral.sh/uv/):

```bash
git clone https://github.com/ngotrnghia1811/learn.git
cd learn
uv sync --extra dev
```

## Quick Start

```python
from learn.env.engine import MockEngine
from learn.env.program import Variable, Parameter, Program
from learn.agent import Generator

# 1. Create an engine (swap MockEngine for OpenAICompatibleEngine in production)
engine = MockEngine()

# 2. Define a learnable system prompt
system_prompt = Parameter(
    value="You are a helpful assistant that answers questions concisely.",
    name="system_prompt",
)

# 3. Build an agent
agent = Generator(name="qa_agent", engine=engine, prompt=system_prompt)

# 4. Run inference
question = Variable("What is textual gradient descent?", name="question")
answer = agent(question)
print(answer.value)
```

### Training Loop

```python
from learn.optim.txt import TGD

# Create optimizer
optimizer = TGD(parameters=[system_prompt], engine=engine)

# Training step (analogous to PyTorch)
loss = some_loss_function(prediction, target)
loss.backward(engine)      # Compute textual gradients
optimizer.step()           # Update parameters with natural language feedback
```

## Architecture

```
learn
├── learn.env           Programs, engines, management, Trainer
├── learn.agent         Generator, Reviewer, Reviser, Router, Ensemble, MetaAgent...
├── learn.optim         TGD, OPRO, evolutionary optimizers, weight-space (SFT/DPO/PPO)
└── learn.benchmark     Tasks, scoring, evaluation protocols, statistics
```

### Dependency Rules

These are strict and enforced:

```
learn.optim         → depends on NOTHING
learn.benchmark     → depends on NOTHING
learn.env.engine    → depends on NOTHING
learn.agent         → may depend on learn.optim
learn.env.program   → depends on learn.env.engine + learn.agent
learn.env           → orchestrates all others
```

### Key Components

**Agents** — `Generator`, `Reviewer`, `Reviser`, `Router`, `Ensemble`, `MetaAgent`, `Programmer`, `Retriever`, `Custom`. Each agent has sub-systems for memory (8 types), tools (10+ types), reasoning (CoT, ReAct, ToT, LATS, Reflexion), and profiles.

**Optimizers** — Four families:
- **Textual** — `TGD`, `TSGD-M`, `TextBFGS`, `GDPO`, `REMO` (gradient descent in text space)
- **Numerical** — `OPRO`, `MIPROv2`, `Bootstrap`, `CAPO`, `BanditSelector`
- **Evolutionary** — `CMAESEvolution`, `MCTSEvolution`, `NoveltySearch`, island models
- **Weight-space** — `SFT`, `DPO`, `PPO`, `GRPO`, `REINFORCE`

**Engines** — `MockEngine` (testing), `OpenAICompatibleEngine`, `OpenRouterEngine`, `EnginePool` (multi-model routing), `CachedEngine`, `InstrumentedEngine`, `RetryEngine`.

**Programs** — DAG-based composition with typed edges (DataFlow, ControlFlow, Conditional, Communication, Delegation, Feedback), shared memory, and topology presets (Complete, Star, Layered, Ring, Learned).

**Benchmark** — `ExactMatch`, `TokenF1`, `LLMJudge`, `StandardProtocol`, `MultiRunProtocol`, `BootstrapCI`, `EffectSize`.

## Development

```bash
# Run tests (806 unit tests)
uv run pytest -m "not integration"

# Lint
uv run ruff check src/

# Type check
uv run mypy src/

# Format
uv run ruff format src/
```

## License

[MIT](LICENSE)
