# anpc849/ka-graph architecture

> Architecture diagram of the GitHub repository anpc849/ka-graph, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anpc849/ka-graph
- Repository: https://github.com/anpc849/ka-graph

## Overview

KaGraph is a LangGraph-compatible orchestration framework for stateful, message-aware agent workflows. A caller builds and compiles a graph, invokes it with messages, and graph execution dispatches nodes, routes conditional or parallel work, and can checkpoint state for inspection or resumption. Nodes can use Kaggle Benchmarks LLMs and prebuilt tools. Optional KaTrace captures runs for a web studio that stores and presents traces, LLM calls, and replay data. Relationships among unsampled studio pieces are limited to documented capabilities; the graph does not assume unshown frontend wiring.

Main entry points: [`src/kagraph/graph/state.py`](https://github.com/anpc849/ka-graph/blob/main/src/kagraph/graph/state.py) (Graph API), [`src/kagraph/webapp/backend/main.py`](https://github.com/anpc849/ka-graph/blob/main/src/kagraph/webapp/backend/main.py) (Trace API), [`src/kagraph/webapp/frontend/src/lib/api.ts`](https://github.com/anpc849/ka-graph/blob/main/src/kagraph/webapp/frontend/src/lib/api.ts) (Frontend API client), [`src/kagraph/tracing/katrace.py`](https://github.com/anpc849/ka-graph/blob/main/src/kagraph/tracing/katrace.py) (Trace capture)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Graph orchestration"]
  node_graph_api["Graph API<br/>[state.py]"]
  node_node_specs["Node policies<br/>[_node.py]"]
  node_runtime["Run context<br/>[runtime.py]"]
  node_checkpoint[("Checkpoints<br/>[base.py]")]
  node_graph_view["Graph visualization<br/>[visualization.py]"]
end

subgraph group_agent["Agent building blocks"]
  node_messages["Message model<br/>[messages.py]"]
  node_images["Image content<br/>[images.py]"]
  node_prompts["Prompt invocation<br/>[prompts.py]"]
  node_llm_loader["LLM loader<br/>[llms.py]"]
  node_tool_node["Tool execution<br/>[tool_node.py]"]
  node_tool_validation["Tool validation<br/>[validation.py]"]
end

subgraph group_observability["Tracing and storage"]
  node_trace_capture["Trace capture<br/>[katrace.py]"]
  node_studio_config["Studio configuration<br/>[_studio_config.py]"]
  node_studio_launcher["Studio launcher<br/>[studio.py]"]
end

subgraph group_studio["KaTrace Studio"]
  node_backend_api["Trace API<br/>[main.py]"]
  node_db_session["Database access<br/>[database.py]"]
  node_trace_models["Trace records<br/>[models.py]"]
  node_frontend_api["Frontend API client<br/>[api.ts]"]
  node_trace_list["Trace browser<br/>[page.tsx]"]
  node_trace_detail["Trace inspection<br/>[page.tsx]"]
  node_studio_home["Studio interface<br/>[page.tsx]"]
end

node_developer(("Graph author"))

node_developer -->|"defines workflow"| node_graph_api
node_graph_api -->|"uses policies"| node_node_specs
node_graph_api -->|"sets run context"| node_runtime
node_graph_api -->|"loads and saves"| node_checkpoint
node_developer -->|"loads model"| node_llm_loader
node_developer -->|"invokes model"| node_prompts
node_prompts -->|"uses messages"| node_messages
node_messages -->|"converts images"| node_images
node_graph_api -.->|"runs node"| node_tool_node
node_tool_validation -->|"validates tools"| node_tool_node
node_graph_api -.->|"emits run events"| node_trace_capture
node_trace_capture -->|"resolves endpoint"| node_studio_config
node_trace_capture -->|"sends trace data"| node_backend_api
node_studio_launcher -->|"writes runtime config"| node_studio_config
node_backend_api -->|"uses sessions"| node_db_session
node_backend_api -->|"queries records"| node_trace_models
node_frontend_api -.->|"requests trace data"| node_backend_api
node_trace_list -.->|"loads traces"| node_frontend_api
node_trace_detail -.->|"loads trace detail"| node_frontend_api
node_studio_home -.->|"uses API"| node_frontend_api
node_developer -.->|"renders graph"| node_graph_view

click node_graph_api "https://github.com/anpc849/ka-graph/blob/main/src/kagraph/graph/state.py"
click node_node_specs "https://github.com/anpc849/ka-graph/blob/main/src/kagraph/graph/_node.py"
click node_runtime "https://github.com/anpc849/ka-graph/blob/main/src/kagraph/runtime.py"
click node_checkpoint "https://github.com/anpc849/ka-graph/blob/main/src/kagraph/checkpoint/base.py"
click node_graph_view "https://github.com/anpc849/ka-graph/blob/main/src/kagraph/graph/visualization.py"
click node_messages "https://github.com/anpc849/ka-graph/blob/main/src/kagraph/messages.py"
click node_images "https://github.com/anpc849/ka-graph/blob/main/src/kagraph/images.py"
click node_prompts "https://github.com/anpc849/ka-graph/blob/main/src/kagraph/prompts.py"
click node_llm_loader "https://github.com/anpc849/ka-graph/blob/main/src/kagraph/llms.py"
click node_tool_node "https://github.com/anpc849/ka-graph/blob/main/src/kagraph/prebuilt/tool_node.py"
click node_tool_validation "https://github.com/anpc849/ka-graph/blob/main/src/kagraph/prebuilt/validation.py"
click node_trace_capture "https://github.com/anpc849/ka-graph/blob/main/src/kagraph/tracing/katrace.py"
click node_studio_config "https://github.com/anpc849/ka-graph/blob/main/src/kagraph/_studio_config.py"
click node_studio_launcher "https://github.com/anpc849/ka-graph/blob/main/src/kagraph/studio.py"
click node_backend_api "https://github.com/anpc849/ka-graph/blob/main/src/kagraph/webapp/backend/main.py"
click node_db_session "https://github.com/anpc849/ka-graph/blob/main/src/kagraph/webapp/backend/database.py"
click node_trace_models "https://github.com/anpc849/ka-graph/blob/main/src/kagraph/webapp/backend/models.py"
click node_frontend_api "https://github.com/anpc849/ka-graph/blob/main/src/kagraph/webapp/frontend/src/lib/api.ts"
click node_trace_list "https://github.com/anpc849/ka-graph/blob/main/src/kagraph/webapp/frontend/src/app/traces/page.tsx"
click node_trace_detail "https://github.com/anpc849/ka-graph/blob/main/src/kagraph/webapp/frontend/src/app/traces/%5BtraceId%5D/page.tsx"
click node_studio_home "https://github.com/anpc849/ka-graph/blob/main/src/kagraph/webapp/frontend/src/app/studio/page.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_graph_api,node_node_specs,node_runtime,node_checkpoint,node_graph_view toneBlue
class node_messages,node_images,node_prompts,node_llm_loader,node_tool_node,node_tool_validation toneAmber
class node_trace_capture,node_studio_config,node_studio_launcher toneMint
class node_backend_api,node_db_session,node_trace_models,node_frontend_api,node_trace_list,node_trace_detail,node_studio_home toneRose
class node_developer toneIndigo
```

## Components

### Graph orchestration

- [Graph API](https://github.com/anpc849/ka-graph/blob/main/src/kagraph/graph/state.py): `src/kagraph/graph/state.py`
- [Node policies](https://github.com/anpc849/ka-graph/blob/main/src/kagraph/graph/_node.py): `src/kagraph/graph/_node.py`
- [Run context](https://github.com/anpc849/ka-graph/blob/main/src/kagraph/runtime.py): `src/kagraph/runtime.py`
- [Checkpoints](https://github.com/anpc849/ka-graph/blob/main/src/kagraph/checkpoint/base.py): `src/kagraph/checkpoint/base.py`
- [Graph visualization](https://github.com/anpc849/ka-graph/blob/main/src/kagraph/graph/visualization.py): `src/kagraph/graph/visualization.py`

### Agent building blocks

- [Message model](https://github.com/anpc849/ka-graph/blob/main/src/kagraph/messages.py): `src/kagraph/messages.py`
- [Image content](https://github.com/anpc849/ka-graph/blob/main/src/kagraph/images.py): `src/kagraph/images.py`
- [Prompt invocation](https://github.com/anpc849/ka-graph/blob/main/src/kagraph/prompts.py): `src/kagraph/prompts.py`
- [LLM loader](https://github.com/anpc849/ka-graph/blob/main/src/kagraph/llms.py): `src/kagraph/llms.py`
- [Tool execution](https://github.com/anpc849/ka-graph/blob/main/src/kagraph/prebuilt/tool_node.py): `src/kagraph/prebuilt/tool_node.py`
- [Tool validation](https://github.com/anpc849/ka-graph/blob/main/src/kagraph/prebuilt/validation.py): `src/kagraph/prebuilt/validation.py`

### Tracing and storage

- [Trace capture](https://github.com/anpc849/ka-graph/blob/main/src/kagraph/tracing/katrace.py): `src/kagraph/tracing/katrace.py`
- [Studio configuration](https://github.com/anpc849/ka-graph/blob/main/src/kagraph/_studio_config.py): `src/kagraph/_studio_config.py`
- [Studio launcher](https://github.com/anpc849/ka-graph/blob/main/src/kagraph/studio.py): `src/kagraph/studio.py`

### KaTrace Studio

- [Trace API](https://github.com/anpc849/ka-graph/blob/main/src/kagraph/webapp/backend/main.py): `src/kagraph/webapp/backend/main.py`
- [Database access](https://github.com/anpc849/ka-graph/blob/main/src/kagraph/webapp/backend/database.py): `src/kagraph/webapp/backend/database.py`
- [Trace records](https://github.com/anpc849/ka-graph/blob/main/src/kagraph/webapp/backend/models.py): `src/kagraph/webapp/backend/models.py`
- [Frontend API client](https://github.com/anpc849/ka-graph/blob/main/src/kagraph/webapp/frontend/src/lib/api.ts): `src/kagraph/webapp/frontend/src/lib/api.ts`
- [Trace browser](https://github.com/anpc849/ka-graph/blob/main/src/kagraph/webapp/frontend/src/app/traces/page.tsx): `src/kagraph/webapp/frontend/src/app/traces/page.tsx`
- [Trace inspection](https://github.com/anpc849/ka-graph/blob/main/src/kagraph/webapp/frontend/src/app/traces/%5BtraceId%5D/page.tsx): `src/kagraph/webapp/frontend/src/app/traces/[traceId]/page.tsx`
- [Studio interface](https://github.com/anpc849/ka-graph/blob/main/src/kagraph/webapp/frontend/src/app/studio/page.tsx): `src/kagraph/webapp/frontend/src/app/studio/page.tsx`

### Other components

- **Graph author**

## Connections

- Graph author → Graph API: defines workflow (evidence: `README.md`)
- Graph API → Node policies: uses policies (evidence: `src/kagraph/graph/state.py`)
- Graph API → Run context: sets run context (evidence: `src/kagraph/graph/state.py`)
- Graph API → Checkpoints: loads and saves (evidence: `src/kagraph/graph/state.py`)
- Graph author → LLM loader: loads model (evidence: `README.md`)
- Graph author → Prompt invocation: invokes model (evidence: `README.md`)
- Prompt invocation → Message model: uses messages (evidence: `src/kagraph/prompts.py`)
- Message model → Image content: converts images (evidence: `src/kagraph/messages.py`)
- Graph API → Tool execution: runs node
- Tool validation → Tool execution: validates tools (evidence: `src/kagraph/prebuilt/validation.py`)
- Graph API → Trace capture: emits run events
- Trace capture → Studio configuration: resolves endpoint (evidence: `src/kagraph/tracing/katrace.py`)
- Trace capture → Trace API: sends trace data (evidence: `src/kagraph/tracing/katrace.py`)
- Studio launcher → Studio configuration: writes runtime config (evidence: `src/kagraph/studio.py`)
- Trace API → Database access: uses sessions (evidence: `src/kagraph/webapp/backend/main.py`)
- Trace API → Trace records: queries records (evidence: `src/kagraph/webapp/backend/main.py`)
- Frontend API client → Trace API: requests trace data
- Trace browser → Frontend API client: loads traces
- Trace inspection → Frontend API client: loads trace detail
- Studio interface → Frontend API client: uses API
- Graph author → Graph visualization: renders graph