Metadata-Version: 2.4
Name: FastICLE
Version: 1.0.2
Summary: Multi-agent framework that trains and orchestrates specialized Expert Agents on-demand via In-Context Reinforcement Learning.
Author-email: Maximilian König <47715517+makoeta@users.noreply.github.com>
Project-URL: Homepage, https://github.com/makoeta/ICLE
Project-URL: Source, https://github.com/makoeta/ICLE
Project-URL: Issues, https://github.com/makoeta/ICLE/issues
Keywords: llm,agents,multi-agent,in-context-learning,reinforcement-learning,mixture-of-experts
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: agno>=2.6.9
Requires-Dist: fastapi>=0.136.3
Requires-Dist: fasticrl==1.1.1
Requires-Dist: python-dotenv>=1.2.2
Provides-Extra: test
Requires-Dist: openai>=2.38.0; extra == "test"
Requires-Dist: pytest>=9.0.3; extra == "test"
Dynamic: license-file

# FastICLE

**FastICLE** is a multi-agent AI framework implementing the **ICLE (In-Context Learning Experts)** paradigm: it dynamically trains and orchestrates specialized *Expert Agents* to solve complex, multi-step tasks. Experts are trained on-demand using **In-Context Reinforcement Learning (ICRL)** and persist across runs, accumulating refined strategies over time.

![Framework Architecture](./assets/framework_architecture.png)

---

## How It Works

FastICLE decomposes any task into a four-stage pipeline:

```text
User Input
    │
    ▼
┌─────────────┐     ┌──────────────┐     ┌───────────────┐     ┌─────────────┐
│  Dispatcher │────▶│    Caster    │────▶│    Runtime    │────▶│  Assembler  │
│             │     │              │     │               │     │             │
│ Breaks task │     │ Assigns the  │     │ Executes all  │     │ Synthesizes │
│ into a DAG  │     │ right expert │     │ tasks in      │     │ outputs into│
│ of sub-tasks│     │ to each task │     │ parallel      │     │ final answer│
└─────────────┘     └──────────────┘     └───────────────┘     └─────────────┘
```

### Pipeline Stages

| Stage | Agent | Responsibility |
| --- | --- | --- |
| **Dispatch** | `DispatcherAgent` | Decomposes the user's request into an ordered, dependency-aware task graph |
| **Cast** | `CasterAgent` | Assigns the best-fit Expert Agent(s) to each sub-task; trains new experts on-demand |
| **Runtime** | `Runtime` | Resolves the task DAG topologically; runs independent tasks in parallel via a thread pool; injects each task's declared dependency outputs as context into its prompt |
| **Assemble** | `Assembler` | Collects all sub-agent outputs and synthesizes a single coherent final response |

### The Campus — Expert Training & Storage

The **Campus** is where Expert Agents are born. When the Caster determines no suitable expert exists for a sub-task, it calls `train_new_expert`, which:

1. **Generates a training curriculum** — a synthetic sequence of progressively harder tasks tailored to the required domain
2. **Runs ICRL training** via [FastICRL](https://github.com/makoeta/FastICRL) — the agent iterates through tasks using an explore/exploit loop guided by reward signals
3. **Distills a strategy** — the agent's learned strategy is saved alongside its experience buffer as a `.yaml` file in the expert save directory

Saved experts are loaded automatically on future runs, so the pool of available specialists grows over time.

### Expert Assignment Modes

The `CasterAgent` supports two modes:

- **Single-Expert Mode** — assigns exactly one highly specialized expert per task
- **Multi-Expert Mode (MoE)** — assigns a thematically relevant general expert as coordinator plus one or more specialists per sub-task, following a Mixture-of-Experts architecture

---

## Installation

Requires Python ≥ 3.13 and [uv](https://docs.astral.sh/uv/).

```bash
git clone https://github.com/makoeta/FastICLE.git
cd FastICLE
make install        # runtime dependencies only
make install-dev    # + test dependencies (pytest, openai test client)
```

Copy the environment template and fill in your API key:

```bash
cp .env.example .env
```

```env
# .env
OPENAI_API_KEY=sk-...
```

---

## Quick Start

```python
from agno.models.openai import OpenAIChat
from fasticle import FastICLE

model = OpenAIChat(id="gpt-4o")

pipeline = FastICLE(
    model=model,
    global_task="Write poems.",
    expert_save_dir="./experts",
    multi_expert_mode=True,
)

result = pipeline.run("Write three poems: one about black holes, one about the deep ocean, and one about autumn.")
print(result.content)
```

On the first run the Caster will train any missing experts before executing. On subsequent runs, saved experts are reused immediately.

### Verbose Mode

Pass `verbose=True` to log every pipeline step — dispatched task graph, expert assignments, per-task runtime outputs, expert training, and the final synthesis — to the console **and** a log file:

```python
pipeline = FastICLE(..., verbose=True)                       # logs to console + ./fasticle.log
pipeline = FastICLE(..., verbose=True, log_file="run.log")   # custom log file
pipeline = FastICLE(..., verbose=True, log_file=None)        # console only
```

Step summaries are logged at `INFO`; full step contents (system prompts — including each expert's learned strategy and experience buffer —, input prompts, task outputs, final answer) at `DEBUG`. Outside the pipeline you can enable the same logging directly:

```python
from fasticle.log_setup import enable_verbose_logging

enable_verbose_logging("fasticle.log")
```

---

## Project Structure

```text
src/fasticle/
├── __init__.py           # Top-level FastICLE workflow (exports FastICLE)
├── dispatcher/           # Decomposes input into a task graph
├── caster/               # Expert assignment & on-demand training
├── campus/               # Expert training via ICRL
│   └── models/           # ExpertConfig, TrainingTaskList
├── runtime/              # Parallel task execution engine
├── assembler/            # Output synthesis
└── models/               # Shared task models (DAG nodes)
tests/
├── data/                 # Example saved expert YAML files
└── {component}/          # Per-component test suites
```

---

## Dependencies

| Package | Role |
| --- | --- |
| [`agno`](https://github.com/agno-agi/agno) | Agent, Team, and Workflow orchestration |
| [`fasticrl`](https://github.com/makoeta/FastICRL) | In-Context Reinforcement Learning engine |
| `openai` | LLM backend |
| `pydantic` | Structured outputs and data models |
| `python-dotenv` | Environment configuration |

---

## Running Tests

```bash
make test          # unit tests only (no API calls)
make test-api      # full suite including live API calls
```

Tests require `make install-dev` to be run first.
