Documentation and Examples

Create comprehensive documentation for the Op-based agent system.

Deliverables

1. Update Omni/Agent/README.md

# Omni Agent System

## Overview

The agent system is built on a free monad over inference operations,
enabling composable, parallel, observable agent programs.

## Core Concepts

### Op - The Free Monad

\`\`\`haskell
-- An agent program is data, not IO
type Op s = Free (OpF s)

-- Run with different interpreters
runSequential :: Config -> s -> Op s a -> IO (a, Trace, s)
runParallel   :: Config -> s -> Op s a -> IO (a, Trace, s)
\`\`\`

### Primitives

- \`infer\`: Call an LLM
- \`par\`: Run branches in parallel, collect all results
- \`race\`: Run branches in parallel, take first result
- \`tool\`: Execute a tool (IO action)
- \`get/put\`: Access state
- \`emit\`: Emit observability event
- \`checkpoint\`: Save resumption point

### State Strategies

| Strategy | Use Case | Merge Behavior |
|----------|----------|----------------|
| CRDT | Coding, research | Automatic merge |
| STM | Monitoring | Transactional |
| Event Log | Audit trails | Append-only |

## Quick Start

\`\`\`haskell
import Omni.Agent.Op
import Omni.Agent.Interpreter.Sequential

-- Define a program
myAgent :: Op AgentState Text
myAgent = do
  response <- infer model "Hello, what can you help with?"
  emit (EventCustom "greeting" (toJSON response))
  pure (responseContent response)

-- Run it
main = do
  (result, trace, _) <- runSequential config initialState myAgent
  print result
  print (totalCost trace)
\`\`\`

## Examples

See \`Omni/Agent/Programs/\` for complete examples.
\`\`\`

### 2. Create Omni/Agent/TUTORIAL.md

Step-by-step guide:

1. Your first Op program
2. Adding tools
3. Parallel composition
4. State management
5. Checkpointing
6. Testing Op programs

### 3. Create Omni/Agent/PATTERNS.md

Common patterns:

- Agent loop pattern
- Parallel research pattern
- Oracle advisor pattern
- Verify-retry loop pattern
- Recovery/rollback pattern

### 4. API Documentation

Ensure all exported functions have Haddock comments:

-- | Execute an inference call to an LLM. -- -- This is the core primitive. All agent behavior ultimately -- reduces to sequences of 'infer' calls. -- -- @ -- response <- infer model prompt -- @ infer :: Model -> Prompt -> Op s Response

### 5. Example Programs

Ensure these exist and are well-documented:

- `Programs/Agent.hs` - Basic agent loop
- `Programs/Coder.hs` - Coding workflow
- `Programs/Research.hs` - Parallel research
- `Programs/Oracle.hs` - Oracle pattern
- `Programs/Monitor.hs` - STM-based monitoring

### 6. Migration Guide

How to migrate from Engine.runAgentWithProvider:

Migrating from Engine to Op

Before

\\\haskell result <- Engine.runAgentWithProvider config provider agentCfg prompt \\\

After

\\\haskell let program = agent agentCfg prompt (result, trace, state) <- runSequential seqConfig initialState program \\\

Benefits of Migration

• Composable: Combine programs with >>= and par
• Observable: Trace is first-class data
• Resumable: Checkpoint and resume long runs
• Testable: Mock interpreter for unit tests

\\\`

Files

• Omni/Agent/README.md
• Omni/Agent/TUTORIAL.md
• Omni/Agent/PATTERNS.md
• Omni/Agent/MIGRATION.md
• Haddock comments in all modules