# nvidia-nemo/labs-oo-agents architecture

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

- Interactive diagram: https://gitdiagram.com/nvidia-nemo/labs-oo-agents
- Repository: https://github.com/nvidia-nemo/labs-oo-agents

## Overview

NOOA is a Python framework for building model-agnostic agents whose typed Python objects combine state, prompts, deterministic methods, and LLM-driven capabilities. Its principal workflow is to define an agent method, assemble context and callable interfaces, let a strategy generate and execute code, and return a typed result. Runtime events, persistence, and tracing support that workflow. The repository also documents optional coding-agent, long-term memory, benchmark, evaluation, CLI, and trace-viewer products. Some subsystem paths are known from the tree, but unsampled integration wiring is not inferred.

Main entry points: [`src/nooa/agent.py`](https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/agent.py) (Agent object), [`src/nooa/strategies/codeact.py`](https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/strategies/codeact.py) (Agent strategies), [`src/nooa/runtime/actor.py`](https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/runtime/actor.py) (Execution runtime), [`src/nooa/runtime/event_manager.py`](https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/runtime/event_manager.py) (Event manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent_runtime["Agent runtime"]
  node_agent["Agent object<br/>[agent.py]"]
  node_method["Agent methods<br/>[method_llm.py]"]
  node_context["Context blocks<br/>[context_manager.py]"]
  node_context_builder["Context builder<br/>[context_builder.py]"]
  node_skill["Skills and tools<br/>[skill.py]"]
end

subgraph group_execution_model["Execution and models"]
  node_strategy["Agent strategies<br/>[codeact.py]"]
  node_runtime["Execution runtime<br/>[actor.py]"]
  node_sandbox["Code sandbox<br/>[executor.py]"]
  node_validator["Code validation<br/>[code_validator.py]"]
  node_llm["Unified LLM client<br/>[unifiedllm.py]"]
end

subgraph group_state_observability["State and observability"]
  node_event_manager["Event manager<br/>[event_manager.py]"]
  node_event_backend["Event backend<br/>[event_backend.py]"]
  node_storage["Agent persistence<br/>[manager.py]"]
  node_sqlite[("SQLite storage<br/>[sqlite.py]")]
  node_tracing["Tracing exporters<br/>[exporters.py]"]
end

subgraph group_product_tools["Product extensions"]
  node_memory["Long-term memory<br/>[manager.py]"]
  node_acp["ACP coding adapter<br/>[server.py]"]
  node_bench["Benchmark runner<br/>[runner.py]"]
  node_eval_pipeline["Evaluation pipeline<br/>[pipeline.py]"]
  node_cli["CLI commands<br/>[traces.py]"]
  node_viewer["Trace viewer API<br/>[trace_routes.py]"]
  node_eval_viewer["Evaluation viewer API<br/>[eval_routes.py]"]
  node_trace_store[("OTLP trace store<br/>[otlp_store.py]")]
  node_viewer_ui["Trace and eval UI<br/>[App.tsx]"]
end

node_developer(("Agent developer"))
node_provider(("Model provider"))

node_developer -->|"defines"| node_agent
node_agent -->|"exposes"| node_method
node_method -->|"dispatches"| node_strategy
node_strategy -->|"builds context"| node_context_builder
node_context_builder -->|"resolves blocks"| node_context
node_strategy -->|"uses interfaces"| node_skill
node_strategy -->|"requests generation"| node_llm
node_llm -->|"sends requests"| node_provider
node_strategy -->|"runs agent turn"| node_runtime
node_runtime -->|"checks generated code"| node_validator
node_runtime -->|"executes code"| node_sandbox
node_agent -->|"owns events"| node_event_manager
node_event_manager -->|"records events"| node_event_backend
node_agent -->|"saves or restores"| node_storage
node_storage -->|"persists state"| node_sqlite
node_event_manager -.->|"exports telemetry"| node_tracing
node_memory -.->|"installs hooks"| node_agent
node_acp -.->|"serves coding sessions"| node_agent
node_bench -.->|"runs benchmarks"| node_agent
node_eval_pipeline -.->|"executes samples"| node_agent
node_cli -.->|"supports trace workflows"| node_viewer
node_viewer -->|"reads and manages traces"| node_trace_store
node_eval_viewer -->|"reads evaluation traces"| node_trace_store
node_viewer_ui -->|"requests trace data"| node_viewer
node_viewer_ui -->|"requests eval data"| node_eval_viewer

click node_agent "https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/agent.py"
click node_method "https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/method_llm.py"
click node_context "https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/runtime/context_manager.py"
click node_context_builder "https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/runtime/context_builder.py"
click node_skill "https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/skill.py"
click node_strategy "https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/strategies/codeact.py"
click node_runtime "https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/runtime/actor.py"
click node_sandbox "https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/runtime/sandbox/executor.py"
click node_validator "https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/runtime/code_validator.py"
click node_llm "https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/unifiedllm/unifiedllm.py"
click node_event_manager "https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/runtime/event_manager.py"
click node_event_backend "https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/runtime/event_backend.py"
click node_storage "https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/storage/manager.py"
click node_sqlite "https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/storage/sqlite.py"
click node_tracing "https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/tracing/exporters.py"
click node_memory "https://github.com/nvidia-nemo/labs-oo-agents/blob/main/packages/nooa-memory/src/nooa_memory/manager.py"
click node_acp "https://github.com/nvidia-nemo/labs-oo-agents/blob/main/packages/nooa-acp/src/nooa_acp/server.py"
click node_bench "https://github.com/nvidia-nemo/labs-oo-agents/blob/main/packages/nooa-bench/src/nooa_bench/runner.py"
click node_eval_pipeline "https://github.com/nvidia-nemo/labs-oo-agents/blob/main/util/eval_pipeline/src/eval_pipeline/pipeline.py"
click node_cli "https://github.com/nvidia-nemo/labs-oo-agents/blob/main/packages/nooa-cli/src/nooa_cli/commands/traces.py"
click node_viewer "https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/viewer/trace_routes.py"
click node_eval_viewer "https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/viewer/eval_routes.py"
click node_trace_store "https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/viewer/otlp_store.py"
click node_viewer_ui "https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/viewer/frontend-react/src/App.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_agent,node_method,node_context,node_context_builder,node_skill toneBlue
class node_strategy,node_runtime,node_sandbox,node_validator,node_llm toneAmber
class node_event_manager,node_event_backend,node_storage,node_sqlite,node_tracing toneMint
class node_memory,node_acp,node_bench,node_eval_pipeline,node_cli,node_viewer,node_eval_viewer,node_trace_store,node_viewer_ui toneRose
class node_developer,node_provider toneIndigo
```

## Components

### Agent runtime

- [Agent object](https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/agent.py): `src/nooa/agent.py`
- [Agent methods](https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/method_llm.py): `src/nooa/method_llm.py`
- [Context blocks](https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/runtime/context_manager.py): `src/nooa/runtime/context_manager.py`
- [Context builder](https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/runtime/context_builder.py): `src/nooa/runtime/context_builder.py`
- [Skills and tools](https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/skill.py): `src/nooa/skill.py`

### Execution and models

- [Agent strategies](https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/strategies/codeact.py): `src/nooa/strategies/codeact.py`
- [Execution runtime](https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/runtime/actor.py): `src/nooa/runtime/actor.py`
- [Code sandbox](https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/runtime/sandbox/executor.py): `src/nooa/runtime/sandbox/executor.py`
- [Code validation](https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/runtime/code_validator.py): `src/nooa/runtime/code_validator.py`
- [Unified LLM client](https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/unifiedllm/unifiedllm.py): `src/nooa/unifiedllm/unifiedllm.py`

### State and observability

- [Event manager](https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/runtime/event_manager.py): `src/nooa/runtime/event_manager.py`
- [Event backend](https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/runtime/event_backend.py): `src/nooa/runtime/event_backend.py`
- [Agent persistence](https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/storage/manager.py): `src/nooa/storage/manager.py`
- [SQLite storage](https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/storage/sqlite.py): `src/nooa/storage/sqlite.py`
- [Tracing exporters](https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/tracing/exporters.py): `src/nooa/tracing/exporters.py`

### Product extensions

- [Long-term memory](https://github.com/nvidia-nemo/labs-oo-agents/blob/main/packages/nooa-memory/src/nooa_memory/manager.py): `packages/nooa-memory/src/nooa_memory/manager.py`
- [ACP coding adapter](https://github.com/nvidia-nemo/labs-oo-agents/blob/main/packages/nooa-acp/src/nooa_acp/server.py): `packages/nooa-acp/src/nooa_acp/server.py`
- [Benchmark runner](https://github.com/nvidia-nemo/labs-oo-agents/blob/main/packages/nooa-bench/src/nooa_bench/runner.py): `packages/nooa-bench/src/nooa_bench/runner.py`
- [Evaluation pipeline](https://github.com/nvidia-nemo/labs-oo-agents/blob/main/util/eval_pipeline/src/eval_pipeline/pipeline.py): `util/eval_pipeline/src/eval_pipeline/pipeline.py`
- [CLI commands](https://github.com/nvidia-nemo/labs-oo-agents/blob/main/packages/nooa-cli/src/nooa_cli/commands/traces.py): `packages/nooa-cli/src/nooa_cli/commands/traces.py`
- [Trace viewer API](https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/viewer/trace_routes.py): `src/nooa/viewer/trace_routes.py`
- [Evaluation viewer API](https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/viewer/eval_routes.py): `src/nooa/viewer/eval_routes.py`
- [OTLP trace store](https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/viewer/otlp_store.py): `src/nooa/viewer/otlp_store.py`
- [Trace and eval UI](https://github.com/nvidia-nemo/labs-oo-agents/blob/main/src/nooa/viewer/frontend-react/src/App.tsx): `src/nooa/viewer/frontend-react/src/App.tsx`

### Other components

- **Agent developer**
- **Model provider**

## Connections

- Agent developer → Agent object: defines
- Agent object → Agent methods: exposes
- Agent methods → Agent strategies: dispatches
- Agent strategies → Context builder: builds context
- Context builder → Context blocks: resolves blocks
- Agent strategies → Skills and tools: uses interfaces
- Agent strategies → Unified LLM client: requests generation
- Unified LLM client → Model provider: sends requests
- Agent strategies → Execution runtime: runs agent turn
- Execution runtime → Code validation: checks generated code
- Execution runtime → Code sandbox: executes code
- Agent object → Event manager: owns events
- Event manager → Event backend: records events
- Agent object → Agent persistence: saves or restores
- Agent persistence → SQLite storage: persists state
- Event manager → Tracing exporters: exports telemetry
- Long-term memory → Agent object: installs hooks
- ACP coding adapter → Agent object: serves coding sessions
- Benchmark runner → Agent object: runs benchmarks
- Evaluation pipeline → Agent object: executes samples
- CLI commands → Trace viewer API: supports trace workflows
- Trace viewer API → OTLP trace store: reads and manages traces
- Evaluation viewer API → OTLP trace store: reads evaluation traces
- Trace and eval UI → Trace viewer API: requests trace data
- Trace and eval UI → Evaluation viewer API: requests eval data