# ruc-datalab/evoontology architecture

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

- Interactive diagram: https://gitdiagram.com/ruc-datalab/evoontology
- Repository: https://github.com/ruc-datalab/evoontology

## Overview

EvoOntology provides a versioned semantic layer for data agents, accessed through MCP and adapted from workload and execution history. The main workflow prepares workload evidence, builds and publishes grounded ontology versions, serves semantics on demand, records task trajectories, and uses evolution diagnosis and paired evaluation to gate candidate updates. The graph emphasizes the canonical package; plugin copies expose the same core for Claude Code and Codex. Some subsystem relationships are documented in the README, while unsampled implementation details are left unconnected.

Main entry points: [`evoontology/evolution/session.py`](https://github.com/ruc-datalab/evoontology/blob/master/evoontology/evolution/session.py) (Evolution Session), [`evoontology/runtime/ops.py`](https://github.com/ruc-datalab/evoontology/blob/master/evoontology/runtime/ops.py) (Lifecycle Operations), [`evoontology/ontology/store.py`](https://github.com/ruc-datalab/evoontology/blob/master/evoontology/ontology/store.py) (Versioned Store), [`evoontology/runtime/runtime.py`](https://github.com/ruc-datalab/evoontology/blob/master/evoontology/runtime/runtime.py) (Semantic Runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace &amp; Ontology"]
  node_workspace_ctx["Workspace Context<br/>[workspace.py]"]
  node_ontology_model["Ontology Records<br/>[models.py]"]
  node_ontology_store[("Versioned Store<br/>[store.py]")]
end

subgraph group_access["Agent Runtime"]
  node_semantic_runtime["Semantic Runtime<br/>[runtime.py]"]
  node_tool_layer["Semantic Tools<br/>[tools.py]"]
  node_mcp_server["MCP Server<br/>[mcp_server.py]"]
end

subgraph group_lifecycle["Workload &amp; Evolution"]
  node_workflow["Workload Workflow<br/>[workflow.py]"]
  node_operations["Lifecycle Operations<br/>[ops.py]"]
  node_trajectory[("Task Trajectories<br/>[trajectory.py]")]
  node_trigger["Evolution Trigger<br/>[trigger.py]"]
  node_evolution["Evolution Session<br/>[session.py]"]
  node_evaluation["Candidate Evaluation<br/>[evaluation.py]"]
  node_validation["Ontology Validation<br/>[validate.py]"]
end

subgraph group_integration["Adapters &amp; Views"]
  node_adapter["Agent Adapter<br/>[adapter.py]"]
  node_visualization["Ontology Preview<br/>[preview.py]"]
  node_renderer["Ontology Renderer<br/>[renderer.py]"]
  node_claude_plugin["Claude Code Plugin<br/>[mcp_server.py]"]
  node_codex_plugin["Codex Plugin<br/>[mcp_server.py]"]
end

node_agent(("Data Agent"))

node_agent -->|"queries semantics"| node_mcp_server
node_mcp_server -.->|"dispatches tools"| node_semantic_runtime
node_tool_layer -.->|"exposes operations"| node_semantic_runtime
node_semantic_runtime -->|"reads version"| node_ontology_store
node_ontology_store -->|"loads records"| node_ontology_model
node_workflow -->|"uses workspace"| node_workspace_ctx
node_workflow -->|"reads history"| node_trajectory
node_operations -->|"invokes workflow"| node_workflow
node_operations -->|"starts evolution"| node_evolution
node_operations -->|"checks due state"| node_trigger
node_operations -->|"validates versions"| node_validation
node_operations -->|"previews ontology"| node_visualization
node_trajectory -->|"stores in workspace"| node_workspace_ctx
node_trigger -->|"counts new tasks"| node_trajectory
node_evolution -->|"consults gate"| node_trigger
node_evolution -->|"runs comparisons"| node_evaluation
node_evolution -->|"validates candidate"| node_validation
node_evolution -->|"publishes candidate"| node_ontology_store
node_adapter -.->|"supports session"| node_evolution
node_renderer -->|"reads ontology"| node_ontology_store
node_renderer -->|"renders runtime"| node_semantic_runtime
node_claude_plugin -.->|"integrates agent"| node_agent
node_codex_plugin -.->|"integrates agent"| node_agent

click node_workspace_ctx "https://github.com/ruc-datalab/evoontology/blob/master/evoontology/workspace.py"
click node_ontology_model "https://github.com/ruc-datalab/evoontology/blob/master/evoontology/ontology/models.py"
click node_ontology_store "https://github.com/ruc-datalab/evoontology/blob/master/evoontology/ontology/store.py"
click node_semantic_runtime "https://github.com/ruc-datalab/evoontology/blob/master/evoontology/runtime/runtime.py"
click node_tool_layer "https://github.com/ruc-datalab/evoontology/blob/master/evoontology/runtime/tools.py"
click node_mcp_server "https://github.com/ruc-datalab/evoontology/blob/master/evoontology/runtime/mcp_server.py"
click node_workflow "https://github.com/ruc-datalab/evoontology/blob/master/evoontology/workflow.py"
click node_operations "https://github.com/ruc-datalab/evoontology/blob/master/evoontology/runtime/ops.py"
click node_trajectory "https://github.com/ruc-datalab/evoontology/blob/master/evoontology/trajectory/trajectory.py"
click node_trigger "https://github.com/ruc-datalab/evoontology/blob/master/evoontology/trigger/trigger.py"
click node_evolution "https://github.com/ruc-datalab/evoontology/blob/master/evoontology/evolution/session.py"
click node_evaluation "https://github.com/ruc-datalab/evoontology/blob/master/evoontology/evaluation/evaluation.py"
click node_validation "https://github.com/ruc-datalab/evoontology/blob/master/evoontology/validate.py"
click node_adapter "https://github.com/ruc-datalab/evoontology/blob/master/evoontology/evolution/adapter.py"
click node_visualization "https://github.com/ruc-datalab/evoontology/blob/master/evoontology/visualization/preview.py"
click node_renderer "https://github.com/ruc-datalab/evoontology/blob/master/evoontology/visualization/renderer.py"
click node_claude_plugin "https://github.com/ruc-datalab/evoontology/blob/master/plugins/claude-code/evoontology/runtime/mcp_server.py"
click node_codex_plugin "https://github.com/ruc-datalab/evoontology/blob/master/plugins/evoontology-codex/evoontology/runtime/mcp_server.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_workspace_ctx,node_ontology_model,node_ontology_store toneBlue
class node_semantic_runtime,node_tool_layer,node_mcp_server toneAmber
class node_workflow,node_operations,node_trajectory,node_trigger,node_evolution,node_evaluation,node_validation toneMint
class node_adapter,node_visualization,node_renderer,node_claude_plugin,node_codex_plugin toneRose
class node_agent toneIndigo
```

## Components

### Workspace & Ontology

- [Workspace Context](https://github.com/ruc-datalab/evoontology/blob/master/evoontology/workspace.py): `evoontology/workspace.py`
- [Ontology Records](https://github.com/ruc-datalab/evoontology/blob/master/evoontology/ontology/models.py): `evoontology/ontology/models.py`
- [Versioned Store](https://github.com/ruc-datalab/evoontology/blob/master/evoontology/ontology/store.py): `evoontology/ontology/store.py`

### Agent Runtime

- [Semantic Runtime](https://github.com/ruc-datalab/evoontology/blob/master/evoontology/runtime/runtime.py): `evoontology/runtime/runtime.py`
- [Semantic Tools](https://github.com/ruc-datalab/evoontology/blob/master/evoontology/runtime/tools.py): `evoontology/runtime/tools.py`
- [MCP Server](https://github.com/ruc-datalab/evoontology/blob/master/evoontology/runtime/mcp_server.py): `evoontology/runtime/mcp_server.py`

### Workload & Evolution

- [Workload Workflow](https://github.com/ruc-datalab/evoontology/blob/master/evoontology/workflow.py): `evoontology/workflow.py`
- [Lifecycle Operations](https://github.com/ruc-datalab/evoontology/blob/master/evoontology/runtime/ops.py): `evoontology/runtime/ops.py`
- [Task Trajectories](https://github.com/ruc-datalab/evoontology/blob/master/evoontology/trajectory/trajectory.py): `evoontology/trajectory/trajectory.py`
- [Evolution Trigger](https://github.com/ruc-datalab/evoontology/blob/master/evoontology/trigger/trigger.py): `evoontology/trigger/trigger.py`
- [Evolution Session](https://github.com/ruc-datalab/evoontology/blob/master/evoontology/evolution/session.py): `evoontology/evolution/session.py`
- [Candidate Evaluation](https://github.com/ruc-datalab/evoontology/blob/master/evoontology/evaluation/evaluation.py): `evoontology/evaluation/evaluation.py`
- [Ontology Validation](https://github.com/ruc-datalab/evoontology/blob/master/evoontology/validate.py): `evoontology/validate.py`

### Adapters & Views

- [Agent Adapter](https://github.com/ruc-datalab/evoontology/blob/master/evoontology/evolution/adapter.py): `evoontology/evolution/adapter.py`
- [Ontology Preview](https://github.com/ruc-datalab/evoontology/blob/master/evoontology/visualization/preview.py): `evoontology/visualization/preview.py`
- [Ontology Renderer](https://github.com/ruc-datalab/evoontology/blob/master/evoontology/visualization/renderer.py): `evoontology/visualization/renderer.py`
- [Claude Code Plugin](https://github.com/ruc-datalab/evoontology/blob/master/plugins/claude-code/evoontology/runtime/mcp_server.py): `plugins/claude-code/evoontology/runtime/mcp_server.py`
- [Codex Plugin](https://github.com/ruc-datalab/evoontology/blob/master/plugins/evoontology-codex/evoontology/runtime/mcp_server.py): `plugins/evoontology-codex/evoontology/runtime/mcp_server.py`

### Other components

- **Data Agent**

## Connections

- Data Agent → MCP Server: queries semantics (evidence: `README.md`)
- MCP Server → Semantic Runtime: dispatches tools
- Semantic Tools → Semantic Runtime: exposes operations
- Semantic Runtime → Versioned Store: reads version (evidence: `evoontology/runtime/runtime.py`)
- Versioned Store → Ontology Records: loads records (evidence: `evoontology/ontology/store.py`)
- Workload Workflow → Workspace Context: uses workspace (evidence: `evoontology/workflow.py`)
- Workload Workflow → Task Trajectories: reads history (evidence: `evoontology/workflow.py`)
- Lifecycle Operations → Workload Workflow: invokes workflow (evidence: `evoontology/runtime/ops.py`)
- Lifecycle Operations → Evolution Session: starts evolution (evidence: `evoontology/runtime/ops.py`)
- Lifecycle Operations → Evolution Trigger: checks due state (evidence: `evoontology/runtime/ops.py`)
- Lifecycle Operations → Ontology Validation: validates versions (evidence: `evoontology/runtime/ops.py`)
- Lifecycle Operations → Ontology Preview: previews ontology (evidence: `evoontology/runtime/ops.py`)
- Task Trajectories → Workspace Context: stores in workspace (evidence: `evoontology/trajectory/trajectory.py`)
- Evolution Trigger → Task Trajectories: counts new tasks (evidence: `evoontology/trigger/trigger.py`)
- Evolution Session → Evolution Trigger: consults gate (evidence: `evoontology/evolution/session.py`)
- Evolution Session → Candidate Evaluation: runs comparisons (evidence: `evoontology/evolution/session.py`)
- Evolution Session → Ontology Validation: validates candidate (evidence: `evoontology/evolution/session.py`)
- Evolution Session → Versioned Store: publishes candidate (evidence: `evoontology/evolution/session.py`)
- Agent Adapter → Evolution Session: supports session (evidence: `evoontology/evolution/session.py`)
- Ontology Renderer → Versioned Store: reads ontology (evidence: `evoontology/visualization/renderer.py`)
- Ontology Renderer → Semantic Runtime: renders runtime (evidence: `evoontology/visualization/renderer.py`)
- Claude Code Plugin → Data Agent: integrates agent (evidence: `README.md`)
- Codex Plugin → Data Agent: integrates agent (evidence: `README.md`)
