marlo-sdk 0.1.0
Open-source agent learning platform
Requires Python: >=3.13
Keywords: autonomy, agents, reasoning, reward-models, trajectories, learning

# Marlo

Open-source agent learning platform. Capture agent behavior, evaluate outcomes, and turn failures into learnings that make your agents better over time.

[![PyPI](https://img.shields.io/pypi/v/marlo-sdk.svg)](https://pypi.org/project/marlo-sdk/)
[![npm](https://img.shields.io/npm/v/@marshmallo/marlo.svg)](https://www.npmjs.com/package/@marshmallo/marlo)
[![CI](https://github.com/Marshmallo-AI/Marlo/actions/workflows/ci.yml/badge.svg)](https://github.com/Marshmallo-AI/Marlo/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## The Problem

AI agents fail silently in production. The same mistakes repeat across runs because there is no feedback loop -- failures are logged and forgotten. Marlo closes this gap.

## How It Works

```
1. Capture    Record every LLM call, tool call, and outcome
2. Evaluate   Score task results automatically using Gemini
3. Learn      Generate structured learnings from failures
4. Apply      Inject learnings into future agent runs
```

Your agent gets smarter with every failure instead of repeating the same mistakes.

## Quick Start

Three commands to get running:

```bash
pip install marlo-sdk
export GEMINI_API_KEY=your-key    # https://aistudio.google.com/apikey
marlo run                          # starts server + dashboard + postgres
```

Dashboard at [localhost:5173](http://localhost:5173). API at [localhost:8000](http://localhost:8000). Requires [Docker](https://docs.docker.com/get-docker/).

Stop with `marlo stop`.

## Python SDK

```bash
pip install marlo-sdk
```

```python
import marlo

marlo.init()

# Register your agent
marlo.agent(
    name="support-bot",
    system_prompt="You are a customer support agent.",
    tools=[{"name": "lookup_order", "description": "Find order by ID"}],
)

# Track a task
with marlo.task(thread_id="thread-123", agent="support-bot") as t:
    t.input("Where is my order?")

    # Retrieve learnings from past failures
    learnings = t.get_learnings()
    # Inject into your prompt: system_prompt += learnings["learnings_text"]

    t.tool("lookup_order", {"id": "ORD-456"}, {"status": "shipped"})
    t.output("Your order has been shipped and arrives tomorrow.")

marlo.shutdown()
```

### Multi-Agent

```python
with marlo.task(thread_id="thread-1", agent="orchestrator") as parent:
    parent.input("Research AI trends and write a report")

    with parent.child(agent="researcher") as child:
        child.input("Search for recent AI developments")
        child.output("Found 3 relevant sources...")

    parent.output("Report complete.")
```

## TypeScript SDK

```bash
npm install @marshmallo/marlo
```

```typescript
import { init, agent, task, shutdown } from "@marshmallo/marlo";

await init();

agent("support-bot", "You are a customer support agent.", [
  { name: "lookup_order", description: "Find order by ID" },
]);

const t = task("thread-123", "support-bot").start();
t.input("Where is my order?");

const learnings = await t.getLearnings();
// Inject learnings into your prompt if available

t.tool("lookup_order", { id: "ORD-456" }, { status: "shipped" });
t.output("Your order has been shipped and arrives tomorrow.");
t.end();

await shutdown();
```

## Dashboard

The dashboard gives you visibility into your agents:

- **Traces** -- browse sessions, tasks, LLM calls, and tool calls
- **Learnings** -- review, approve, or reject generated learnings
- **Agents** -- see registered agents, their tools, and model configs
- **Rewards** -- track evaluation scores over time
- **Copilot** -- ask questions about your agent data in natural language

No login required. Runs locally at [localhost:5173](http://localhost:5173).

## Architecture

```
SDK (Python/TS)  --->  FastAPI Server  --->  PostgreSQL
                            |
                        Dashboard
```

The SDK captures events and sends them to the server over HTTP. The server stores trajectories in PostgreSQL, runs evaluation with Gemini, and generates learnings. The dashboard reads from the same server.

`marlo run` starts all three services via Docker Compose.

## Configuration

| Variable | Required | Default | Description |
|---|---|---|---|
| `GEMINI_API_KEY` | Yes | -- | Google Gemini key for evaluation |
| `MARLO_ENDPOINT` | No | `http://localhost:8000` | Server URL |

## Repository Structure

```
marlo/              Python SDK + FastAPI server
sdks/typescript/    TypeScript SDK (@marshmallo/marlo on npm)
dashboard/          React dashboard (Vite + TanStack Router)
docker/             Docker Compose config for local stack
tests/              Python test suite
```

## Releases

Releases are tag-driven. Bump the version, merge to main, then tag:

```bash
# Python SDK
git tag v0.2.0 && git push origin v0.2.0

# TypeScript SDK
git tag ts-v0.2.0 && git push origin ts-v0.2.0
```

Tags trigger CI to publish to PyPI/npm and create a GitHub Release automatically.

| Package | Registry | Tag format |
|---|---|---|
| `marlo-sdk` | [PyPI](https://pypi.org/project/marlo-sdk/) | `v*.*.*` |
| `@marshmallo/marlo` | [npm](https://www.npmjs.com/package/@marshmallo/marlo) | `ts-v*.*.*` |

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT