# DAG Editor

The DAG Editor is an interactive browser-based tool for creating and
modifying causal graphs (World DAGs). It provides visual editing with
AI-powered edge proposals and real-time soliton scoring.

## Quick Start

```bash
orxaq edit
```

This opens the DAG editor at `http://localhost:8742/editor`.

## Features

### Node & Edge Management
- Add, remove, and rename nodes
- Create directed causal edges
- Full undo/redo support (100 actions)

### AI Edge Proposals
When connected to an LLM provider (see [Providers](providers.md)), the
editor can suggest causal edges based on domain knowledge and variable names.

Click **AI Propose** to get suggestions. Each proposal shows:
- Source and target nodes
- Confidence score (0-1)
- Reasoning for the proposed edge

### Soliton Scoring
Real-time graph quality scores update as you edit:

- **Connectivity**: Fraction of nodes reachable from root nodes
- **Balance**: How evenly distributed in/out degrees are
- **Depth**: DAG depth relative to node count
- **Density**: Edge count relative to ideal sparse density

### Export Formats

Export your DAG in multiple formats:

| Format | Use Case |
|--------|----------|
| **JSON** | Programmatic processing, re-import |
| **DOT** | Graphviz visualization |
| **Mermaid** | Documentation, markdown embedding |

## API Routes

The editor exposes REST endpoints for programmatic access:

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/dag/nodes` | List all nodes |
| GET | `/api/dag/edges` | List all edges |
| GET | `/api/dag/export` | Export full graph |
| GET | `/api/dag/export/{format}` | Export as json, dot, or mermaid |
| POST | `/api/dag/nodes` | Add a node |
| POST | `/api/dag/edges` | Add an edge |
| POST | `/api/dag/propose-edges` | Get AI proposals |
| POST | `/api/dag/score` | Get soliton scores |
| DELETE | `/api/dag/nodes` | Remove a node |
| DELETE | `/api/dag/edges` | Remove an edge |

## Python API

```python
from orxaq.experiences.dag_editor import DAGEditorSession, SolitonScorer

session = DAGEditorSession()
session.add_node("gdp", name="GDP Growth")
session.add_node("unemp", name="Unemployment")
session.add_edge("gdp", "unemp", mechanism="macro_effect")

# Score the graph
scorer = SolitonScorer(session.dag)
print(f"Soliton score: {scorer.overall_score()}")

# Undo last action
session.undo()

# Export
from orxaq.experiences.dag_editor import DAGExporter
exporter = DAGExporter(session.dag)
print(exporter.to_mermaid())
```
