# ibm/assetopsbench architecture

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

- Interactive diagram: https://gitdiagram.com/ibm/assetopsbench
- Repository: https://github.com/ibm/assetopsbench

## Overview

AssetOpsBench is a framework for industrial asset-operations agents, MCP domain tools, and offline evaluation. The primary workflow is an engineer’s question handled by an agent, which uses domain servers to retrieve asset, work-order, failure-mode, or time-series evidence and return an operational answer. Distinct branches provide TSFM forecasting and catalog workflows, vibration analysis, and evaluation/reporting. The graph reflects documented capabilities and indexed imports; unsampled implementation details are not assumed, so uncertain relationships are omitted.

Main entry points: [`src/agent/runner.py`](https://github.com/ibm/assetopsbench/blob/main/src/agent/runner.py) (Agent runner), [`src/servers/tsfm/main.py`](https://github.com/ibm/assetopsbench/blob/main/src/servers/tsfm/main.py) (TSFM tool server), [`src/servers/tsfm/engine/composition.py`](https://github.com/ibm/assetopsbench/blob/main/src/servers/tsfm/engine/composition.py) (Recipe composition), [`src/evaluation/runner.py`](https://github.com/ibm/assetopsbench/blob/main/src/evaluation/runner.py) (Evaluation runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agents["Agent orchestration"]
  node_agent_runner["Agent runner<br/>[runner.py]"]
  node_plan_execute["Plan-execute<br/>[executor.py]"]
  node_deep_agent["Deep Agent<br/>[runner.py]"]
  node_claude_agent["Claude Agent<br/>[runner.py]"]
  node_openai_agent["OpenAI Agent<br/>[runner.py]"]
  node_opencode_agent["OpenCode Agent<br/>[runner.py]"]
  node_stirrup_agent["Stirrup Agent<br/>[runner.py]"]
end

subgraph group_llm["Model backends"]
  node_llm_backend["LLM backend<br/>[base.py]"]
  node_llm_factory["Backend selection<br/>[__init__.py]"]
  node_llm_router["Proxy routing<br/>[routers.py]"]
end

subgraph group_domains["Industrial MCP tools"]
  node_iot_server["IoT assets and sensors<br/>[main.py]"]
  node_fmsr_server["Failure modes<br/>[main.py]"]
  node_wo_server["Work orders<br/>[main.py]"]
  node_wo_lifecycle["Work-order lifecycle<br/>[workorders.py]"]
  node_vibration_server["Vibration diagnostics<br/>[main.py]"]
  node_vibration_dsp["Signal analysis<br/>[fault_detection.py]"]
  node_utilities["Shared utilities<br/>[main.py]"]
end

subgraph group_tsfm["Time-series analysis"]
  node_tsfm_server["TSFM tool server<br/>[main.py]"]
  node_tsfm_composition["Recipe composition<br/>[composition.py]"]
  node_tsfm_reasoning["Feature reasoning"]
  node_model_store[("Model catalog<br/>[model_store.py]")]
  node_feature_store[("Feature catalog<br/>[feature_store.py]")]
  node_model_resolver["Model resolver<br/>[resolver.py]"]
end

subgraph group_evaluation["Evaluation and telemetry"]
  node_evaluation_runner["Evaluation runner<br/>[runner.py]"]
  node_evaluation_scorers["Scenario scorers<br/>[static_json.py]"]
  node_llm_judge["LLM judge<br/>[llm_judge.py]"]
  node_evaluation_metrics["Metrics<br/>[metrics.py]"]
  node_evaluation_report["Reports<br/>[report.py]"]
  node_observability["Tracing and persistence<br/>[tracing.py]"]
end

node_engineer(("Maintenance engineer"))
node_couchdb[("CouchDB")]
node_mcp{{"MCP tool environment"}}

node_engineer -->|"asks task"| node_agent_runner
node_agent_runner -.->|"selects framework"| node_plan_execute
node_agent_runner -.->|"selects framework"| node_deep_agent
node_agent_runner -.->|"selects framework"| node_claude_agent
node_agent_runner -.->|"selects framework"| node_openai_agent
node_agent_runner -.->|"selects framework"| node_opencode_agent
node_agent_runner -.->|"selects framework"| node_stirrup_agent
node_agent_runner -->|"creates backend"| node_llm_factory
node_llm_factory -->|"selects implementation"| node_llm_backend
node_llm_factory -->|"checks prefix"| node_llm_router
node_agent_runner -->|"uses tool servers"| node_mcp
node_mcp -->|"exposes tools"| node_iot_server
node_mcp -->|"exposes tools"| node_fmsr_server
node_mcp -->|"exposes tools"| node_wo_server
node_mcp -->|"exposes tools"| node_vibration_server
node_mcp -->|"exposes tools"| node_tsfm_server
node_mcp -->|"exposes tools"| node_utilities
node_wo_server -->|"delegates lifecycle"| node_wo_lifecycle
node_wo_server -->|"reads and writes"| node_couchdb
node_iot_server -->|"queries asset data"| node_couchdb
node_vibration_server -->|"runs diagnostics"| node_vibration_dsp
node_vibration_server -->|"loads sensor data"| node_couchdb
node_tsfm_server -->|"dispatches recipes"| node_tsfm_composition
node_tsfm_server -->|"uses feature selection"| node_tsfm_reasoning
node_tsfm_server -->|"looks up models"| node_model_store
node_tsfm_server -->|"looks up features"| node_feature_store
node_tsfm_server -->|"resolves models"| node_model_resolver
node_tsfm_composition -->|"loads model cards"| node_model_store
node_tsfm_composition -->|"loads feature cards"| node_feature_store
node_tsfm_composition -->|"resolves model"| node_model_resolver
node_tsfm_server -->|"uses catalog data"| node_couchdb
node_evaluation_runner -.->|"scores scenarios"| node_evaluation_scorers
node_evaluation_runner -.->|"calculates metrics"| node_evaluation_metrics
node_evaluation_runner -.->|"produces report"| node_evaluation_report
node_evaluation_scorers -->|"offers judge scorer"| node_llm_judge
node_llm_judge -->|"requests judgment"| node_llm_backend
node_evaluation_report -->|"summarizes metrics"| node_evaluation_metrics
node_observability -.->|"exports traces"| node_couchdb

click node_agent_runner "https://github.com/ibm/assetopsbench/blob/main/src/agent/runner.py"
click node_plan_execute "https://github.com/ibm/assetopsbench/blob/main/src/agent/plan_execute/executor.py"
click node_deep_agent "https://github.com/ibm/assetopsbench/blob/main/src/agent/deep_agent/runner.py"
click node_claude_agent "https://github.com/ibm/assetopsbench/blob/main/src/agent/claude_agent/runner.py"
click node_openai_agent "https://github.com/ibm/assetopsbench/blob/main/src/agent/openai_agent/runner.py"
click node_opencode_agent "https://github.com/ibm/assetopsbench/blob/main/src/agent/opencode_agent/runner.py"
click node_stirrup_agent "https://github.com/ibm/assetopsbench/blob/main/src/agent/stirrup_agent/runner.py"
click node_llm_backend "https://github.com/ibm/assetopsbench/blob/main/src/llm/base.py"
click node_llm_factory "https://github.com/ibm/assetopsbench/blob/main/src/llm/__init__.py"
click node_llm_router "https://github.com/ibm/assetopsbench/blob/main/src/llm/routers.py"
click node_iot_server "https://github.com/ibm/assetopsbench/blob/main/src/servers/iot/main.py"
click node_fmsr_server "https://github.com/ibm/assetopsbench/blob/main/src/servers/fmsr/main.py"
click node_wo_server "https://github.com/ibm/assetopsbench/blob/main/src/servers/wo/main.py"
click node_wo_lifecycle "https://github.com/ibm/assetopsbench/blob/main/src/servers/wo/workorders.py"
click node_vibration_server "https://github.com/ibm/assetopsbench/blob/main/src/servers/vibration/main.py"
click node_vibration_dsp "https://github.com/ibm/assetopsbench/blob/main/src/servers/vibration/dsp/fault_detection.py"
click node_utilities "https://github.com/ibm/assetopsbench/blob/main/src/servers/utilities/main.py"
click node_tsfm_server "https://github.com/ibm/assetopsbench/blob/main/src/servers/tsfm/main.py"
click node_tsfm_composition "https://github.com/ibm/assetopsbench/blob/main/src/servers/tsfm/engine/composition.py"
click node_tsfm_reasoning "https://github.com/ibm/assetopsbench/blob/main/src/servers/tsfm/reasoning/feature_selection.py"
click node_model_store "https://github.com/ibm/assetopsbench/blob/main/src/servers/tsfm/stores/model_store.py"
click node_feature_store "https://github.com/ibm/assetopsbench/blob/main/src/servers/tsfm/stores/feature_store.py"
click node_model_resolver "https://github.com/ibm/assetopsbench/blob/main/src/servers/tsfm/substrate/resolver.py"
click node_evaluation_runner "https://github.com/ibm/assetopsbench/blob/main/src/evaluation/runner.py"
click node_evaluation_scorers "https://github.com/ibm/assetopsbench/blob/main/src/evaluation/scorers/static_json.py"
click node_llm_judge "https://github.com/ibm/assetopsbench/blob/main/src/evaluation/scorers/llm_judge.py"
click node_evaluation_metrics "https://github.com/ibm/assetopsbench/blob/main/src/evaluation/metrics.py"
click node_evaluation_report "https://github.com/ibm/assetopsbench/blob/main/src/evaluation/report.py"
click node_observability "https://github.com/ibm/assetopsbench/blob/main/src/observability/tracing.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_agent_runner,node_plan_execute,node_deep_agent,node_claude_agent,node_openai_agent,node_opencode_agent,node_stirrup_agent toneBlue
class node_llm_backend,node_llm_factory,node_llm_router,node_couchdb toneAmber
class node_iot_server,node_fmsr_server,node_wo_server,node_wo_lifecycle,node_vibration_server,node_vibration_dsp,node_utilities toneMint
class node_tsfm_server,node_tsfm_composition,node_tsfm_reasoning,node_model_store,node_feature_store,node_model_resolver toneRose
class node_evaluation_runner,node_evaluation_scorers,node_llm_judge,node_evaluation_metrics,node_evaluation_report,node_observability,node_engineer,node_mcp toneIndigo
```

## Components

### Agent orchestration

- [Agent runner](https://github.com/ibm/assetopsbench/blob/main/src/agent/runner.py): `src/agent/runner.py`
- [Plan-execute](https://github.com/ibm/assetopsbench/blob/main/src/agent/plan_execute/executor.py): `src/agent/plan_execute/executor.py`
- [Deep Agent](https://github.com/ibm/assetopsbench/blob/main/src/agent/deep_agent/runner.py): `src/agent/deep_agent/runner.py`
- [Claude Agent](https://github.com/ibm/assetopsbench/blob/main/src/agent/claude_agent/runner.py): `src/agent/claude_agent/runner.py`
- [OpenAI Agent](https://github.com/ibm/assetopsbench/blob/main/src/agent/openai_agent/runner.py): `src/agent/openai_agent/runner.py`
- [OpenCode Agent](https://github.com/ibm/assetopsbench/blob/main/src/agent/opencode_agent/runner.py): `src/agent/opencode_agent/runner.py`
- [Stirrup Agent](https://github.com/ibm/assetopsbench/blob/main/src/agent/stirrup_agent/runner.py): `src/agent/stirrup_agent/runner.py`

### Model backends

- [LLM backend](https://github.com/ibm/assetopsbench/blob/main/src/llm/base.py): `src/llm/base.py`
- [Backend selection](https://github.com/ibm/assetopsbench/blob/main/src/llm/__init__.py): `src/llm/__init__.py`
- [Proxy routing](https://github.com/ibm/assetopsbench/blob/main/src/llm/routers.py): `src/llm/routers.py`

### Industrial MCP tools

- [IoT assets and sensors](https://github.com/ibm/assetopsbench/blob/main/src/servers/iot/main.py): `src/servers/iot/main.py`
- [Failure modes](https://github.com/ibm/assetopsbench/blob/main/src/servers/fmsr/main.py): `src/servers/fmsr/main.py`
- [Work orders](https://github.com/ibm/assetopsbench/blob/main/src/servers/wo/main.py): `src/servers/wo/main.py`
- [Work-order lifecycle](https://github.com/ibm/assetopsbench/blob/main/src/servers/wo/workorders.py): `src/servers/wo/workorders.py`
- [Vibration diagnostics](https://github.com/ibm/assetopsbench/blob/main/src/servers/vibration/main.py): `src/servers/vibration/main.py`
- [Signal analysis](https://github.com/ibm/assetopsbench/blob/main/src/servers/vibration/dsp/fault_detection.py): `src/servers/vibration/dsp/fault_detection.py`
- [Shared utilities](https://github.com/ibm/assetopsbench/blob/main/src/servers/utilities/main.py): `src/servers/utilities/main.py`

### Time-series analysis

- [TSFM tool server](https://github.com/ibm/assetopsbench/blob/main/src/servers/tsfm/main.py): `src/servers/tsfm/main.py`
- [Recipe composition](https://github.com/ibm/assetopsbench/blob/main/src/servers/tsfm/engine/composition.py): `src/servers/tsfm/engine/composition.py`
- [Feature reasoning](https://github.com/ibm/assetopsbench/blob/main/src/servers/tsfm/reasoning/feature_selection.py): `src/servers/tsfm/reasoning/feature_selection.py`
- [Model catalog](https://github.com/ibm/assetopsbench/blob/main/src/servers/tsfm/stores/model_store.py): `src/servers/tsfm/stores/model_store.py`
- [Feature catalog](https://github.com/ibm/assetopsbench/blob/main/src/servers/tsfm/stores/feature_store.py): `src/servers/tsfm/stores/feature_store.py`
- [Model resolver](https://github.com/ibm/assetopsbench/blob/main/src/servers/tsfm/substrate/resolver.py): `src/servers/tsfm/substrate/resolver.py`

### Evaluation and telemetry

- [Evaluation runner](https://github.com/ibm/assetopsbench/blob/main/src/evaluation/runner.py): `src/evaluation/runner.py`
- [Scenario scorers](https://github.com/ibm/assetopsbench/blob/main/src/evaluation/scorers/static_json.py): `src/evaluation/scorers/static_json.py`
- [LLM judge](https://github.com/ibm/assetopsbench/blob/main/src/evaluation/scorers/llm_judge.py): `src/evaluation/scorers/llm_judge.py`
- [Metrics](https://github.com/ibm/assetopsbench/blob/main/src/evaluation/metrics.py): `src/evaluation/metrics.py`
- [Reports](https://github.com/ibm/assetopsbench/blob/main/src/evaluation/report.py): `src/evaluation/report.py`
- [Tracing and persistence](https://github.com/ibm/assetopsbench/blob/main/src/observability/tracing.py): `src/observability/tracing.py`

### Other components

- **Maintenance engineer**
- **CouchDB**
- **MCP tool environment**

## Connections

- Maintenance engineer → Agent runner: asks task (evidence: `README.md`)
- Agent runner → Plan-execute: selects framework (evidence: `README.md`)
- Agent runner → Deep Agent: selects framework (evidence: `README.md`)
- Agent runner → Claude Agent: selects framework (evidence: `README.md`)
- Agent runner → OpenAI Agent: selects framework (evidence: `README.md`)
- Agent runner → OpenCode Agent: selects framework (evidence: `src/agent/opencode_agent/runner.py`)
- Agent runner → Stirrup Agent: selects framework (evidence: `src/agent/stirrup_agent/runner.py`)
- Agent runner → Backend selection: creates backend (evidence: `src/agent/runner.py`)
- Backend selection → LLM backend: selects implementation (evidence: `src/llm/__init__.py`)
- Backend selection → Proxy routing: checks prefix (evidence: `src/llm/__init__.py`)
- Agent runner → MCP tool environment: uses tool servers (evidence: `README.md`)
- MCP tool environment → IoT assets and sensors: exposes tools (evidence: `README.md`)
- MCP tool environment → Failure modes: exposes tools (evidence: `README.md`)
- MCP tool environment → Work orders: exposes tools (evidence: `README.md`)
- MCP tool environment → Vibration diagnostics: exposes tools (evidence: `README.md`)
- MCP tool environment → TSFM tool server: exposes tools (evidence: `README.md`)
- MCP tool environment → Shared utilities: exposes tools (evidence: `README.md`)
- Work orders → Work-order lifecycle: delegates lifecycle (evidence: `src/servers/wo/main.py`)
- Work orders → CouchDB: reads and writes (evidence: `src/servers/wo/main.py`)
- IoT assets and sensors → CouchDB: queries asset data (evidence: `src/servers/iot/main.py`)
- Vibration diagnostics → Signal analysis: runs diagnostics (evidence: `src/servers/vibration/main.py`)
- Vibration diagnostics → CouchDB: loads sensor data (evidence: `src/servers/vibration/main.py`)
- TSFM tool server → Recipe composition: dispatches recipes (evidence: `src/servers/tsfm/main.py`)
- TSFM tool server → Feature reasoning: uses feature selection (evidence: `src/servers/tsfm/main.py`)
- TSFM tool server → Model catalog: looks up models (evidence: `src/servers/tsfm/main.py`)
- TSFM tool server → Feature catalog: looks up features (evidence: `src/servers/tsfm/main.py`)
- TSFM tool server → Model resolver: resolves models (evidence: `src/servers/tsfm/main.py`)
- Recipe composition → Model catalog: loads model cards (evidence: `src/servers/tsfm/engine/composition.py`)
- Recipe composition → Feature catalog: loads feature cards (evidence: `src/servers/tsfm/engine/composition.py`)
- Recipe composition → Model resolver: resolves model (evidence: `src/servers/tsfm/engine/composition.py`)
- TSFM tool server → CouchDB: uses catalog data (evidence: `src/servers/tsfm/main.py`)
- Evaluation runner → Scenario scorers: scores scenarios
- Evaluation runner → Metrics: calculates metrics
- Evaluation runner → Reports: produces report
- Scenario scorers → LLM judge: offers judge scorer
- LLM judge → LLM backend: requests judgment (evidence: `src/evaluation/scorers/llm_judge.py`)
- Reports → Metrics: summarizes metrics (evidence: `src/evaluation/report.py`)
- Tracing and persistence → CouchDB: exports traces
