# quantumwake/kas architecture

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

- Interactive diagram: https://gitdiagram.com/quantumwake/kas
- Repository: https://github.com/quantumwake/kas

## Overview

K.A.S combines a terminal agent with a local model server. A user enters a task in the TUI or CLI; the agent streams model responses, runs requested tools, returns tool results for further turns, and saves resumable session state. The server translates Messages API requests into model prompts and streams parsed events from interchangeable MLX or llama.cpp backends. Additional documented capabilities include subagents, compaction and local recall, model management, and optional audio, vision, image, video, web, and workspace tools. Some feature links are based on README claims and tree paths; unsampled wiring is omitted.

Main entry points: [`agent/core/loop.py`](https://github.com/quantumwake/kas/blob/main/agent/core/loop.py) (Agent turn loop), [`server/core/pipeline.py`](https://github.com/quantumwake/kas/blob/main/server/core/pipeline.py) (Generation pipeline), [`agent/tui/app.py`](https://github.com/quantumwake/kas/blob/main/agent/tui/app.py) (Interactive TUI), [`server/registry.py`](https://github.com/quantumwake/kas/blob/main/server/registry.py) (Model registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent_ui["Agent interface"]
  node_tui["Interactive TUI<br/>[app.py]"]
  node_cli["Agent CLI<br/>[cli.py]"]
end

subgraph group_agent_core["Agent runtime"]
  node_agent_loop["Agent turn loop<br/>[loop.py]"]
  node_prompts["Prompts and toolspecs<br/>[prompts.py]"]
  node_compaction["Compaction<br/>[compaction.py]"]
  node_subagent["Subagent delegation<br/>[subagent.py]"]
end

subgraph group_server_runtime["Model server"]
  node_messages_api["Messages API<br/>[app.py]"]
  node_pipeline["Generation pipeline<br/>[pipeline.py]"]
  node_prompting["Prompt translation<br/>[translate.py]"]
  node_parser["Stream parser<br/>[parser.py]"]
  node_registry[("Model registry<br/>[registry.py]")]
  node_kv_state[("KV continuation<br/>[kvpersist.py]")]
end

subgraph group_model_engine["Inference backends"]
  node_mlx["MLX backend<br/>[mlx.py]"]
  node_llama["llama.cpp backend<br/>[llama_cpp.py]"]
end

subgraph group_agent_adapters["Agent capabilities"]
  node_tool_runner["Tool runner<br/>[executor.py]"]
  node_tool_adapters["Tools"]
  node_recall["Local recall"]
  node_embeddings["Embedding adapters"]
  node_session_store[("Session storage<br/>[filesystem.py]")]
  node_audio["Audio features"]
  node_media["Image and video"]
end

node_user(("User"))
node_model_source[("Local model files")]
node_model_service["Anthropic-compatible endpoint"]

node_user -->|"enters task"| node_tui
node_user -->|"starts task"| node_cli
node_tui -->|"drives turns"| node_agent_loop
node_cli -->|"starts turns"| node_agent_loop
node_agent_loop -->|"uses guidance"| node_prompts
node_agent_loop -->|"sends messages"| node_model_service
node_model_service -->|"streams response"| node_agent_loop
node_agent_loop -->|"runs tools"| node_tool_runner
node_tool_runner -->|"dispatches calls"| node_tool_adapters
node_agent_loop -->|"delegates tasks"| node_subagent
node_subagent -->|"runs nested turns"| node_agent_loop
node_agent_loop -->|"compacts transcript"| node_compaction
node_agent_loop -->|"saves session"| node_session_store
node_compaction -->|"archives transcript"| node_session_store
node_tool_adapters -.->|"exposes recall"| node_recall
node_recall -->|"embeds queries"| node_embeddings
node_tui -.->|"offers voice commands"| node_audio
node_tool_adapters -.->|"provides media tools"| node_media
node_messages_api -->|"dispatches generation"| node_pipeline
node_pipeline -->|"renders request"| node_prompting
node_pipeline -->|"parses output"| node_parser
node_pipeline -->|"selects engine"| node_registry
node_pipeline -->|"updates continuation"| node_kv_state
node_registry -->|"loads backend"| node_mlx
node_registry -->|"loads backend"| node_llama
node_mlx -->|"loads model"| node_model_source
node_llama -->|"loads model"| node_model_source
node_model_service -->|"serves requests"| node_messages_api

click node_tui "https://github.com/quantumwake/kas/blob/main/agent/tui/app.py"
click node_cli "https://github.com/quantumwake/kas/blob/main/agent/cli.py"
click node_agent_loop "https://github.com/quantumwake/kas/blob/main/agent/core/loop.py"
click node_prompts "https://github.com/quantumwake/kas/blob/main/agent/core/prompts.py"
click node_compaction "https://github.com/quantumwake/kas/blob/main/agent/core/compaction.py"
click node_subagent "https://github.com/quantumwake/kas/blob/main/agent/core/subagent.py"
click node_tool_runner "https://github.com/quantumwake/kas/blob/main/agent/adapters/tools/executor.py"
click node_tool_adapters "https://github.com/quantumwake/kas/tree/main/agent/adapters/tools"
click node_recall "https://github.com/quantumwake/kas/tree/main/agent/adapters/retrieval"
click node_embeddings "https://github.com/quantumwake/kas/tree/main/agent/adapters/embeddings"
click node_session_store "https://github.com/quantumwake/kas/blob/main/agent/adapters/storage/filesystem.py"
click node_audio "https://github.com/quantumwake/kas/tree/main/agent/adapters/audio"
click node_media "https://github.com/quantumwake/kas/tree/main/agent/adapters/tools"
click node_messages_api "https://github.com/quantumwake/kas/blob/main/server/app.py"
click node_pipeline "https://github.com/quantumwake/kas/blob/main/server/core/pipeline.py"
click node_prompting "https://github.com/quantumwake/kas/blob/main/server/prompting/translate.py"
click node_parser "https://github.com/quantumwake/kas/blob/main/server/prompting/parser.py"
click node_registry "https://github.com/quantumwake/kas/blob/main/server/registry.py"
click node_kv_state "https://github.com/quantumwake/kas/blob/main/server/core/kvpersist.py"
click node_mlx "https://github.com/quantumwake/kas/blob/main/server/backends/mlx.py"
click node_llama "https://github.com/quantumwake/kas/blob/main/server/backends/llama_cpp.py"

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_tui,node_cli,node_user toneBlue
class node_agent_loop,node_prompts,node_compaction,node_subagent,node_model_source toneAmber
class node_messages_api,node_pipeline,node_prompting,node_parser,node_registry,node_kv_state toneMint
class node_mlx,node_llama toneRose
class node_tool_runner,node_tool_adapters,node_recall,node_embeddings,node_session_store,node_audio,node_media,node_model_service toneIndigo
```

## Components

### Agent interface

- [Interactive TUI](https://github.com/quantumwake/kas/blob/main/agent/tui/app.py): `agent/tui/app.py`
- [Agent CLI](https://github.com/quantumwake/kas/blob/main/agent/cli.py): `agent/cli.py`

### Agent runtime

- [Agent turn loop](https://github.com/quantumwake/kas/blob/main/agent/core/loop.py): `agent/core/loop.py`
- [Prompts and toolspecs](https://github.com/quantumwake/kas/blob/main/agent/core/prompts.py): `agent/core/prompts.py`
- [Compaction](https://github.com/quantumwake/kas/blob/main/agent/core/compaction.py): `agent/core/compaction.py`
- [Subagent delegation](https://github.com/quantumwake/kas/blob/main/agent/core/subagent.py): `agent/core/subagent.py`

### Model server

- [Messages API](https://github.com/quantumwake/kas/blob/main/server/app.py): `server/app.py`
- [Generation pipeline](https://github.com/quantumwake/kas/blob/main/server/core/pipeline.py): `server/core/pipeline.py`
- [Prompt translation](https://github.com/quantumwake/kas/blob/main/server/prompting/translate.py): `server/prompting/translate.py`
- [Stream parser](https://github.com/quantumwake/kas/blob/main/server/prompting/parser.py): `server/prompting/parser.py`
- [Model registry](https://github.com/quantumwake/kas/blob/main/server/registry.py): `server/registry.py`
- [KV continuation](https://github.com/quantumwake/kas/blob/main/server/core/kvpersist.py): `server/core/kvpersist.py`

### Inference backends

- [MLX backend](https://github.com/quantumwake/kas/blob/main/server/backends/mlx.py): `server/backends/mlx.py`
- [llama.cpp backend](https://github.com/quantumwake/kas/blob/main/server/backends/llama_cpp.py): `server/backends/llama_cpp.py`

### Agent capabilities

- [Tool runner](https://github.com/quantumwake/kas/blob/main/agent/adapters/tools/executor.py): `agent/adapters/tools/executor.py`
- [Tools](https://github.com/quantumwake/kas/tree/main/agent/adapters/tools): `agent/adapters/tools`
- [Local recall](https://github.com/quantumwake/kas/tree/main/agent/adapters/retrieval): `agent/adapters/retrieval`
- [Embedding adapters](https://github.com/quantumwake/kas/tree/main/agent/adapters/embeddings): `agent/adapters/embeddings`
- [Session storage](https://github.com/quantumwake/kas/blob/main/agent/adapters/storage/filesystem.py): `agent/adapters/storage/filesystem.py`
- [Audio features](https://github.com/quantumwake/kas/tree/main/agent/adapters/audio): `agent/adapters/audio`
- [Image and video](https://github.com/quantumwake/kas/tree/main/agent/adapters/tools): `agent/adapters/tools`

### Other components

- **User**
- **Local model files**
- **Anthropic-compatible endpoint**

## Connections

- User → Interactive TUI: enters task
- User → Agent CLI: starts task
- Interactive TUI → Agent turn loop: drives turns
- Agent CLI → Agent turn loop: starts turns
- Agent turn loop → Prompts and toolspecs: uses guidance
- Agent turn loop → Anthropic-compatible endpoint: sends messages
- Anthropic-compatible endpoint → Agent turn loop: streams response
- Agent turn loop → Tool runner: runs tools
- Tool runner → Tools: dispatches calls
- Agent turn loop → Subagent delegation: delegates tasks
- Subagent delegation → Agent turn loop: runs nested turns
- Agent turn loop → Compaction: compacts transcript
- Agent turn loop → Session storage: saves session
- Compaction → Session storage: archives transcript
- Tools → Local recall: exposes recall
- Local recall → Embedding adapters: embeds queries
- Interactive TUI → Audio features: offers voice commands
- Tools → Image and video: provides media tools
- Messages API → Generation pipeline: dispatches generation
- Generation pipeline → Prompt translation: renders request
- Generation pipeline → Stream parser: parses output
- Generation pipeline → Model registry: selects engine
- Generation pipeline → KV continuation: updates continuation
- Model registry → MLX backend: loads backend
- Model registry → llama.cpp backend: loads backend
- MLX backend → Local model files: loads model
- llama.cpp backend → Local model files: loads model
- Anthropic-compatible endpoint → Messages API: serves requests