# ceschmiedel/alm architecture

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

- Interactive diagram: https://gitdiagram.com/ceschmiedel/alm
- Repository: https://github.com/ceschmiedel/alm

## Overview

ALM is a governed federation of domain-specialist agents. A user submits an intent through the CLI or REST API; the runtime structures it as a LIP task, routes and decomposes it, executes the dependency plan with specialists, then arbitrates and synthesizes an answer with provenance. The Context Graph, scoped retrieval and governance support execution throughout. README documents evaluation, distillation, MLOps and Agentic Bus bridging; sampled excerpts do not establish all their runtime wiring.

Main entry points: [`alm/federation/runtime.py`](https://github.com/ceschmiedel/alm/blob/main/alm/federation/runtime.py) (Federation runtime), [`alm/models`](https://github.com/ceschmiedel/alm/tree/main/alm/models) (Model serving), [`alm/experts`](https://github.com/ceschmiedel/alm/tree/main/alm/experts) (Expert agents), [`alm/cmrag`](https://github.com/ceschmiedel/alm/tree/main/alm/cmrag) (Scoped retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_api["REST API<br/>[app.py]"]
  node_protocol["LIP protocol"]
end

subgraph group_execution["Routing and execution"]
  node_runtime["Federation runtime<br/>[runtime.py]"]
  node_router["Cognitive router<br/>[router.py]"]
  node_dag["DAG execution"]
  node_contextpass["Context passing<br/>[context.py]"]
  node_arbitration["Arbitration synthesis"]
end

subgraph group_specialists["Expert federation"]
  node_experts["Expert agents"]
  node_models["Model serving"]
  node_backends["Model backends"]
end

subgraph group_context["Context and governance"]
  node_graph[("Context Graph")]
  node_cmrag["Scoped retrieval"]
  node_governance["IBAC policies"]
  node_persistence[("Session storage")]
end

subgraph group_operations["Learning and operations"]
  node_evaluation["Evaluation harness"]
  node_distillation["Distillation pipeline"]
  node_mlops["Model lifecycle"]
  node_bridge["Bus bridge"]
end

node_user(("User"))

node_user -->|"submits intent"| node_cli
node_user -->|"submits intent"| node_api
node_cli -->|"invokes"| node_runtime
node_api -->|"invokes"| node_runtime
node_runtime -->|"structures task"| node_protocol
node_runtime -->|"routes task"| node_router
node_router -->|"matches capabilities"| node_graph
node_runtime -->|"executes plan"| node_dag
node_runtime -->|"dispatches subtasks"| node_experts
node_runtime -->|"synthesizes answers"| node_arbitration
node_runtime -->|"persists session"| node_persistence
node_dag -->|"passes dependencies"| node_contextpass
node_contextpass -->|"publishes answers"| node_graph
node_experts -->|"requests inference"| node_models
node_models -->|"dispatches inference"| node_backends
node_experts -->|"retrieves context"| node_cmrag
node_cmrag -->|"checks access"| node_governance
node_cmrag -->|"uses ontology"| node_graph
node_runtime -->|"governs actions"| node_governance
node_distillation -->|"uses teacher serving"| node_models
node_evaluation -.->|"evaluates federation"| node_runtime
node_mlops -.->|"manages versions"| node_models
node_bridge -.->|"publishes federation"| node_runtime

click node_cli "https://github.com/ceschmiedel/alm/blob/main/alm/cli.py"
click node_api "https://github.com/ceschmiedel/alm/blob/main/alm/api/app.py"
click node_protocol "https://github.com/ceschmiedel/alm/tree/main/alm/protocol"
click node_runtime "https://github.com/ceschmiedel/alm/blob/main/alm/federation/runtime.py"
click node_router "https://github.com/ceschmiedel/alm/blob/main/alm/router/router.py"
click node_dag "https://github.com/ceschmiedel/alm/tree/main/alm/orchestration"
click node_contextpass "https://github.com/ceschmiedel/alm/blob/main/alm/orchestration/context.py"
click node_arbitration "https://github.com/ceschmiedel/alm/tree/main/alm/arbitration"
click node_experts "https://github.com/ceschmiedel/alm/tree/main/alm/experts"
click node_models "https://github.com/ceschmiedel/alm/tree/main/alm/models"
click node_backends "https://github.com/ceschmiedel/alm/tree/main/alm/models/backends"
click node_graph "https://github.com/ceschmiedel/alm/tree/main/alm/graph"
click node_cmrag "https://github.com/ceschmiedel/alm/tree/main/alm/cmrag"
click node_governance "https://github.com/ceschmiedel/alm/tree/main/alm/governance"
click node_persistence "https://github.com/ceschmiedel/alm/tree/main/alm/persistence"
click node_evaluation "https://github.com/ceschmiedel/alm/tree/main/alm/evaluation"
click node_distillation "https://github.com/ceschmiedel/alm/tree/main/alm/distillation"
click node_mlops "https://github.com/ceschmiedel/alm/tree/main/alm/mlops"
click node_bridge "https://github.com/ceschmiedel/alm/tree/main/alm/bridge"

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_cli,node_api,node_protocol,node_user toneBlue
class node_runtime,node_router,node_dag,node_contextpass,node_arbitration toneAmber
class node_experts,node_models,node_backends toneMint
class node_graph,node_cmrag,node_governance,node_persistence toneRose
class node_evaluation,node_distillation,node_mlops,node_bridge toneIndigo
```

## Components

### Interfaces

- [CLI](https://github.com/ceschmiedel/alm/blob/main/alm/cli.py): `alm/cli.py`
- [REST API](https://github.com/ceschmiedel/alm/blob/main/alm/api/app.py): `alm/api/app.py`
- [LIP protocol](https://github.com/ceschmiedel/alm/tree/main/alm/protocol): `alm/protocol`

### Routing and execution

- [Federation runtime](https://github.com/ceschmiedel/alm/blob/main/alm/federation/runtime.py): `alm/federation/runtime.py`
- [Cognitive router](https://github.com/ceschmiedel/alm/blob/main/alm/router/router.py): `alm/router/router.py`
- [DAG execution](https://github.com/ceschmiedel/alm/tree/main/alm/orchestration): `alm/orchestration`
- [Context passing](https://github.com/ceschmiedel/alm/blob/main/alm/orchestration/context.py): `alm/orchestration/context.py`
- [Arbitration synthesis](https://github.com/ceschmiedel/alm/tree/main/alm/arbitration): `alm/arbitration`

### Expert federation

- [Expert agents](https://github.com/ceschmiedel/alm/tree/main/alm/experts): `alm/experts`
- [Model serving](https://github.com/ceschmiedel/alm/tree/main/alm/models): `alm/models`
- [Model backends](https://github.com/ceschmiedel/alm/tree/main/alm/models/backends): `alm/models/backends`

### Context and governance

- [Context Graph](https://github.com/ceschmiedel/alm/tree/main/alm/graph): `alm/graph`
- [Scoped retrieval](https://github.com/ceschmiedel/alm/tree/main/alm/cmrag): `alm/cmrag`
- [IBAC policies](https://github.com/ceschmiedel/alm/tree/main/alm/governance): `alm/governance`
- [Session storage](https://github.com/ceschmiedel/alm/tree/main/alm/persistence): `alm/persistence`

### Learning and operations

- [Evaluation harness](https://github.com/ceschmiedel/alm/tree/main/alm/evaluation): `alm/evaluation`
- [Distillation pipeline](https://github.com/ceschmiedel/alm/tree/main/alm/distillation): `alm/distillation`
- [Model lifecycle](https://github.com/ceschmiedel/alm/tree/main/alm/mlops): `alm/mlops`
- [Bus bridge](https://github.com/ceschmiedel/alm/tree/main/alm/bridge): `alm/bridge`

### Other components

- **User**

## Connections

- User → CLI: submits intent
- User → REST API: submits intent
- CLI → Federation runtime: invokes
- REST API → Federation runtime: invokes
- Federation runtime → LIP protocol: structures task
- Federation runtime → Cognitive router: routes task
- Cognitive router → Context Graph: matches capabilities
- Federation runtime → DAG execution: executes plan
- Federation runtime → Expert agents: dispatches subtasks
- Federation runtime → Arbitration synthesis: synthesizes answers
- Federation runtime → Session storage: persists session
- DAG execution → Context passing: passes dependencies
- Context passing → Context Graph: publishes answers
- Expert agents → Model serving: requests inference
- Model serving → Model backends: dispatches inference
- Expert agents → Scoped retrieval: retrieves context
- Scoped retrieval → IBAC policies: checks access
- Scoped retrieval → Context Graph: uses ontology
- Federation runtime → IBAC policies: governs actions
- Distillation pipeline → Model serving: uses teacher serving
- Evaluation harness → Federation runtime: evaluates federation
- Model lifecycle → Model serving: manages versions
- Bus bridge → Federation runtime: publishes federation