learn-env 0.1.0

Learning Environment for Agent Reasoning Networks — Unified framework for specifying, composing, optimizing, and evaluating LLM-based systems

learn

Learning Environment for Agent Reasoning Networks
A unified framework for specifying, composing, optimizing, and evaluating LLM-based systems through natural language.

---

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

pip install learn-env

With optional engine support:

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:

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

Quick Start

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

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

# 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