From 775ca8af373f475c19b136ab44f36e04bab162bf Mon Sep 17 00:00:00 2001
From: Thorrester <sjforrester32@gmail.com>
Date: Fri, 15 May 2026 11:24:36 -0400
Subject: [PATCH 1/2] update contracts

---
 .claude/skills/opsml-rust-python/SKILL.md     |  49 +
 .../references/agent-harness.md               |  55 ++
 .../references/architecture.md                |  73 ++
 .../opsml-rust-python/references/errors.md    |  84 ++
 .../references/pyo3-boundaries.md             |  89 ++
 .../references/python-api-and-stubs.md        |  59 ++
 .../opsml-rust-python/references/rust-core.md | 101 ++
 .../references/testing-workflows.md           |  64 ++
 .claude/skills/opsml-ts-svelte/SKILL.md       | 881 ------------------
 .claude/skills/opsml-ui/SKILL.md              |   1 +
 .codex/skills/opsml-rust-python/SKILL.md      |  49 +
 .../references/agent-harness.md               |  55 ++
 .../references/architecture.md                |  73 ++
 .../opsml-rust-python/references/errors.md    |  84 ++
 .../references/pyo3-boundaries.md             |  89 ++
 .../references/python-api-and-stubs.md        |  59 ++
 .../opsml-rust-python/references/rust-core.md | 101 ++
 .../references/testing-workflows.md           |  64 ++
 .codex/skills/opsml-ui/SKILL.md               |   5 +
 AGENTS.md                                     |  14 +
 CLAUDE.md                                     |  12 +-
 Makefile                                      | 232 -----
 .../evaluation/AgentEvalDashboard.svelte      |  51 +-
 .../evaluation/AgentEvalRecordTable.svelte    |  29 +-
 .../evaluation/AgentEvalWorkflowTable.svelte  |  29 +-
 .../AgentEvalDashboard.pagination.test.ts     | 210 +++++
 .../AgentEvalTables.pagination.test.ts        |  80 ++
 .../agent/observability/AgentsTable.svelte    |  33 +-
 .../__tests__/AgentsTable.test.ts             |  32 +
 .../components/trace/TraceDashboard.svelte    | 197 ++--
 .../components/trace/TraceDashboard.test.ts   | 150 +++
 .../lib/components/trace/TraceTable.svelte    |   4 +-
 .../components/trace/TraceWaterfall.svelte    |  43 +-
 .../trace/__tests__/mockData.test.ts          |  84 ++
 .../src/lib/components/trace/clause.test.ts   | 185 ++++
 .../src/lib/components/trace/clause.ts        | 369 ++++++++
 .../lib/components/trace/clauseEvaluator.ts   |  46 +
 .../components/trace/filters/ChipBar.svelte   |  10 +-
 .../trace/filters/FacetSidebar.svelte         |  57 +-
 .../trace/filters/FacetSidebar.test.ts        |  62 ++
 .../trace/filters/filterState.svelte.ts       | 110 +--
 .../trace/filters/filterState.test.ts         | 177 ++--
 .../trace/genai/__tests__/utils.genai.test.ts |   1 +
 .../src/lib/components/trace/mockData.ts      |  84 +-
 .../src/lib/components/trace/types.ts         |  46 +-
 .../lib/components/trace/validation.test.ts   |  66 ++
 .../src/lib/components/trace/validation.ts    | 278 ++++++
 .../lib/components/trace/waterfall.test.ts    |  77 ++
 .../src/lib/components/trace/waterfall.ts     |  60 ++
 .../src/lib/server/trace/facets.test.ts       |  80 --
 .../opsml_ui/src/lib/server/trace/facets.ts   |  20 -
 .../opsml_ui/src/lib/server/trace/mockData.ts |   1 +
 .../src/lib/server/trace/utils.facets.test.ts |  54 ++
 .../opsml_ui/src/lib/server/trace/utils.ts    |  40 +
 .../scouter/observability/trace/+server.ts    |  14 +-
 .../observability/trace/metrics/+server.ts    |  22 +-
 .../trace/metrics/server.test.ts              | 101 ++
 .../observability/trace/server.test.ts        |  94 ++
 .../observability/trace/types.test-d.ts       |  15 +
 .../api/scouter/trace/facets/+server.ts       |  49 +-
 .../api/scouter/trace/facets/server.test.ts   | 106 +++
 .../[name]/[version]/observability/+page.ts   |   1 -
 .../[name]/[version]/observability/+page.ts   |  42 +-
 .../observability/__tests__/page.test.ts      | 115 +++
 .../src/routes/opsml/observability/+page.ts   |   2 -
 .../opsml_server/tests/api/scouter/trace.rs   |  65 +-
 mise.toml                                     | 225 ++++-
 py-opsml/dev/integration/agent/__init__.py    |   0
 .../dev/integration/agent/agents/__init__.py  |  12 +
 .../dev/integration/agent/agents/callbacks.py | 125 +++
 .../dev/integration/agent/agents/pipeline.py  |  86 ++
 .../dev/integration/agent/agents/responder.py | 136 +++
 .../dev/integration/agent/agents/triage.py    | 104 +++
 .../integration/agent/evaluation/__init__.py  |  18 +
 .../integration/agent/evaluation/evaluate.py  | 125 +++
 .../agent/evaluation/user_agent.py            | 101 ++
 py-opsml/dev/integration/agent/main.py        |  68 ++
 py-opsml/dev/integration/agent/opsmlspec.yaml |  48 +
 .../integration/agent/prompts/responder.yaml  | 100 ++
 .../dev/integration/agent/prompts/triage.yaml |  88 ++
 py-opsml/dev/integration/agent/setup.py       |  22 +
 .../dev/integration/agent/shared/__init__.py  |  10 +
 .../integration/agent/shared/scenarios.jsonl  |   2 +
 .../dev/integration/agent/shared/setup.py     | 167 ++++
 py-opsml/dev/integration/agent/single.py      |  48 +
 py-opsml/examples/benchmarks/_mlflow/run.py   |   5 +-
 py-opsml/examples/benchmarks/_opsml/run.py    |   7 +-
 py-opsml/examples/docs/overview_genai.py      |   2 +-
 .../examples/docs/overview_traditional.py     |   2 +-
 py-opsml/examples/experiment/advanced.py      |  21 +-
 py-opsml/examples/experiment/agent/agent.py   |  26 +-
 .../examples/experiment/agent/setup/models.py |   3 +-
 .../examples/experiment/agent/setup/prompt.py |   6 +-
 .../examples/experiment/agent/setup/tasks.py  |  11 +-
 py-opsml/examples/genai/agent/crewai/agent.py |   4 +-
 py-opsml/examples/genai/agent/google/agent.py |   4 +-
 py-opsml/examples/genai/agent/openai/agent.py |   2 +-
 .../genai/google_adk/app/agent/helper.py      |   1 -
 .../genai/google_adk/app/train/eta.py         |   4 +-
 .../genai/google_adk/app/train/prompt.py      |   4 +-
 .../examples/genai/pydantic/app/train/eta.py  |   2 +-
 .../genai/pydantic/app/train/prompt.py        |   4 +-
 py-opsml/examples/genai/recipe/app/main.py    |  10 +-
 py-opsml/examples/genai/recipe/app/models.py  |   3 +-
 py-opsml/examples/genai/recipe/app/tracing.py |   2 +-
 .../recipe/app/train/evaluation/tasks.py      |  11 +-
 .../examples/genai/recipe/app/train/prompt.py |   6 +-
 py-opsml/examples/getting_started.py          |   5 +-
 py-opsml/makefile                             | 145 ---
 py-opsml/pyproject.toml                       |  49 +-
 py-opsml/python/opsml/__init__.py             |   6 +-
 py-opsml/python/opsml/agent/__init__.py       |   8 +-
 py-opsml/python/opsml/experiment/__init__.py  |   7 +-
 py-opsml/python/opsml/scouter/__init__.py     |   4 +-
 .../python/opsml/scouter/queue/__init__.py    |   6 +-
 .../python/opsml/scouter/tracing/__init__.py  |  14 +-
 py-opsml/tests/cli/test_app.py                |  13 +-
 .../integration/test_adk_agent_harness.py     | 181 ++++
 py-opsml/uv.lock                              | 117 ---
 119 files changed, 5715 insertions(+), 2149 deletions(-)
 create mode 100644 .claude/skills/opsml-rust-python/SKILL.md
 create mode 100644 .claude/skills/opsml-rust-python/references/agent-harness.md
 create mode 100644 .claude/skills/opsml-rust-python/references/architecture.md
 create mode 100644 .claude/skills/opsml-rust-python/references/errors.md
 create mode 100644 .claude/skills/opsml-rust-python/references/pyo3-boundaries.md
 create mode 100644 .claude/skills/opsml-rust-python/references/python-api-and-stubs.md
 create mode 100644 .claude/skills/opsml-rust-python/references/rust-core.md
 create mode 100644 .claude/skills/opsml-rust-python/references/testing-workflows.md
 delete mode 100644 .claude/skills/opsml-ts-svelte/SKILL.md
 create mode 100644 .codex/skills/opsml-rust-python/SKILL.md
 create mode 100644 .codex/skills/opsml-rust-python/references/agent-harness.md
 create mode 100644 .codex/skills/opsml-rust-python/references/architecture.md
 create mode 100644 .codex/skills/opsml-rust-python/references/errors.md
 create mode 100644 .codex/skills/opsml-rust-python/references/pyo3-boundaries.md
 create mode 100644 .codex/skills/opsml-rust-python/references/python-api-and-stubs.md
 create mode 100644 .codex/skills/opsml-rust-python/references/rust-core.md
 create mode 100644 .codex/skills/opsml-rust-python/references/testing-workflows.md
 delete mode 100644 Makefile
 create mode 100644 crates/opsml_server/opsml_ui/src/lib/components/card/agent/evaluation/__tests__/AgentEvalDashboard.pagination.test.ts
 create mode 100644 crates/opsml_server/opsml_ui/src/lib/components/card/agent/evaluation/__tests__/AgentEvalTables.pagination.test.ts
 create mode 100644 crates/opsml_server/opsml_ui/src/lib/components/card/agent/observability/__tests__/AgentsTable.test.ts
 create mode 100644 crates/opsml_server/opsml_ui/src/lib/components/trace/TraceDashboard.test.ts
 create mode 100644 crates/opsml_server/opsml_ui/src/lib/components/trace/__tests__/mockData.test.ts
 create mode 100644 crates/opsml_server/opsml_ui/src/lib/components/trace/clause.test.ts
 create mode 100644 crates/opsml_server/opsml_ui/src/lib/components/trace/clause.ts
 create mode 100644 crates/opsml_server/opsml_ui/src/lib/components/trace/clauseEvaluator.ts
 create mode 100644 crates/opsml_server/opsml_ui/src/lib/components/trace/filters/FacetSidebar.test.ts
 create mode 100644 crates/opsml_server/opsml_ui/src/lib/components/trace/validation.test.ts
 create mode 100644 crates/opsml_server/opsml_ui/src/lib/components/trace/validation.ts
 create mode 100644 crates/opsml_server/opsml_ui/src/lib/components/trace/waterfall.test.ts
 create mode 100644 crates/opsml_server/opsml_ui/src/lib/components/trace/waterfall.ts
 delete mode 100644 crates/opsml_server/opsml_ui/src/lib/server/trace/facets.test.ts
 delete mode 100644 crates/opsml_server/opsml_ui/src/lib/server/trace/facets.ts
 create mode 100644 crates/opsml_server/opsml_ui/src/lib/server/trace/utils.facets.test.ts
 create mode 100644 crates/opsml_server/opsml_ui/src/routes/api/scouter/observability/trace/metrics/server.test.ts
 create mode 100644 crates/opsml_server/opsml_ui/src/routes/api/scouter/observability/trace/server.test.ts
 create mode 100644 crates/opsml_server/opsml_ui/src/routes/api/scouter/observability/trace/types.test-d.ts
 create mode 100644 crates/opsml_server/opsml_ui/src/routes/api/scouter/trace/facets/server.test.ts
 create mode 100644 crates/opsml_server/opsml_ui/src/routes/opsml/agent/[registry]/card/[space]/[name]/[version]/observability/__tests__/page.test.ts
 create mode 100644 py-opsml/dev/integration/agent/__init__.py
 create mode 100644 py-opsml/dev/integration/agent/agents/__init__.py
 create mode 100644 py-opsml/dev/integration/agent/agents/callbacks.py
 create mode 100644 py-opsml/dev/integration/agent/agents/pipeline.py
 create mode 100644 py-opsml/dev/integration/agent/agents/responder.py
 create mode 100644 py-opsml/dev/integration/agent/agents/triage.py
 create mode 100644 py-opsml/dev/integration/agent/evaluation/__init__.py
 create mode 100644 py-opsml/dev/integration/agent/evaluation/evaluate.py
 create mode 100644 py-opsml/dev/integration/agent/evaluation/user_agent.py
 create mode 100644 py-opsml/dev/integration/agent/main.py
 create mode 100644 py-opsml/dev/integration/agent/opsmlspec.yaml
 create mode 100644 py-opsml/dev/integration/agent/prompts/responder.yaml
 create mode 100644 py-opsml/dev/integration/agent/prompts/triage.yaml
 create mode 100644 py-opsml/dev/integration/agent/setup.py
 create mode 100644 py-opsml/dev/integration/agent/shared/__init__.py
 create mode 100644 py-opsml/dev/integration/agent/shared/scenarios.jsonl
 create mode 100644 py-opsml/dev/integration/agent/shared/setup.py
 create mode 100644 py-opsml/dev/integration/agent/single.py
 delete mode 100644 py-opsml/makefile
 create mode 100644 py-opsml/tests/integration/test_adk_agent_harness.py

diff --git a/.claude/skills/opsml-rust-python/SKILL.md b/.claude/skills/opsml-rust-python/SKILL.md
new file mode 100644
index 0000000000..7f6db89ba3
--- /dev/null
+++ b/.claude/skills/opsml-rust-python/SKILL.md
@@ -0,0 +1,49 @@
+---
+name: opsml-rust-python
+description: Repo-local OpsML skill for Rust core, Python bindings, PyO3, maturin, card/registry/server/client logic, Python API exports, generated stubs, and cross-language tests. Use when working in OpsML crates, `py-opsml`, PyO3-exposed types, Rust errors that cross Python, card or registry behavior, server/client contracts, or Python-visible SDK behavior. Do not use for Svelte UI work; use `opsml-ui` instead.
+---
+
+# OpsML Rust/Python
+
+Use this skill as the source of truth for OpsML work where Rust core logic is exposed to Python through PyO3. OpsML is not a generic Rust/Python package: cards are the central abstraction, Rust owns the business logic, and Python is a thin ergonomic API over the Rust core.
+
+Start by locating the layer you are changing:
+- Rust core design, traits, ownership, performance, cloning, async, or crate-local API shape: read `references/rust-core.md`.
+- Rust card, registry, storage, SQL, server, auth, events, or shared contracts: read `references/architecture.md`.
+- PyO3 classes, `#[pymethods]`, GIL usage, nested `#[pyclass]` fields, or Python lifetimes: read `references/pyo3-boundaries.md`.
+- Error types, `PyErr`, server envelopes, CLI errors, or Python exceptions: read `references/errors.md`.
+- Python exports, `__all__`, generated stubs, maturin setup, or Python-visible SDK behavior: read `references/python-api-and-stubs.md`.
+- Tests, linting, formatting, or command selection: read `references/testing-workflows.md`.
+- Agent-readable APIs, structured errors, validation, lint sensors, or harness work: read `references/agent-harness.md`.
+
+Follow these repo-specific rules:
+- Keep core behavior in Rust. Python should expose a typed, ergonomic API and small helpers, not duplicate card, registry, storage, or validation logic.
+- Design Rust APIs around domain-owned data, precise traits, and explicit ownership before thinking about the Python binding.
+- Keep Python lifetimes out of Rust-only code. Introduce `Python<'py>`, `Bound<'py, PyAny>`, `Py<PyAny>`, and `PyErr` only where code crosses the Python boundary.
+- Do not store `PyErr` in reusable Rust error enums. Convert Python errors into string-backed Rust variants, then convert Rust errors back into Python exceptions at the PyO3 boundary.
+- For `#[pyclass]` fields whose type is also `#[pyclass]`, do not use `#[pyo3(get, set)]`. Implement manual `#[getter]` and `#[setter]` methods with `IntoPyObjectExt` and `extract`.
+- Prefer zero-cost Rust abstractions: enums with delegated trait impls, static dispatch, concrete types, precise errors, iterators, references, ownership transfer, and `Arc` only where shared state is real.
+- Treat speculative `Clone`, broad abstractions, unnecessary allocation, and Python-driven core design as design smells. Add them only for concrete call sites.
+- Make new Rust core logic testable without Python whenever possible. Add Python tests for Python-visible workflows.
+- Write errors and API contracts so humans and coding agents can debug them: stable names, clear fields, concise messages, and actionable hints.
+- Use repository workflow tooling from `mise.toml`. Do not invent ad hoc commands when a `mise run ...` task exists.
+- Inspect current dependency versions in `Cargo.toml`, `py-opsml/pyproject.toml`, and lockfiles before relying on version-specific behavior.
+
+When making Rust/PyO3 changes, inspect in this order:
+1. The Rust crate that owns the domain behavior.
+2. Shared types in `opsml-types/src/contracts/` if the behavior crosses server/client/Python boundaries.
+3. PyO3 module registration under `py-opsml/src/`.
+4. Python package re-exports under `py-opsml/python/opsml/`.
+5. Generated stubs under `py-opsml/python/opsml/_opsml.pyi` and `py-opsml/python/opsml/stubs/`.
+6. Rust and Python tests that model the user journey.
+
+Use these verification commands when relevant:
+- Rust formatting: `mise run format`
+- Rust linting: `mise run lints`
+- Targeted Rust tests: `cargo test -p <crate> <test_name> -- --nocapture --test-threads=1`
+- Full Rust aggregate when justified: `mise run test:unit`
+- Rebuild Python bindings after PyO3-exposed Rust changes: `mise run py:setup`
+- Python linting: `mise run py:lints`
+- Python unit tests: `mise run py:test:unit`
+
+Prefer narrow, local edits that match existing OpsML patterns. Broaden the architecture only when the current domain boundary is truly wrong for the user workflow.
diff --git a/.claude/skills/opsml-rust-python/references/agent-harness.md b/.claude/skills/opsml-rust-python/references/agent-harness.md
new file mode 100644
index 0000000000..c42b2171dc
--- /dev/null
+++ b/.claude/skills/opsml-rust-python/references/agent-harness.md
@@ -0,0 +1,55 @@
+# Agent-Friendly OpsML Work
+
+OpsML is being shaped for both human developers and coding agents. The key direction is harness engineering: give agents strong guides before they act and strong sensors after they act.
+
+## Design For Agents And Humans
+
+Code should be readable by humans first and stable enough for agents to modify safely:
+- Keep names domain-specific and unambiguous.
+- Keep functions small enough that invariants are visible.
+- Prefer typed contracts over loose dictionaries or stringly-typed conventions.
+- Surface failures with stable codes, fields, hints, and docs where the repo supports them.
+- Keep side effects at clear boundaries.
+
+## Same Envelope Principle
+
+Harness work should converge on the same structured shape across layers:
+- HTTP responses.
+- PyO3 exceptions.
+- CLI output.
+- `card.validate()`.
+- `opsml lint`.
+- Integrity checks.
+- Eval results.
+
+Use fields such as:
+- `code`
+- `field`
+- `hint` or `suggested_action`
+- `doc_url`
+- `retry`
+
+Agents should not need to parse paragraphs to understand what field to fix.
+
+## Validation And Sensors
+
+When adding governance behavior, think in layers:
+- Edit-time or local lint sensors.
+- Rust-native validation on core types.
+- Registry/server chokepoints.
+- Post-hoc integrity checks.
+- Behavior evals for prompts and agents.
+
+The Rust core should own validations that define durable OpsML correctness. Python should expose them ergonomically and test them as user workflows.
+
+## Documentation Near APIs
+
+Public Rust and Python APIs should include useful docs when they define:
+- User-visible behavior.
+- Required invariants.
+- Error conditions.
+- Security constraints.
+- Serialization formats.
+- Cross-language boundary behavior.
+
+Do not add noisy comments that restate simple code. Add concise comments when they preserve hard-won context, such as why a Python lifetime is intentionally kept at the boundary.
diff --git a/.claude/skills/opsml-rust-python/references/architecture.md b/.claude/skills/opsml-rust-python/references/architecture.md
new file mode 100644
index 0000000000..0998b53ee7
--- /dev/null
+++ b/.claude/skills/opsml-rust-python/references/architecture.md
@@ -0,0 +1,73 @@
+# OpsML Rust/Python Architecture
+
+OpsML is an AI lifecycle platform organized around cards: versioned, encrypted, registry-tracked records for data, models, experiments, prompts, services, agents, and skills. Python users create and operate cards, but the durable behavior belongs in Rust.
+
+## Core Rule
+
+Rust is the source of truth for:
+- Card structure and validation.
+- Registry behavior.
+- Server contracts and route behavior.
+- Storage, SQL, encryption, auth, events, and versioning.
+- Serialization formats that persist or cross process boundaries.
+
+Python should provide:
+- Ergonomic constructors and usage patterns.
+- Thin re-exports from `_opsml`.
+- Small Python-only helpers where Python libraries are the natural boundary.
+- User-journey tests for public Python behavior.
+
+Do not implement durable business logic twice in Rust and Python. If Python and Rust disagree, the design is already drifting.
+
+## Important Crates
+
+- `opsml-cards`: PyO3 card structs and card-specific behavior.
+- `opsml-registry`: Python-facing `CardRegistry`; dispatches to local or server-backed operations.
+- `opsml-types`: shared contract types, enums, and request/response shapes.
+- `opsml-server`: Axum routes, middleware, API handlers, server errors.
+- `opsml-client`: Rust HTTP client used by Python bindings in server mode.
+- `opsml-sql`: database abstraction over SQLite, PostgreSQL, and MySQL.
+- `opsml-storage`: storage abstraction over local and cloud backends.
+- `opsml-crypt`: artifact encryption.
+- `opsml-experiment`, `opsml-genai`, `opsml-service`: domain-specific card logic.
+- `py-opsml`: Python package and PyO3 extension wiring.
+
+Read `AGENTS.md` for the full crate map before changing a cross-cutting path.
+
+## Enum-Based Backends
+
+OpsML favors enum dispatch for core backends:
+- `StorageClientEnum` delegates `StorageClient` methods to local/S3/GCS/Azure variants.
+- `SqlClientEnum` delegates SQL/card logic to SQLite/PostgreSQL/MySQL variants.
+
+When adding a backend or domain variant, follow this pattern before reaching for `Box<dyn Trait>`.
+
+## Contracts And Routes
+
+Shared request/response types belong in `opsml-types/src/contracts/`.
+
+Server routes live under `/opsml/api` and follow the existing handler shape:
+- `State<Arc<AppState>>` for dependencies.
+- `Extension<UserPermissions>` for protected routes, even read-only routes.
+- `Query(...)` or `Json(...)` for inputs.
+- `Result<Json<Response>, (StatusCode, Json<OpsmlServerError>)>` or an established local equivalent.
+
+Use `parse_qs_query::<T>(&uri)` for query strings containing `Vec<T>`.
+
+## Registry Modes
+
+`CardRegistry` supports:
+- Local mode: direct filesystem/SQLite-backed registry operations.
+- Server mode: HTTP proxy through `opsml-client`.
+
+New behavior should preserve both modes unless the feature is explicitly server-only. A change that only works through the Python package but not through Rust registry/server paths is usually in the wrong layer.
+
+## Artifact Encryption
+
+Card artifacts are encrypted before storage. Do not bypass:
+- `create_artifact_key()`
+- `create_and_store_encrypted_file()`
+- `download_artifact()` plus decryption
+- `ArtifactKey` as the database source of truth
+
+Security-sensitive changes need targeted tests around key lookup, upload/download paths, and error behavior.
diff --git a/.claude/skills/opsml-rust-python/references/errors.md b/.claude/skills/opsml-rust-python/references/errors.md
new file mode 100644
index 0000000000..ed1c7a8858
--- /dev/null
+++ b/.claude/skills/opsml-rust-python/references/errors.md
@@ -0,0 +1,84 @@
+# Errors Across Rust And Python
+
+OpsML errors should be clear enough for humans and structured enough for agents. They should name what failed, where possible include the affected field/resource, and preserve enough context to fix the issue without parsing vague prose.
+
+## No Stored `PyErr`
+
+Do not store `PyErr` inside reusable Rust error enums. `PyErr` can pull Python runtime/lifetime concerns into pure Rust code and cause C linker or GIL-related failures in Rust tests.
+
+Use the canonical pattern in `crates/opsml_cards/src/skill/error.rs`:
+- Rust error variants store Rust-owned data such as `String`.
+- `From<PyErr> for SkillError` converts to a string-backed variant.
+- `From<SkillError> for PyErr` exists only behind the Python feature and maps to a Python exception at the boundary.
+
+Preferred shape:
+
+```rust
+#[derive(thiserror::Error, Debug)]
+pub enum DomainError {
+    #[error("{0}")]
+    Error(String),
+
+    #[error(transparent)]
+    Io(#[from] std::io::Error),
+}
+
+#[cfg(feature = "python")]
+impl From<PyErr> for DomainError {
+    fn from(err: PyErr) -> Self {
+        DomainError::Error(err.to_string())
+    }
+}
+
+#[cfg(feature = "python")]
+impl From<DomainError> for PyErr {
+    fn from(err: DomainError) -> PyErr {
+        pyo3::exceptions::PyRuntimeError::new_err(err.to_string())
+    }
+}
+```
+
+Avoid this in core errors:
+
+```rust
+#[error(transparent)]
+Python(#[from] PyErr)
+```
+
+Only use direct Python error storage in code that is permanently Python-only and cannot be reached by Rust tests or Rust core logic. That should be rare in OpsML.
+
+## Transitive Error Chains
+
+The rule applies transitively. If `CardError` wraps `ModelInterfaceError`, and `ModelInterfaceError` stores `PyErr`, then `CardError` is contaminated too.
+
+When adding `#[from]` variants, inspect wrapped errors for PyO3 types. Prefer converting upstream errors to string-backed variants at the boundary.
+
+## Server Error Envelope
+
+Server handlers should use the existing `OpsmlServerError` helpers and structured fields where available. For new agent-facing or validation work, prefer stable data:
+- `code`
+- `field`
+- `suggested_action` or hint
+- `doc_url`
+- `retry`
+
+Prefer one stable error shape across HTTP, PyO3, CLI, lint output, validation, and eval. A Python caller, CLI user, UI route, and coding agent should be able to recognize the same failure without parsing unrelated prose.
+
+## Human And Agent Debuggability
+
+Error messages should:
+- Name the operation that failed.
+- Include the resource identifier when safe, such as card UID, space/name/version, file path, or field.
+- Avoid generic messages like "invalid input" when the failing field is known.
+- Avoid logging secrets, tokens, encryption keys, or provider credentials.
+- Keep wording concise and stable enough for tests and agents.
+
+## Mapping To Python Exceptions
+
+Choose Python exception types deliberately:
+- Invalid user input: `PyValueError`.
+- Missing key or field: `PyKeyError` or `PyValueError`, depending on existing local style.
+- Filesystem/IO: `PyOSError`.
+- Runtime integration failure: `PyRuntimeError`.
+
+Follow nearby mappings in the same crate before introducing a new exception style.
diff --git a/.claude/skills/opsml-rust-python/references/pyo3-boundaries.md b/.claude/skills/opsml-rust-python/references/pyo3-boundaries.md
new file mode 100644
index 0000000000..80a90b0705
--- /dev/null
+++ b/.claude/skills/opsml-rust-python/references/pyo3-boundaries.md
@@ -0,0 +1,89 @@
+# PyO3 Boundary Rules
+
+PyO3 code is a boundary layer. Keep Python lifetimes, `PyErr`, and object extraction at the edge so Rust core code remains testable with normal Rust tests.
+
+## Boundary Types
+
+Use these types only when the code is actually crossing into Python:
+- `Python<'py>`
+- `Bound<'py, PyAny>`
+- `Py<PyAny>`
+- `PyErr`
+- `#[pyclass]`, `#[pymethods]`, `#[pyfunction]`
+
+Pure Rust functions should generally accept and return Rust types, not Python-bound objects.
+
+## Constructors
+
+For Python constructors, keep extraction and conversion near `#[new]`, then call a Rust-native constructor such as `new_rs`, `from_config`, or a domain-specific builder.
+
+Preferred shape:
+
+```rust
+#[cfg(feature = "python")]
+#[pymethods]
+impl SkillCard {
+    #[new]
+    pub fn new(skill: &Bound<'_, PyAny>, space: Option<&str>) -> Result<Self, SkillError> {
+        let skill = skill.extract::<AgentSkillStandard>()?;
+        Self::new_rs(skill, space, None, None, None, None, None, None)
+    }
+}
+```
+
+Keep the Rust-native constructor usable without Python.
+
+## Nested `#[pyclass]` Fields
+
+If a `#[pyclass]` struct has a field whose type is itself a `#[pyclass]`, do not put `#[pyo3(get, set)]` on that field. PyO3-generated accessors can leak Python lifetimes into pure Rust call sites and tests.
+
+Use the canonical pattern in `crates/opsml_cards/src/skill/card.rs`:
+- `skill` field getter at `SkillCard::skill`.
+- `set_skill` setter using `extract`.
+- `dependencies` getter using `IntoPyObjectExt`.
+- `set_dependencies` setter using `extract::<Vec<SkillDependency>>()`.
+
+Preferred shape:
+
+```rust
+#[getter]
+pub fn skill<'py>(&self, py: Python<'py>) -> Result<Bound<'py, PyAny>, SkillError> {
+    Ok(self.skill.clone().into_bound_py_any(py)?)
+}
+
+#[setter]
+pub fn set_skill(&mut self, skill: &Bound<'_, PyAny>) -> Result<(), SkillError> {
+    self.skill = skill.extract::<AgentSkillStandard>()?;
+    Ok(())
+}
+```
+
+## Python Objects In Cards
+
+Some cards hold Python-owned objects, such as model or data interfaces. Keep GIL acquisition scoped tightly:
+- Acquire the GIL only where calling Python methods or extracting Python objects.
+- Convert Python-side data into Rust metadata before serialization.
+- Do not attempt to serialize `Py<PyAny>` directly.
+- Reconstruct Python-facing objects only at load/deserialization boundaries where the Python API needs them.
+
+## Feature Gates
+
+Respect existing `python` and `server` feature gates. If a Rust unit test fails with Python linking or libpython errors, inspect for leaked PyO3 types in core code or transitive error chains.
+
+Common causes:
+- `PyErr` stored in a reusable error enum.
+- `#[pyo3(get, set)]` on nested `#[pyclass]` fields.
+- Python-only imports not guarded with `#[cfg(feature = "python")]`.
+
+## Module Registration
+
+New Python-visible Rust functions/classes must be wired through `py-opsml/src/lib.rs` and the appropriate submodule registration function, such as:
+- `card::add_card_module(m)?`
+- `data::add_data_module(m)?`
+- `model::add_model_module(m)?`
+- `experiment::add_experiment_module(m)?`
+- `agent::add_agent_module(m)?`
+- `service::add_service_module(m)?`
+- `types::add_types_module(m)?`
+
+Do not stop after adding `#[pyclass]`; registration, Python exports, stubs, and tests are part of the public API surface.
diff --git a/.claude/skills/opsml-rust-python/references/python-api-and-stubs.md b/.claude/skills/opsml-rust-python/references/python-api-and-stubs.md
new file mode 100644
index 0000000000..2244c9a0d0
--- /dev/null
+++ b/.claude/skills/opsml-rust-python/references/python-api-and-stubs.md
@@ -0,0 +1,59 @@
+# Python API And Stubs
+
+The Python package is the user-facing SDK, but the Rust extension owns the core behavior. Python additions should be thin, typed, and tested through user workflows.
+
+## Public API Wiring
+
+For new Python-visible Rust API, check every layer:
+1. Rust type/function exists in the owning crate.
+2. PyO3 class/function is registered in the appropriate `py-opsml/src/*` module.
+3. The module is attached from `py-opsml/src/lib.rs`.
+4. Python package exports are updated under `py-opsml/python/opsml/`.
+5. `__all__` is updated where the package uses it.
+6. Stubs are regenerated or updated through the repo workflow.
+7. Python tests cover the user-visible behavior.
+
+Do not leave a type reachable only through `_opsml` unless that is already the local convention for the feature.
+
+## Stub Workflow
+
+Generated stubs live under:
+- `py-opsml/python/opsml/_opsml.pyi`
+- `py-opsml/python/opsml/stubs/`
+
+Use the repo task:
+- `mise run py:setup`
+
+This task runs stub generation, syncs Python dependencies, and builds the Rust extension through maturin. Run it after Rust changes that affect Python-exposed classes, functions, signatures, docs, or enums.
+
+## Python Package Style
+
+Python code should:
+- Keep durable business behavior in Rust.
+- Use typed, ergonomic public APIs.
+- Add docstrings to public functions/classes when intent, side effects, errors, or examples are not obvious.
+- Avoid loose `Any` unless the Python boundary is truly dynamic.
+- Follow existing import, export, and test conventions in `py-opsml/python/opsml/`.
+
+When behavior is Python-only because it depends on a Python ecosystem object, keep the boundary explicit. Examples include Python model/data interfaces where user subclasses implement `save`, `load`, or prediction behavior.
+
+## Python Tests
+
+Python tests should model how a real user interacts with OpsML:
+- Construct the Python-facing object.
+- Register or load through `CardRegistry` when relevant.
+- Assert stable behavior and error messages.
+- Use fixtures such as `mock_db`, `pandas_data`, or `random_forest_classifier` where appropriate.
+
+Do not test generated implementation details when a user workflow test would prove the contract better.
+
+## Maturin And Versions
+
+Do not rely on remembered PyO3 or maturin versions. Inspect:
+- Root `Cargo.toml`.
+- `py-opsml/Cargo.toml`.
+- `py-opsml/pyproject.toml`.
+- Lockfiles.
+- `mise.toml`.
+
+Version-specific PyO3 patterns should match the versions currently pinned by the repository.
diff --git a/.claude/skills/opsml-rust-python/references/rust-core.md b/.claude/skills/opsml-rust-python/references/rust-core.md
new file mode 100644
index 0000000000..d1268ecd6b
--- /dev/null
+++ b/.claude/skills/opsml-rust-python/references/rust-core.md
@@ -0,0 +1,101 @@
+# Rust Core Practices
+
+OpsML's Python API is only as good as the Rust core underneath it. Design Rust code first as a clean, testable library; then expose the right boundary to Python.
+
+## API Shape
+
+Prefer APIs that make invalid states difficult to represent:
+- Use domain types instead of raw strings or loose maps for durable concepts.
+- Use enums for closed sets of states, backends, card kinds, operations, and variants.
+- Use structs with named fields for meaningful records.
+- Use traits for behavior shared across real implementations, not for one call site.
+- Keep public functions explicit about inputs, outputs, and error behavior.
+
+Do not shape core Rust APIs around what is easiest to extract from `PyAny`. Convert Python inputs at the boundary, then call Rust-native functions.
+
+## Zero-Cost Abstractions
+
+Prefer abstractions that compile down to direct code:
+- Generic functions with trait bounds when the caller can be monomorphized.
+- Enum dispatch for known backend variants, matching existing `StorageClientEnum` and `SqlClientEnum` patterns.
+- Iterators instead of building intermediate vectors.
+- Borrowed data such as `&str`, `&Path`, and `&[T]` when ownership is not needed.
+- `Cow<'_, str>` only when both borrowed and owned paths are real and the complexity pays for itself.
+
+Use `Box<dyn Trait>` only when runtime extensibility is required and the allocation/dynamic dispatch is an intentional tradeoff.
+
+## Ownership And Cloning
+
+Treat `.clone()` as a question, not a reflex:
+- Prefer borrowing when the callee does not need ownership.
+- Prefer moving values when the current scope no longer needs them.
+- Use `Arc<T>` for real shared ownership across tasks, state, or handlers.
+- Avoid `Arc<Mutex<T>>` as a default; first ask whether ownership, message passing, a narrower lock, or immutable state is enough.
+- Do not derive `Clone` speculatively. Derive it only when concrete call sites need it.
+
+Common acceptable clones:
+- Small identifiers or config values at API boundaries where ownership is clearer than lifetimes.
+- `Arc::clone` for shared application state.
+- Data copied into an owned response type.
+
+Common suspicious clones:
+- Large vectors, maps, schemas, payloads, or serialized values in loops.
+- Cloning to work around a borrow caused by overly broad scopes.
+- Cloning Python objects or PyO3 wrappers without a clear GIL/boundary reason.
+
+## Allocation And Strings
+
+Avoid accidental allocation in hot or repeated paths:
+- Use `String::with_capacity` when building a known-size string.
+- Use `Vec::with_capacity` when the item count is known or cheaply estimated.
+- Use `write!` into an existing `String` instead of repeated `format!` in loops.
+- Avoid serializing/deserializing just to move data between Rust layers.
+- Keep JSON conversion at API, storage, or Python boundaries unless the core domain truly stores JSON.
+
+Do not micro-optimize code that is not on a meaningful path. Prefer clear algorithms first, then optimize measured bottlenecks.
+
+## Traits
+
+Use traits when they express a stable capability:
+- Storage behavior.
+- SQL/card persistence behavior.
+- Card lifecycle behavior.
+- Interface behavior with multiple implementations.
+
+Keep traits small enough to implement correctly. Avoid kitchen-sink traits that force unrelated implementations to carry meaningless methods.
+
+Prefer associated types or generics when they simplify call sites. Avoid clever trait machinery when an enum, function, or concrete type would be easier to read and test.
+
+## Async And Shared State
+
+Use async for I/O boundaries: HTTP, database, storage, network calls, and server handlers. Keep pure computation synchronous unless the caller requires async.
+
+For shared server state:
+- Put heavy shared dependencies in `AppState`.
+- Wrap shared backend clients in `Arc` as established by the repo.
+- Avoid cloning heavy clients or rebuilding pools per request.
+- Keep locks out of request hot paths where possible.
+
+Use timeouts, cancellation-aware APIs, and bounded concurrency for external calls when the surrounding code already supports those patterns.
+
+## Error Design
+
+Rust errors should be precise and useful before they become Python exceptions:
+- Use `thiserror` enums for domain errors.
+- Include the failing operation and field/resource where possible.
+- Preserve source errors with `#[from]` only when the wrapped error is safe for Rust-only code.
+- Avoid `anyhow` in library surfaces unless the crate already uses it for an internal boundary.
+
+For errors crossing Python, follow `references/errors.md`.
+
+## Testing Rust Core
+
+New core logic should have Rust tests that do not require Python unless the behavior is inherently Python-facing.
+
+Good Rust tests:
+- Exercise domain behavior through public or crate-visible APIs.
+- Cover success, edge cases, and stable failures.
+- Use local fixtures and mocks instead of external services.
+- Keep SQLite/server tests isolated with `--test-threads=1` where the repo requires it.
+
+If a test requires Python for non-Python behavior, inspect the design for leaked PyO3 types or a misplaced boundary.
diff --git a/.claude/skills/opsml-rust-python/references/testing-workflows.md b/.claude/skills/opsml-rust-python/references/testing-workflows.md
new file mode 100644
index 0000000000..38ab3716a1
--- /dev/null
+++ b/.claude/skills/opsml-rust-python/references/testing-workflows.md
@@ -0,0 +1,64 @@
+# Testing And Workflow Commands
+
+Use `mise` as the default command surface. The tasks encode environment variables, working directories, feature flags, and server setup.
+
+## Default Commands
+
+Rust:
+- Format: `mise run format`
+- Lint: `mise run lints`
+- Full Rust aggregate when justified: `mise run test:unit`
+- Targeted crate tests: `cargo test -p <crate> <test_or_module> -- --nocapture --test-threads=1`
+
+Python:
+- Build stubs and extension: `mise run py:setup`
+- Format: `mise run py:format`
+- Lint/type checks: `mise run py:lints`
+- CI lint gate: `mise run py:lints-ci`
+- Unit tests: `mise run py:test:unit`
+- Service tests: `mise run py:test:service`
+- Integration tests: `mise run py:test:integration`
+
+Frontend work belongs to `opsml-ui`, not this skill.
+
+## Command Selection
+
+Use targeted tests first:
+- Changed a single Rust crate: run that crate's focused tests.
+- Changed SQL behavior: use the relevant `test:sql-*` task.
+- Changed server handlers: use targeted `opsml-server` tests with `--test-threads=1`.
+- Changed PyO3-exposed API: run `mise run py:setup`, then targeted Python tests or `mise run py:test:unit`.
+- Changed Python-only public API: run targeted pytest, then `mise run py:lints` if practical.
+
+Broaden to aggregate tasks when the change crosses boundaries or before final handoff on high-risk work.
+
+## Server Test Caution
+
+Do not run all `opsml_server` tests casually. The repo guidance warns that broad failures can leave stale state. Prefer isolated tests and cleanup. Use `TestHelper::new(None)` patterns and `helper.cleanup()` where applicable.
+
+Canonical Rust server tests:
+- Use `TestHelper::new(None)`.
+- Send requests through `helper.send_oneshot(request)` so auth headers are added.
+- Use `retry_flaky_test!` for transient SQLite contention.
+- Run with `--test-threads=1`.
+- Mock Scouter and SSO; do not require live external services.
+
+## PyO3 Change Checklist
+
+After changing a Python-exposed Rust type:
+1. Confirm Rust core behavior is tested without Python where possible.
+2. Confirm PyO3 registration is complete.
+3. Run `mise run py:setup`.
+4. Confirm imports work from `opsml`, not only from `_opsml`.
+5. Add or update Python tests for the user workflow.
+6. Run targeted Python tests or `mise run py:test:unit`.
+
+## Test Philosophy
+
+Tests should prove user journeys and stable contracts:
+- Card creation, serialization, registration, retrieval, and loading.
+- Local and server-backed registry behavior where both apply.
+- Structured error behavior for invalid inputs.
+- Python-visible behavior from the public `opsml` package.
+
+Avoid tests that mirror private implementation details. Add regression tests when fixing a bug.
diff --git a/.claude/skills/opsml-ts-svelte/SKILL.md b/.claude/skills/opsml-ts-svelte/SKILL.md
deleted file mode 100644
index b0ac0dba81..0000000000
--- a/.claude/skills/opsml-ts-svelte/SKILL.md
+++ /dev/null
@@ -1,881 +0,0 @@
----
-name: opsml-ts-svelte
-description: Use this skill whenever a user asks about TypeScript logic, Svelte 5 components, SvelteKit routing or data loading, state management, reactivity, API integration, type definitions, performance optimization, or any frontend logic in the OpsML project. Triggers include: writing or fixing TypeScript, Svelte runes ($state, $derived, $effect, $props), load functions, form actions, server endpoints, stores, utility functions, type safety, generics, async patterns, error handling, data fetching, filtering, sorting, pagination, or any mention of "how do I implement", "how should this work", "write a function", "fix the logic", or "why is this slow".
----
-
-You are an expert frontend engineer specializing in **TypeScript, Svelte 5, SvelteKit, and
-Tailwind CSS v4** for the OpsML platform — a developer-facing ML registry and observability
-system. You write strict, idiomatic, highly performant code that is easy to maintain and extend.
-
----
-
-## TypeScript Standards
-
-### Compiler Settings (assume strict mode)
-
-```jsonc
-// tsconfig.json (effective flags)
-{
-  "strict": true,           // enables all strict checks
-  "noUncheckedIndexedAccess": true,
-  "exactOptionalPropertyTypes": true,
-  "noImplicitOverride": true
-}
-```
-
-All code must compile cleanly under these flags. Never use `any` — use `unknown` and narrow
-instead. Never suppress errors with `// @ts-ignore` without an explanatory comment.
-
-### Type Definitions
-
-**Define types close to where they are used. Co-locate with the module, not in a global barrel
-unless shared across 3+ features.**
-
-```typescript
-// ✅ Precise, composable types
-type Status = 'active' | 'failed' | 'pending' | 'archived';
-
-interface RunSummary {
-  uid: string;
-  name: string;
-  version: string;
-  status: Status;
-  createdAt: string;  // ISO-8601; parse to Date at boundary, store as string
-  tags: Record<string, string>;
-}
-
-// ✅ Discriminated unions for API responses
-type ApiResult<T> =
-  | { ok: true; data: T }
-  | { ok: false; error: string; code: number };
-
-// ✅ Branded types for domain IDs (prevent ID confusion)
-type Uid = string & { readonly __brand: 'Uid' };
-type SpaceName = string & { readonly __brand: 'SpaceName' };
-
-function toUid(raw: string): Uid { return raw as Uid; }
-```
-
-### Generics
-
-Use generics to avoid duplication, not to add abstraction for its own sake.
-
-```typescript
-// ✅ Generic paginated response
-interface Page<T> {
-  items: T[];
-  total: number;
-  page: number;
-  pageSize: number;
-}
-
-// ✅ Generic sort utility
-function sortBy<T>(items: T[], key: keyof T, dir: 'asc' | 'desc' = 'asc'): T[] {
-  return [...items].sort((a, b) => {
-    const av = a[key];
-    const bv = b[key];
-    const cmp = av < bv ? -1 : av > bv ? 1 : 0;
-    return dir === 'asc' ? cmp : -cmp;
-  });
-}
-
-// ✅ Generic filter with type predicate
-function filterDefined<T>(items: (T | null | undefined)[]): T[] {
-  return items.filter((x): x is T => x != null);
-}
-```
-
-### Null Safety & Narrowing
-
-```typescript
-// ✅ Narrow unknown API responses at the boundary
-function parseRun(raw: unknown): RunSummary {
-  if (!raw || typeof raw !== 'object') throw new Error('Invalid run payload');
-  const r = raw as Record<string, unknown>;
-  if (typeof r['uid'] !== 'string') throw new Error('Missing uid');
-  // ...validate each field
-  return r as RunSummary;
-}
-
-// ✅ Optional chaining + nullish coalescing
-const label = run?.tags?.['display_name'] ?? run.name;
-
-// ✅ Exhaustive switch (TS will error if a variant is unhandled)
-function statusColor(s: Status): string {
-  switch (s) {
-    case 'active':   return 'bg-secondary-300';
-    case 'failed':   return 'bg-error-600';
-    case 'pending':  return 'bg-warning-300';
-    case 'archived': return 'bg-surface-300';
-  }
-}
-```
-
-### Async Patterns
-
-```typescript
-// ✅ Result pattern — never throw across async boundaries silently
-async function fetchRun(uid: string): Promise<ApiResult<RunSummary>> {
-  try {
-    const res = await fetch(`/api/runs/${uid}`);
-    if (!res.ok) return { ok: false, error: res.statusText, code: res.status };
-    const data: unknown = await res.json();
-    return { ok: true, data: parseRun(data) };
-  } catch (e) {
-    return { ok: false, error: String(e), code: 0 };
-  }
-}
-
-// ✅ Parallel fetches — use Promise.all, not sequential await
-const [runs, metrics] = await Promise.all([
-  fetchRuns(spaceId),
-  fetchMetrics(spaceId),
-]);
-
-// ✅ Abort controller for cancellable fetches
-function createFetch(url: string, signal: AbortSignal) {
-  return fetch(url, { signal });
-}
-```
-
----
-
-## Svelte 5 Runes — Complete Reference
-
-### $state
-
-```svelte
-<script lang="ts">
-  // Primitive state
-  let count = $state(0);
-  let isOpen = $state(false);
-  let query = $state('');
-
-  // Typed state — infer where possible, annotate when needed
-  let selected = $state<RunSummary | null>(null);
-  let items = $state<RunSummary[]>([]);
-
-  // Object state — mutations on nested properties ARE reactive
-  let filter = $state({ status: 'active' as Status, page: 1 });
-  // filter.status = 'failed';  ← reactive ✅
-
-  // Array state — use array methods directly
-  function addItem(item: RunSummary) {
-    items.push(item);  // reactive ✅
-  }
-  function removeItem(uid: string) {
-    const idx = items.findIndex(i => i.uid === uid);
-    if (idx !== -1) items.splice(idx, 1);  // reactive ✅
-  }
-</script>
-```
-
-### $derived
-
-```svelte
-<script lang="ts">
-  let items = $state<RunSummary[]>([]);
-  let query = $state('');
-  let sortKey = $state<keyof RunSummary>('createdAt');
-  let sortDir = $state<'asc' | 'desc'>('desc');
-
-  // ✅ Always wrap in arrow function; call as filtered() in template
-  const filtered = $derived(() =>
-    items
-      .filter(r => r.name.toLowerCase().includes(query.toLowerCase()))
-      .sort((a, b) => {
-        const cmp = a[sortKey] < b[sortKey] ? -1 : a[sortKey] > b[sortKey] ? 1 : 0;
-        return sortDir === 'asc' ? cmp : -cmp;
-      })
-  );
-
-  // ✅ Cheap derived — status counts for header badges
-  const counts = $derived(() => ({
-    active:   items.filter(r => r.status === 'active').length,
-    failed:   items.filter(r => r.status === 'failed').length,
-    total:    items.length,
-  }));
-</script>
-
-<!-- template: always call as a function -->
-{#each filtered() as run}...{/each}
-<span>{counts().failed} failed</span>
-```
-
-**Rules:**
-- `$derived` re-runs only when its tracked dependencies change — keep derivations pure and cheap
-- Do NOT write side effects inside `$derived`; use `$effect` for that
-- Memoization is automatic; no need for manual `useMemo` equivalents
-
-### $effect
-
-```svelte
-<script lang="ts">
-  let query = $state('');
-  let results = $state<RunSummary[]>([]);
-  let loading = $state(false);
-
-  // ✅ Fetch on query change — cleanup via returned function
-  $effect(() => {
-    const controller = new AbortController();
-    loading = true;
-
-    fetch(`/api/runs?q=${encodeURIComponent(query)}`, { signal: controller.signal })
-      .then(r => r.json())
-      .then(data => { results = data; loading = false; })
-      .catch(err => { if (err.name !== 'AbortError') loading = false; });
-
-    return () => controller.abort();  // cleanup on re-run or unmount
-  });
-
-  // ✅ Sync to URL param — side effect, not derived logic
-  $effect(() => {
-    const url = new URL(window.location.href);
-    url.searchParams.set('q', query);
-    history.replaceState({}, '', url);
-  });
-
-  // ✅ DOM interaction after mount
-  $effect(() => {
-    if (selected) {
-      document.getElementById(`row-${selected.uid}`)?.scrollIntoView({ block: 'nearest' });
-    }
-  });
-</script>
-```
-
-**Rules:**
-- `$effect` runs after the DOM updates, like `useEffect` in React
-- Always return a cleanup function when managing subscriptions, timers, or fetch controllers
-- Never write to state that the same effect reads — causes infinite loops
-- Prefer `$derived` for computed values; use `$effect` only for actual side effects
-
-### $props
-
-```svelte
-<script lang="ts">
-  // ✅ Destructure with inline type annotation
-  let {
-    run,
-    selected = false,
-    onSelect,
-    onDelete,
-  }: {
-    run: RunSummary;
-    selected?: boolean;
-    onSelect: (uid: string) => void;
-    onDelete?: (uid: string) => void;
-  } = $props();
-
-  // ✅ Rest props for spread forwarding
-  let { class: className = '', ...rest }: { class?: string; [key: string]: unknown } = $props();
-</script>
-```
-
-### $bindable
-
-```svelte
-<!-- ✅ Two-way bindable prop (prefer for form inputs, not complex state) -->
-<script lang="ts">
-  let { value = $bindable('') }: { value?: string } = $props();
-</script>
-<input bind:value />
-```
-
----
-
-## SvelteKit Data Loading
-
-### +page.server.ts — Server Load Functions
-
-```typescript
-// src/routes/runs/[uid]/+page.server.ts
-import type { PageServerLoad } from './$types';
-import { error } from '@sveltejs/kit';
-import { fetchRun } from '$lib/api/runs';
-
-export const load: PageServerLoad = async ({ params, fetch, locals }) => {
-  const result = await fetchRun(params.uid, fetch);
-
-  if (!result.ok) {
-    throw error(result.code || 500, result.error);
-  }
-
-  return {
-    run: result.data,
-    // Return only serializable data — no class instances, no functions
-  };
-};
-```
-
-### +page.ts — Universal Load (runs on server + client)
-
-```typescript
-// src/routes/runs/+page.ts
-import type { PageLoad } from './$types';
-
-export const load: PageLoad = async ({ url, fetch }) => {
-  const q = url.searchParams.get('q') ?? '';
-  const page = Number(url.searchParams.get('page') ?? '1');
-
-  const res = await fetch(`/api/runs?q=${encodeURIComponent(q)}&page=${page}`);
-  if (!res.ok) throw new Error(`Failed to load runs: ${res.status}`);
-
-  const data: Page<RunSummary> = await res.json();
-  return { runs: data, q, page };
-};
-```
-
-### Form Actions
-
-```typescript
-// src/routes/runs/[uid]/+page.server.ts
-import type { Actions } from './$types';
-import { fail, redirect } from '@sveltejs/kit';
-
-export const actions: Actions = {
-  deleteRun: async ({ params, fetch }) => {
-    const res = await fetch(`/api/runs/${params.uid}`, { method: 'DELETE' });
-    if (!res.ok) return fail(res.status, { message: 'Delete failed' });
-    throw redirect(303, '/runs');
-  },
-
-  updateTags: async ({ params, request, fetch }) => {
-    const form = await request.formData();
-    const tags = Object.fromEntries(
-      [...form.entries()].filter(([k]) => k.startsWith('tag_'))
-        .map(([k, v]) => [k.slice(4), String(v)])
-    );
-
-    const res = await fetch(`/api/runs/${params.uid}/tags`, {
-      method: 'PATCH',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ tags }),
-    });
-
-    if (!res.ok) return fail(res.status, { message: 'Update failed' });
-    return { success: true };
-  },
-};
-```
-
-### API Route Handlers (+server.ts)
-
-```typescript
-// src/routes/api/runs/+server.ts
-import type { RequestHandler } from './$types';
-import { json, error } from '@sveltejs/kit';
-
-export const GET: RequestHandler = async ({ url, locals }) => {
-  const q = url.searchParams.get('q') ?? '';
-  const page = Math.max(1, Number(url.searchParams.get('page') ?? '1'));
-  const pageSize = 25;
-
-  try {
-    const runs = await locals.db.runs.search({ q, page, pageSize });
-    return json(runs);
-  } catch (e) {
-    throw error(500, 'Database error');
-  }
-};
-
-export const POST: RequestHandler = async ({ request, locals }) => {
-  const body: unknown = await request.json();
-  // validate...
-  const run = await locals.db.runs.create(body);
-  return json(run, { status: 201 });
-};
-```
-
----
-
-## State Architecture
-
-### When to Use What
-
-| Pattern | Use When |
-|---|---|
-| `$state` in component | Local UI state — open/closed, selection, form values |
-| `$state` in `.svelte.ts` module | Shared state across sibling components without prop drilling |
-| SvelteKit `load` return | Server-fetched data that belongs to a route |
-| URL search params | Filterable / shareable state (search query, page, sort) |
-| Form actions | Mutations — creates, updates, deletes |
-| Context API (`setContext`/`getContext`) | Deep component trees; avoid prop drilling for config/services |
-
-### Shared Reactive State (`.svelte.ts` module)
-
-```typescript
-// src/lib/state/selection.svelte.ts
-// ✅ Use for cross-component shared state (replaces writable stores)
-
-let _selected = $state<string | null>(null);
-let _multiSelected = $state<Set<string>>(new Set());
-
-export const selection = {
-  get current() { return _selected; },
-  get multi() { return _multiSelected; },
-  select(uid: string) { _selected = uid; },
-  toggle(uid: string) {
-    if (_multiSelected.has(uid)) _multiSelected.delete(uid);
-    else _multiSelected.add(uid);
-  },
-  clear() { _selected = null; _multiSelected.clear(); },
-};
-```
-
-Usage in any component:
-```svelte
-<script lang="ts">
-  import { selection } from '$lib/state/selection.svelte';
-</script>
-
-<tr
-  class={selection.current === run.uid ? 'bg-primary-100' : ''}
-  onclick={() => selection.select(run.uid)}
->
-```
-
----
-
-## Performance Patterns
-
-### Debouncing Search / Filter Input
-
-```typescript
-// src/lib/utils/debounce.ts
-export function debounce<T extends (...args: never[]) => void>(
-  fn: T,
-  delay: number
-): (...args: Parameters<T>) => void {
-  let timer: ReturnType<typeof setTimeout>;
-  return (...args) => {
-    clearTimeout(timer);
-    timer = setTimeout(() => fn(...args), delay);
-  };
-}
-```
-
-```svelte
-<script lang="ts">
-  import { debounce } from '$lib/utils/debounce';
-
-  let query = $state('');
-  let debouncedQuery = $state('');
-
-  const updateQuery = debounce((q: string) => { debouncedQuery = q; }, 300);
-
-  $effect(() => updateQuery(query));
-</script>
-
-<input bind:value={query} placeholder="Search..." />
-<!-- use debouncedQuery for actual filtering/fetching -->
-```
-
-### Virtual / Windowed Lists
-
-For tables with 500+ rows, avoid rendering all at once:
-
-```svelte
-<script lang="ts">
-  let items = $state<RunSummary[]>([]);
-  let visibleStart = $state(0);
-  const ROW_HEIGHT = 40; // px
-  const VISIBLE_COUNT = 25;
-
-  const visible = $derived(() =>
-    items.slice(visibleStart, visibleStart + VISIBLE_COUNT)
-  );
-
-  function onScroll(e: UIEvent) {
-    const scrollTop = (e.target as HTMLElement).scrollTop;
-    visibleStart = Math.floor(scrollTop / ROW_HEIGHT);
-  }
-</script>
-
-<div
-  class="overflow-y-auto"
-  style="height: {VISIBLE_COUNT * ROW_HEIGHT}px"
-  onscroll={onScroll}
->
-  <div style="height: {items.length * ROW_HEIGHT}px; position: relative;">
-    <div style="position: absolute; top: {visibleStart * ROW_HEIGHT}px; width: 100%;">
-      {#each visible() as run (run.uid)}
-        <RunRow {run} />
-      {/each}
-    </div>
-  </div>
-</div>
-```
-
-### Keyed Each Blocks
-
-Always key `{#each}` blocks on a stable, unique ID to prevent unnecessary DOM reconciliation:
-
-```svelte
-<!-- ✅ Keyed -->
-{#each runs as run (run.uid)}
-  <RunRow {run} />
-{/each}
-
-<!-- ❌ Un-keyed — full re-render on reorder -->
-{#each runs as run}
-  <RunRow {run} />
-{/each}
-```
-
-### Lazy / Async Components
-
-```svelte
-<script lang="ts">
-  // ✅ Import heavy component lazily — only downloaded when needed
-  const TraceWaterfall = import('$lib/components/trace/TraceWaterfall.svelte');
-</script>
-
-{#await TraceWaterfall}
-  <div class="h-64 border-2 border-black rounded-base bg-surface-200 animate-pulse" />
-{:then { default: TraceWaterfall }}
-  <TraceWaterfall {spans} />
-{/await}
-```
-
-### Avoiding $effect Over-runs
-
-```svelte
-<!-- ❌ Reads items inside effect — re-runs every time items changes -->
-$effect(() => {
-  doSomethingWith(items);
-  doSomethingElseWith(items);
-});
-
-<!-- ✅ Derive the value first; effect only reads the derived snapshot -->
-const snapshot = $derived(() => items.map(i => i.uid).join(','));
-$effect(() => {
-  const uids = snapshot();
-  doSomethingWith(uids);
-});
-```
-
----
-
-## API Layer Patterns
-
-### Typed Fetch Wrapper
-
-```typescript
-// src/lib/api/client.ts
-const BASE = '/api';
-
-async function apiFetch<T>(
-  path: string,
-  options?: RequestInit
-): Promise<ApiResult<T>> {
-  try {
-    const res = await fetch(`${BASE}${path}`, {
-      headers: { 'Content-Type': 'application/json' },
-      ...options,
-    });
-
-    if (!res.ok) {
-      const msg = await res.text().catch(() => res.statusText);
-      return { ok: false, error: msg, code: res.status };
-    }
-
-    const data: T = await res.json();
-    return { ok: true, data };
-  } catch (e) {
-    return { ok: false, error: String(e), code: 0 };
-  }
-}
-
-export const api = {
-  get:    <T>(path: string) => apiFetch<T>(path),
-  post:   <T>(path: string, body: unknown) =>
-            apiFetch<T>(path, { method: 'POST', body: JSON.stringify(body) }),
-  patch:  <T>(path: string, body: unknown) =>
-            apiFetch<T>(path, { method: 'PATCH', body: JSON.stringify(body) }),
-  delete: <T>(path: string) => apiFetch<T>(path, { method: 'DELETE' }),
-};
-```
-
-### Module-Level API Functions
-
-```typescript
-// src/lib/api/runs.ts
-import { api } from './client';
-import type { Page, RunSummary, RunDetail } from '$lib/types';
-
-export async function listRuns(params: {
-  space?: string;
-  q?: string;
-  page?: number;
-  status?: Status;
-}): Promise<ApiResult<Page<RunSummary>>> {
-  const query = new URLSearchParams();
-  if (params.space)  query.set('space', params.space);
-  if (params.q)      query.set('q', params.q);
-  if (params.page)   query.set('page', String(params.page));
-  if (params.status) query.set('status', params.status);
-
-  return api.get<Page<RunSummary>>(`/runs?${query}`);
-}
-
-export async function getRun(uid: string): Promise<ApiResult<RunDetail>> {
-  return api.get<RunDetail>(`/runs/${uid}`);
-}
-
-export async function deleteRun(uid: string): Promise<ApiResult<void>> {
-  return api.delete<void>(`/runs/${uid}`);
-}
-```
-
----
-
-## Utility Functions
-
-### Date Formatting
-
-```typescript
-// src/lib/utils/format.ts
-
-const relativeFormatter = new Intl.RelativeTimeFormat('en', { numeric: 'auto' });
-const dateFormatter = new Intl.DateTimeFormat('en-US', {
-  month: 'short', day: 'numeric', year: 'numeric',
-  hour: '2-digit', minute: '2-digit',
-});
-
-export function formatRelative(iso: string): string {
-  const diff = (new Date(iso).getTime() - Date.now()) / 1000;
-  if (Math.abs(diff) < 60)    return relativeFormatter.format(Math.round(diff), 'second');
-  if (Math.abs(diff) < 3600)  return relativeFormatter.format(Math.round(diff / 60), 'minute');
-  if (Math.abs(diff) < 86400) return relativeFormatter.format(Math.round(diff / 3600), 'hour');
-  return relativeFormatter.format(Math.round(diff / 86400), 'day');
-}
-
-export function formatDate(iso: string): string {
-  return dateFormatter.format(new Date(iso));
-}
-```
-
-### Duration / Metrics Formatting
-
-```typescript
-export function formatDuration(ms: number): string {
-  if (ms < 1)      return `${(ms * 1000).toFixed(0)}µs`;
-  if (ms < 1000)   return `${ms.toFixed(1)}ms`;
-  if (ms < 60_000) return `${(ms / 1000).toFixed(2)}s`;
-  return `${(ms / 60_000).toFixed(1)}m`;
-}
-
-export function formatNumber(n: number, decimals = 2): string {
-  return new Intl.NumberFormat('en-US', {
-    maximumFractionDigits: decimals,
-    minimumFractionDigits: decimals,
-  }).format(n);
-}
-
-export function formatBytes(bytes: number): string {
-  const units = ['B', 'KB', 'MB', 'GB', 'TB'];
-  let i = 0;
-  let v = bytes;
-  while (v >= 1024 && i < units.length - 1) { v /= 1024; i++; }
-  return `${v.toFixed(i === 0 ? 0 : 1)} ${units[i]}`;
-}
-```
-
-### URL / Search Param Helpers
-
-```typescript
-// src/lib/utils/url.ts
-import { goto } from '$app/navigation';
-import { page } from '$app/stores';
-import { get } from 'svelte/store';
-
-export function updateSearchParam(key: string, value: string | null): void {
-  const url = new URL(get(page).url);
-  if (value === null || value === '') url.searchParams.delete(key);
-  else url.searchParams.set(key, value);
-  goto(url, { keepFocus: true, noScroll: true, replaceState: true });
-}
-
-export function getSearchParam(key: string, fallback: string = ''): string {
-  return get(page).url.searchParams.get(key) ?? fallback;
-}
-```
-
----
-
-## Tailwind CSS v4 Patterns
-
-### Dynamic Class Composition
-
-```typescript
-// ✅ Use a helper to compose conditional classes — avoids string interpolation issues
-export function cx(...classes: (string | false | null | undefined)[]): string {
-  return classes.filter(Boolean).join(' ');
-}
-```
-
-```svelte
-<div class={cx(
-  'rounded-base border-2 border-black p-4',
-  selected && 'bg-primary-100 shadow-primary-small',
-  !selected && 'bg-surface-50 shadow-small',
-  error && 'border-error-600'
-)}>
-```
-
-### Theme-Driven Color Mapping
-
-```typescript
-// ✅ Map domain values to theme classes in TypeScript, not inline
-const STATUS_STYLES: Record<Status, { bg: string; text: string; badge: string }> = {
-  active:   { bg: 'bg-secondary-100', text: 'text-secondary-900', badge: 'bg-secondary-300' },
-  failed:   { bg: 'bg-error-100',     text: 'text-error-900',     badge: 'bg-error-600'     },
-  pending:  { bg: 'bg-warning-100',   text: 'text-warning-900',   badge: 'bg-warning-300'   },
-  archived: { bg: 'bg-surface-200',   text: 'text-black/60',      badge: 'bg-surface-400'   },
-};
-
-// Usage in template
-const styles = $derived(() => STATUS_STYLES[run.status]);
-```
-
-```svelte
-<span class={`badge border border-black shadow-small text-xs font-black ${styles().badge}`}>
-  {run.status.toUpperCase()}
-</span>
-```
-
-**Rule:** Never construct partial Tailwind class names dynamically (e.g., `` `bg-${color}-500` ``).
-Tailwind's scanner cannot detect them. Always use complete class strings or map from a lookup
-object.
-
----
-
-## Error Handling Patterns
-
-### Component-Level Error Boundary
-
-```svelte
-<!-- +error.svelte -->
-<script lang="ts">
-  import { page } from '$app/stores';
-</script>
-
-<div class="flex flex-col items-center justify-center py-24 px-8 text-center">
-  <div class="rounded-base border-2 border-black shadow bg-error-100 p-6 max-w-md w-full">
-    <p class="text-xss font-black uppercase tracking-wider text-error-900 mb-2">
-      Error {$page.status}
-    </p>
-    <h1 class="text-2xl font-black text-error-900 mb-3">{$page.error?.message ?? 'Something went wrong'}</h1>
-    <a href="/" class="btn bg-error-600 text-white border-2 border-black shadow-small shadow-click-small rounded-base font-bold uppercase">
-      Go Home
-    </a>
-  </div>
-</div>
-```
-
-### Inline Async Error Handling in Components
-
-```svelte
-<script lang="ts">
-  let result = $state<ApiResult<RunDetail> | null>(null);
-  let loading = $state(false);
-
-  async function load(uid: string) {
-    loading = true;
-    result = await getRun(uid);
-    loading = false;
-  }
-</script>
-
-{#if loading}
-  <div class="h-32 bg-surface-200 rounded-base border-2 border-black animate-pulse" />
-{:else if result?.ok === false}
-  <div class="warn-color rounded-base border-2 border-black p-4 text-sm font-bold">
-    {result.error}
-  </div>
-{:else if result?.ok}
-  <RunDetail run={result.data} />
-{/if}
-```
-
----
-
-## Code Style Rules
-
-### Naming
-
-| Thing | Convention | Example |
-|---|---|---|
-| Components | PascalCase | `RunTable.svelte` |
-| Functions | camelCase | `fetchRuns`, `formatDate` |
-| Types / Interfaces | PascalCase | `RunSummary`, `ApiResult<T>` |
-| Constants | UPPER_SNAKE | `MAX_PAGE_SIZE`, `DEFAULT_SORT` |
-| State modules | camelCase + `.svelte.ts` | `selection.svelte.ts` |
-| Route params | kebab-case | `[run-uid]` |
-| Utility files | kebab-case | `format.ts`, `debounce.ts` |
-
-### Import Order
-
-```typescript
-// 1. SvelteKit / Svelte built-ins
-import { goto } from '$app/navigation';
-import { page } from '$app/stores';
-
-// 2. Third-party
-import { ExternalLink } from 'lucide-svelte';
-
-// 3. Internal — absolute ($lib/...)
-import { api } from '$lib/api/client';
-import type { RunSummary } from '$lib/types';
-
-// 4. Internal — relative
-import RunRow from './RunRow.svelte';
-```
-
-### File Structure
-
-```
-src/
-  lib/
-    api/          # typed fetch wrappers (client.ts, runs.ts, ...)
-    state/        # shared reactive state (*.svelte.ts)
-    utils/        # pure utilities (format.ts, debounce.ts, url.ts, cx.ts)
-    types/        # shared type definitions (index.ts)
-    components/
-      ui/          # generic reusable (Badge, Pill, Modal, ...)
-      runs/        # feature-specific (RunTable, RunRow, RunDetail, ...)
-      trace/       # trace-specific (TraceWaterfall, SpanRow, ...)
-  routes/
-    (app)/         # layout group with shared nav
-      runs/
-        +page.svelte
-        +page.server.ts
-        [uid]/
-          +page.svelte
-          +page.server.ts
-    api/           # API route handlers
-      runs/
-        +server.ts
-        [uid]/
-          +server.ts
-```
-
----
-
-## Anti-Patterns — Never Do These
-
-| Violation | Correct Alternative |
-|---|---|
-| `$:` reactive statements | `$derived(() => ...)` rune |
-| `writable()` / `readable()` stores | `$state` in `.svelte.ts` module |
-| `on:click=` event directive | `onclick=` attribute |
-| `any` type | `unknown` + type narrowing |
-| Arbitrary hex in `style=` | opsml-theme CSS variables via Tailwind |
-| Dynamic partial class names `` `bg-${x}-500` `` | Full class string lookup map |
-| Sequential `await` inside a single effect | `Promise.all` for parallel fetches |
-| Un-keyed `{#each}` on mutable lists | `{#each items as item (item.uid)}` |
-| Mutating props directly | Emit via callback prop; parent owns state |
-| `document.querySelector` in components | Bind element with `bind:this` |
-| `localStorage` for server-side-rendered routes | URL params or cookies via `locals` |
-| Throwing raw errors from load functions | `throw error(status, message)` from `@sveltejs/kit` |
diff --git a/.claude/skills/opsml-ui/SKILL.md b/.claude/skills/opsml-ui/SKILL.md
index fc7c30218c..56b3a9b176 100644
--- a/.claude/skills/opsml-ui/SKILL.md
+++ b/.claude/skills/opsml-ui/SKILL.md
@@ -31,6 +31,7 @@ Follow these repo-specific rules:
 - Prefer server-backed pagination, filtering, sorting, and aggregation for large remote datasets.
 - Use `VirtualScroller.svelte` or `@tanstack/svelte-virtual` for large scrollable views.
 - Do not add new UI libraries unless the user explicitly asks.
+- All functions, classes, methods, and components must have JSDoc comments. Use TSDoc tags like `@param`, `@returns`, `@throws`, and `@example` where relevant.
 
 When making changes, inspect in this order:
 1. The route entrypoint (`+page.svelte`, `+page.ts`, `+page.server.ts`, `+layout.*`)
diff --git a/.codex/skills/opsml-rust-python/SKILL.md b/.codex/skills/opsml-rust-python/SKILL.md
new file mode 100644
index 0000000000..7f6db89ba3
--- /dev/null
+++ b/.codex/skills/opsml-rust-python/SKILL.md
@@ -0,0 +1,49 @@
+---
+name: opsml-rust-python
+description: Repo-local OpsML skill for Rust core, Python bindings, PyO3, maturin, card/registry/server/client logic, Python API exports, generated stubs, and cross-language tests. Use when working in OpsML crates, `py-opsml`, PyO3-exposed types, Rust errors that cross Python, card or registry behavior, server/client contracts, or Python-visible SDK behavior. Do not use for Svelte UI work; use `opsml-ui` instead.
+---
+
+# OpsML Rust/Python
+
+Use this skill as the source of truth for OpsML work where Rust core logic is exposed to Python through PyO3. OpsML is not a generic Rust/Python package: cards are the central abstraction, Rust owns the business logic, and Python is a thin ergonomic API over the Rust core.
+
+Start by locating the layer you are changing:
+- Rust core design, traits, ownership, performance, cloning, async, or crate-local API shape: read `references/rust-core.md`.
+- Rust card, registry, storage, SQL, server, auth, events, or shared contracts: read `references/architecture.md`.
+- PyO3 classes, `#[pymethods]`, GIL usage, nested `#[pyclass]` fields, or Python lifetimes: read `references/pyo3-boundaries.md`.
+- Error types, `PyErr`, server envelopes, CLI errors, or Python exceptions: read `references/errors.md`.
+- Python exports, `__all__`, generated stubs, maturin setup, or Python-visible SDK behavior: read `references/python-api-and-stubs.md`.
+- Tests, linting, formatting, or command selection: read `references/testing-workflows.md`.
+- Agent-readable APIs, structured errors, validation, lint sensors, or harness work: read `references/agent-harness.md`.
+
+Follow these repo-specific rules:
+- Keep core behavior in Rust. Python should expose a typed, ergonomic API and small helpers, not duplicate card, registry, storage, or validation logic.
+- Design Rust APIs around domain-owned data, precise traits, and explicit ownership before thinking about the Python binding.
+- Keep Python lifetimes out of Rust-only code. Introduce `Python<'py>`, `Bound<'py, PyAny>`, `Py<PyAny>`, and `PyErr` only where code crosses the Python boundary.
+- Do not store `PyErr` in reusable Rust error enums. Convert Python errors into string-backed Rust variants, then convert Rust errors back into Python exceptions at the PyO3 boundary.
+- For `#[pyclass]` fields whose type is also `#[pyclass]`, do not use `#[pyo3(get, set)]`. Implement manual `#[getter]` and `#[setter]` methods with `IntoPyObjectExt` and `extract`.
+- Prefer zero-cost Rust abstractions: enums with delegated trait impls, static dispatch, concrete types, precise errors, iterators, references, ownership transfer, and `Arc` only where shared state is real.
+- Treat speculative `Clone`, broad abstractions, unnecessary allocation, and Python-driven core design as design smells. Add them only for concrete call sites.
+- Make new Rust core logic testable without Python whenever possible. Add Python tests for Python-visible workflows.
+- Write errors and API contracts so humans and coding agents can debug them: stable names, clear fields, concise messages, and actionable hints.
+- Use repository workflow tooling from `mise.toml`. Do not invent ad hoc commands when a `mise run ...` task exists.
+- Inspect current dependency versions in `Cargo.toml`, `py-opsml/pyproject.toml`, and lockfiles before relying on version-specific behavior.
+
+When making Rust/PyO3 changes, inspect in this order:
+1. The Rust crate that owns the domain behavior.
+2. Shared types in `opsml-types/src/contracts/` if the behavior crosses server/client/Python boundaries.
+3. PyO3 module registration under `py-opsml/src/`.
+4. Python package re-exports under `py-opsml/python/opsml/`.
+5. Generated stubs under `py-opsml/python/opsml/_opsml.pyi` and `py-opsml/python/opsml/stubs/`.
+6. Rust and Python tests that model the user journey.
+
+Use these verification commands when relevant:
+- Rust formatting: `mise run format`
+- Rust linting: `mise run lints`
+- Targeted Rust tests: `cargo test -p <crate> <test_name> -- --nocapture --test-threads=1`
+- Full Rust aggregate when justified: `mise run test:unit`
+- Rebuild Python bindings after PyO3-exposed Rust changes: `mise run py:setup`
+- Python linting: `mise run py:lints`
+- Python unit tests: `mise run py:test:unit`
+
+Prefer narrow, local edits that match existing OpsML patterns. Broaden the architecture only when the current domain boundary is truly wrong for the user workflow.
diff --git a/.codex/skills/opsml-rust-python/references/agent-harness.md b/.codex/skills/opsml-rust-python/references/agent-harness.md
new file mode 100644
index 0000000000..c42b2171dc
--- /dev/null
+++ b/.codex/skills/opsml-rust-python/references/agent-harness.md
@@ -0,0 +1,55 @@
+# Agent-Friendly OpsML Work
+
+OpsML is being shaped for both human developers and coding agents. The key direction is harness engineering: give agents strong guides before they act and strong sensors after they act.
+
+## Design For Agents And Humans
+
+Code should be readable by humans first and stable enough for agents to modify safely:
+- Keep names domain-specific and unambiguous.
+- Keep functions small enough that invariants are visible.
+- Prefer typed contracts over loose dictionaries or stringly-typed conventions.
+- Surface failures with stable codes, fields, hints, and docs where the repo supports them.
+- Keep side effects at clear boundaries.
+
+## Same Envelope Principle
+
+Harness work should converge on the same structured shape across layers:
+- HTTP responses.
+- PyO3 exceptions.
+- CLI output.
+- `card.validate()`.
+- `opsml lint`.
+- Integrity checks.
+- Eval results.
+
+Use fields such as:
+- `code`
+- `field`
+- `hint` or `suggested_action`
+- `doc_url`
+- `retry`
+
+Agents should not need to parse paragraphs to understand what field to fix.
+
+## Validation And Sensors
+
+When adding governance behavior, think in layers:
+- Edit-time or local lint sensors.
+- Rust-native validation on core types.
+- Registry/server chokepoints.
+- Post-hoc integrity checks.
+- Behavior evals for prompts and agents.
+
+The Rust core should own validations that define durable OpsML correctness. Python should expose them ergonomically and test them as user workflows.
+
+## Documentation Near APIs
+
+Public Rust and Python APIs should include useful docs when they define:
+- User-visible behavior.
+- Required invariants.
+- Error conditions.
+- Security constraints.
+- Serialization formats.
+- Cross-language boundary behavior.
+
+Do not add noisy comments that restate simple code. Add concise comments when they preserve hard-won context, such as why a Python lifetime is intentionally kept at the boundary.
diff --git a/.codex/skills/opsml-rust-python/references/architecture.md b/.codex/skills/opsml-rust-python/references/architecture.md
new file mode 100644
index 0000000000..0998b53ee7
--- /dev/null
+++ b/.codex/skills/opsml-rust-python/references/architecture.md
@@ -0,0 +1,73 @@
+# OpsML Rust/Python Architecture
+
+OpsML is an AI lifecycle platform organized around cards: versioned, encrypted, registry-tracked records for data, models, experiments, prompts, services, agents, and skills. Python users create and operate cards, but the durable behavior belongs in Rust.
+
+## Core Rule
+
+Rust is the source of truth for:
+- Card structure and validation.
+- Registry behavior.
+- Server contracts and route behavior.
+- Storage, SQL, encryption, auth, events, and versioning.
+- Serialization formats that persist or cross process boundaries.
+
+Python should provide:
+- Ergonomic constructors and usage patterns.
+- Thin re-exports from `_opsml`.
+- Small Python-only helpers where Python libraries are the natural boundary.
+- User-journey tests for public Python behavior.
+
+Do not implement durable business logic twice in Rust and Python. If Python and Rust disagree, the design is already drifting.
+
+## Important Crates
+
+- `opsml-cards`: PyO3 card structs and card-specific behavior.
+- `opsml-registry`: Python-facing `CardRegistry`; dispatches to local or server-backed operations.
+- `opsml-types`: shared contract types, enums, and request/response shapes.
+- `opsml-server`: Axum routes, middleware, API handlers, server errors.
+- `opsml-client`: Rust HTTP client used by Python bindings in server mode.
+- `opsml-sql`: database abstraction over SQLite, PostgreSQL, and MySQL.
+- `opsml-storage`: storage abstraction over local and cloud backends.
+- `opsml-crypt`: artifact encryption.
+- `opsml-experiment`, `opsml-genai`, `opsml-service`: domain-specific card logic.
+- `py-opsml`: Python package and PyO3 extension wiring.
+
+Read `AGENTS.md` for the full crate map before changing a cross-cutting path.
+
+## Enum-Based Backends
+
+OpsML favors enum dispatch for core backends:
+- `StorageClientEnum` delegates `StorageClient` methods to local/S3/GCS/Azure variants.
+- `SqlClientEnum` delegates SQL/card logic to SQLite/PostgreSQL/MySQL variants.
+
+When adding a backend or domain variant, follow this pattern before reaching for `Box<dyn Trait>`.
+
+## Contracts And Routes
+
+Shared request/response types belong in `opsml-types/src/contracts/`.
+
+Server routes live under `/opsml/api` and follow the existing handler shape:
+- `State<Arc<AppState>>` for dependencies.
+- `Extension<UserPermissions>` for protected routes, even read-only routes.
+- `Query(...)` or `Json(...)` for inputs.
+- `Result<Json<Response>, (StatusCode, Json<OpsmlServerError>)>` or an established local equivalent.
+
+Use `parse_qs_query::<T>(&uri)` for query strings containing `Vec<T>`.
+
+## Registry Modes
+
+`CardRegistry` supports:
+- Local mode: direct filesystem/SQLite-backed registry operations.
+- Server mode: HTTP proxy through `opsml-client`.
+
+New behavior should preserve both modes unless the feature is explicitly server-only. A change that only works through the Python package but not through Rust registry/server paths is usually in the wrong layer.
+
+## Artifact Encryption
+
+Card artifacts are encrypted before storage. Do not bypass:
+- `create_artifact_key()`
+- `create_and_store_encrypted_file()`
+- `download_artifact()` plus decryption
+- `ArtifactKey` as the database source of truth
+
+Security-sensitive changes need targeted tests around key lookup, upload/download paths, and error behavior.
diff --git a/.codex/skills/opsml-rust-python/references/errors.md b/.codex/skills/opsml-rust-python/references/errors.md
new file mode 100644
index 0000000000..ed1c7a8858
--- /dev/null
+++ b/.codex/skills/opsml-rust-python/references/errors.md
@@ -0,0 +1,84 @@
+# Errors Across Rust And Python
+
+OpsML errors should be clear enough for humans and structured enough for agents. They should name what failed, where possible include the affected field/resource, and preserve enough context to fix the issue without parsing vague prose.
+
+## No Stored `PyErr`
+
+Do not store `PyErr` inside reusable Rust error enums. `PyErr` can pull Python runtime/lifetime concerns into pure Rust code and cause C linker or GIL-related failures in Rust tests.
+
+Use the canonical pattern in `crates/opsml_cards/src/skill/error.rs`:
+- Rust error variants store Rust-owned data such as `String`.
+- `From<PyErr> for SkillError` converts to a string-backed variant.
+- `From<SkillError> for PyErr` exists only behind the Python feature and maps to a Python exception at the boundary.
+
+Preferred shape:
+
+```rust
+#[derive(thiserror::Error, Debug)]
+pub enum DomainError {
+    #[error("{0}")]
+    Error(String),
+
+    #[error(transparent)]
+    Io(#[from] std::io::Error),
+}
+
+#[cfg(feature = "python")]
+impl From<PyErr> for DomainError {
+    fn from(err: PyErr) -> Self {
+        DomainError::Error(err.to_string())
+    }
+}
+
+#[cfg(feature = "python")]
+impl From<DomainError> for PyErr {
+    fn from(err: DomainError) -> PyErr {
+        pyo3::exceptions::PyRuntimeError::new_err(err.to_string())
+    }
+}
+```
+
+Avoid this in core errors:
+
+```rust
+#[error(transparent)]
+Python(#[from] PyErr)
+```
+
+Only use direct Python error storage in code that is permanently Python-only and cannot be reached by Rust tests or Rust core logic. That should be rare in OpsML.
+
+## Transitive Error Chains
+
+The rule applies transitively. If `CardError` wraps `ModelInterfaceError`, and `ModelInterfaceError` stores `PyErr`, then `CardError` is contaminated too.
+
+When adding `#[from]` variants, inspect wrapped errors for PyO3 types. Prefer converting upstream errors to string-backed variants at the boundary.
+
+## Server Error Envelope
+
+Server handlers should use the existing `OpsmlServerError` helpers and structured fields where available. For new agent-facing or validation work, prefer stable data:
+- `code`
+- `field`
+- `suggested_action` or hint
+- `doc_url`
+- `retry`
+
+Prefer one stable error shape across HTTP, PyO3, CLI, lint output, validation, and eval. A Python caller, CLI user, UI route, and coding agent should be able to recognize the same failure without parsing unrelated prose.
+
+## Human And Agent Debuggability
+
+Error messages should:
+- Name the operation that failed.
+- Include the resource identifier when safe, such as card UID, space/name/version, file path, or field.
+- Avoid generic messages like "invalid input" when the failing field is known.
+- Avoid logging secrets, tokens, encryption keys, or provider credentials.
+- Keep wording concise and stable enough for tests and agents.
+
+## Mapping To Python Exceptions
+
+Choose Python exception types deliberately:
+- Invalid user input: `PyValueError`.
+- Missing key or field: `PyKeyError` or `PyValueError`, depending on existing local style.
+- Filesystem/IO: `PyOSError`.
+- Runtime integration failure: `PyRuntimeError`.
+
+Follow nearby mappings in the same crate before introducing a new exception style.
diff --git a/.codex/skills/opsml-rust-python/references/pyo3-boundaries.md b/.codex/skills/opsml-rust-python/references/pyo3-boundaries.md
new file mode 100644
index 0000000000..80a90b0705
--- /dev/null
+++ b/.codex/skills/opsml-rust-python/references/pyo3-boundaries.md
@@ -0,0 +1,89 @@
+# PyO3 Boundary Rules
+
+PyO3 code is a boundary layer. Keep Python lifetimes, `PyErr`, and object extraction at the edge so Rust core code remains testable with normal Rust tests.
+
+## Boundary Types
+
+Use these types only when the code is actually crossing into Python:
+- `Python<'py>`
+- `Bound<'py, PyAny>`
+- `Py<PyAny>`
+- `PyErr`
+- `#[pyclass]`, `#[pymethods]`, `#[pyfunction]`
+
+Pure Rust functions should generally accept and return Rust types, not Python-bound objects.
+
+## Constructors
+
+For Python constructors, keep extraction and conversion near `#[new]`, then call a Rust-native constructor such as `new_rs`, `from_config`, or a domain-specific builder.
+
+Preferred shape:
+
+```rust
+#[cfg(feature = "python")]
+#[pymethods]
+impl SkillCard {
+    #[new]
+    pub fn new(skill: &Bound<'_, PyAny>, space: Option<&str>) -> Result<Self, SkillError> {
+        let skill = skill.extract::<AgentSkillStandard>()?;
+        Self::new_rs(skill, space, None, None, None, None, None, None)
+    }
+}
+```
+
+Keep the Rust-native constructor usable without Python.
+
+## Nested `#[pyclass]` Fields
+
+If a `#[pyclass]` struct has a field whose type is itself a `#[pyclass]`, do not put `#[pyo3(get, set)]` on that field. PyO3-generated accessors can leak Python lifetimes into pure Rust call sites and tests.
+
+Use the canonical pattern in `crates/opsml_cards/src/skill/card.rs`:
+- `skill` field getter at `SkillCard::skill`.
+- `set_skill` setter using `extract`.
+- `dependencies` getter using `IntoPyObjectExt`.
+- `set_dependencies` setter using `extract::<Vec<SkillDependency>>()`.
+
+Preferred shape:
+
+```rust
+#[getter]
+pub fn skill<'py>(&self, py: Python<'py>) -> Result<Bound<'py, PyAny>, SkillError> {
+    Ok(self.skill.clone().into_bound_py_any(py)?)
+}
+
+#[setter]
+pub fn set_skill(&mut self, skill: &Bound<'_, PyAny>) -> Result<(), SkillError> {
+    self.skill = skill.extract::<AgentSkillStandard>()?;
+    Ok(())
+}
+```
+
+## Python Objects In Cards
+
+Some cards hold Python-owned objects, such as model or data interfaces. Keep GIL acquisition scoped tightly:
+- Acquire the GIL only where calling Python methods or extracting Python objects.
+- Convert Python-side data into Rust metadata before serialization.
+- Do not attempt to serialize `Py<PyAny>` directly.
+- Reconstruct Python-facing objects only at load/deserialization boundaries where the Python API needs them.
+
+## Feature Gates
+
+Respect existing `python` and `server` feature gates. If a Rust unit test fails with Python linking or libpython errors, inspect for leaked PyO3 types in core code or transitive error chains.
+
+Common causes:
+- `PyErr` stored in a reusable error enum.
+- `#[pyo3(get, set)]` on nested `#[pyclass]` fields.
+- Python-only imports not guarded with `#[cfg(feature = "python")]`.
+
+## Module Registration
+
+New Python-visible Rust functions/classes must be wired through `py-opsml/src/lib.rs` and the appropriate submodule registration function, such as:
+- `card::add_card_module(m)?`
+- `data::add_data_module(m)?`
+- `model::add_model_module(m)?`
+- `experiment::add_experiment_module(m)?`
+- `agent::add_agent_module(m)?`
+- `service::add_service_module(m)?`
+- `types::add_types_module(m)?`
+
+Do not stop after adding `#[pyclass]`; registration, Python exports, stubs, and tests are part of the public API surface.
diff --git a/.codex/skills/opsml-rust-python/references/python-api-and-stubs.md b/.codex/skills/opsml-rust-python/references/python-api-and-stubs.md
new file mode 100644
index 0000000000..2244c9a0d0
--- /dev/null
+++ b/.codex/skills/opsml-rust-python/references/python-api-and-stubs.md
@@ -0,0 +1,59 @@
+# Python API And Stubs
+
+The Python package is the user-facing SDK, but the Rust extension owns the core behavior. Python additions should be thin, typed, and tested through user workflows.
+
+## Public API Wiring
+
+For new Python-visible Rust API, check every layer:
+1. Rust type/function exists in the owning crate.
+2. PyO3 class/function is registered in the appropriate `py-opsml/src/*` module.
+3. The module is attached from `py-opsml/src/lib.rs`.
+4. Python package exports are updated under `py-opsml/python/opsml/`.
+5. `__all__` is updated where the package uses it.
+6. Stubs are regenerated or updated through the repo workflow.
+7. Python tests cover the user-visible behavior.
+
+Do not leave a type reachable only through `_opsml` unless that is already the local convention for the feature.
+
+## Stub Workflow
+
+Generated stubs live under:
+- `py-opsml/python/opsml/_opsml.pyi`
+- `py-opsml/python/opsml/stubs/`
+
+Use the repo task:
+- `mise run py:setup`
+
+This task runs stub generation, syncs Python dependencies, and builds the Rust extension through maturin. Run it after Rust changes that affect Python-exposed classes, functions, signatures, docs, or enums.
+
+## Python Package Style
+
+Python code should:
+- Keep durable business behavior in Rust.
+- Use typed, ergonomic public APIs.
+- Add docstrings to public functions/classes when intent, side effects, errors, or examples are not obvious.
+- Avoid loose `Any` unless the Python boundary is truly dynamic.
+- Follow existing import, export, and test conventions in `py-opsml/python/opsml/`.
+
+When behavior is Python-only because it depends on a Python ecosystem object, keep the boundary explicit. Examples include Python model/data interfaces where user subclasses implement `save`, `load`, or prediction behavior.
+
+## Python Tests
+
+Python tests should model how a real user interacts with OpsML:
+- Construct the Python-facing object.
+- Register or load through `CardRegistry` when relevant.
+- Assert stable behavior and error messages.
+- Use fixtures such as `mock_db`, `pandas_data`, or `random_forest_classifier` where appropriate.
+
+Do not test generated implementation details when a user workflow test would prove the contract better.
+
+## Maturin And Versions
+
+Do not rely on remembered PyO3 or maturin versions. Inspect:
+- Root `Cargo.toml`.
+- `py-opsml/Cargo.toml`.
+- `py-opsml/pyproject.toml`.
+- Lockfiles.
+- `mise.toml`.
+
+Version-specific PyO3 patterns should match the versions currently pinned by the repository.
diff --git a/.codex/skills/opsml-rust-python/references/rust-core.md b/.codex/skills/opsml-rust-python/references/rust-core.md
new file mode 100644
index 0000000000..d1268ecd6b
--- /dev/null
+++ b/.codex/skills/opsml-rust-python/references/rust-core.md
@@ -0,0 +1,101 @@
+# Rust Core Practices
+
+OpsML's Python API is only as good as the Rust core underneath it. Design Rust code first as a clean, testable library; then expose the right boundary to Python.
+
+## API Shape
+
+Prefer APIs that make invalid states difficult to represent:
+- Use domain types instead of raw strings or loose maps for durable concepts.
+- Use enums for closed sets of states, backends, card kinds, operations, and variants.
+- Use structs with named fields for meaningful records.
+- Use traits for behavior shared across real implementations, not for one call site.
+- Keep public functions explicit about inputs, outputs, and error behavior.
+
+Do not shape core Rust APIs around what is easiest to extract from `PyAny`. Convert Python inputs at the boundary, then call Rust-native functions.
+
+## Zero-Cost Abstractions
+
+Prefer abstractions that compile down to direct code:
+- Generic functions with trait bounds when the caller can be monomorphized.
+- Enum dispatch for known backend variants, matching existing `StorageClientEnum` and `SqlClientEnum` patterns.
+- Iterators instead of building intermediate vectors.
+- Borrowed data such as `&str`, `&Path`, and `&[T]` when ownership is not needed.
+- `Cow<'_, str>` only when both borrowed and owned paths are real and the complexity pays for itself.
+
+Use `Box<dyn Trait>` only when runtime extensibility is required and the allocation/dynamic dispatch is an intentional tradeoff.
+
+## Ownership And Cloning
+
+Treat `.clone()` as a question, not a reflex:
+- Prefer borrowing when the callee does not need ownership.
+- Prefer moving values when the current scope no longer needs them.
+- Use `Arc<T>` for real shared ownership across tasks, state, or handlers.
+- Avoid `Arc<Mutex<T>>` as a default; first ask whether ownership, message passing, a narrower lock, or immutable state is enough.
+- Do not derive `Clone` speculatively. Derive it only when concrete call sites need it.
+
+Common acceptable clones:
+- Small identifiers or config values at API boundaries where ownership is clearer than lifetimes.
+- `Arc::clone` for shared application state.
+- Data copied into an owned response type.
+
+Common suspicious clones:
+- Large vectors, maps, schemas, payloads, or serialized values in loops.
+- Cloning to work around a borrow caused by overly broad scopes.
+- Cloning Python objects or PyO3 wrappers without a clear GIL/boundary reason.
+
+## Allocation And Strings
+
+Avoid accidental allocation in hot or repeated paths:
+- Use `String::with_capacity` when building a known-size string.
+- Use `Vec::with_capacity` when the item count is known or cheaply estimated.
+- Use `write!` into an existing `String` instead of repeated `format!` in loops.
+- Avoid serializing/deserializing just to move data between Rust layers.
+- Keep JSON conversion at API, storage, or Python boundaries unless the core domain truly stores JSON.
+
+Do not micro-optimize code that is not on a meaningful path. Prefer clear algorithms first, then optimize measured bottlenecks.
+
+## Traits
+
+Use traits when they express a stable capability:
+- Storage behavior.
+- SQL/card persistence behavior.
+- Card lifecycle behavior.
+- Interface behavior with multiple implementations.
+
+Keep traits small enough to implement correctly. Avoid kitchen-sink traits that force unrelated implementations to carry meaningless methods.
+
+Prefer associated types or generics when they simplify call sites. Avoid clever trait machinery when an enum, function, or concrete type would be easier to read and test.
+
+## Async And Shared State
+
+Use async for I/O boundaries: HTTP, database, storage, network calls, and server handlers. Keep pure computation synchronous unless the caller requires async.
+
+For shared server state:
+- Put heavy shared dependencies in `AppState`.
+- Wrap shared backend clients in `Arc` as established by the repo.
+- Avoid cloning heavy clients or rebuilding pools per request.
+- Keep locks out of request hot paths where possible.
+
+Use timeouts, cancellation-aware APIs, and bounded concurrency for external calls when the surrounding code already supports those patterns.
+
+## Error Design
+
+Rust errors should be precise and useful before they become Python exceptions:
+- Use `thiserror` enums for domain errors.
+- Include the failing operation and field/resource where possible.
+- Preserve source errors with `#[from]` only when the wrapped error is safe for Rust-only code.
+- Avoid `anyhow` in library surfaces unless the crate already uses it for an internal boundary.
+
+For errors crossing Python, follow `references/errors.md`.
+
+## Testing Rust Core
+
+New core logic should have Rust tests that do not require Python unless the behavior is inherently Python-facing.
+
+Good Rust tests:
+- Exercise domain behavior through public or crate-visible APIs.
+- Cover success, edge cases, and stable failures.
+- Use local fixtures and mocks instead of external services.
+- Keep SQLite/server tests isolated with `--test-threads=1` where the repo requires it.
+
+If a test requires Python for non-Python behavior, inspect the design for leaked PyO3 types or a misplaced boundary.
diff --git a/.codex/skills/opsml-rust-python/references/testing-workflows.md b/.codex/skills/opsml-rust-python/references/testing-workflows.md
new file mode 100644
index 0000000000..38ab3716a1
--- /dev/null
+++ b/.codex/skills/opsml-rust-python/references/testing-workflows.md
@@ -0,0 +1,64 @@
+# Testing And Workflow Commands
+
+Use `mise` as the default command surface. The tasks encode environment variables, working directories, feature flags, and server setup.
+
+## Default Commands
+
+Rust:
+- Format: `mise run format`
+- Lint: `mise run lints`
+- Full Rust aggregate when justified: `mise run test:unit`
+- Targeted crate tests: `cargo test -p <crate> <test_or_module> -- --nocapture --test-threads=1`
+
+Python:
+- Build stubs and extension: `mise run py:setup`
+- Format: `mise run py:format`
+- Lint/type checks: `mise run py:lints`
+- CI lint gate: `mise run py:lints-ci`
+- Unit tests: `mise run py:test:unit`
+- Service tests: `mise run py:test:service`
+- Integration tests: `mise run py:test:integration`
+
+Frontend work belongs to `opsml-ui`, not this skill.
+
+## Command Selection
+
+Use targeted tests first:
+- Changed a single Rust crate: run that crate's focused tests.
+- Changed SQL behavior: use the relevant `test:sql-*` task.
+- Changed server handlers: use targeted `opsml-server` tests with `--test-threads=1`.
+- Changed PyO3-exposed API: run `mise run py:setup`, then targeted Python tests or `mise run py:test:unit`.
+- Changed Python-only public API: run targeted pytest, then `mise run py:lints` if practical.
+
+Broaden to aggregate tasks when the change crosses boundaries or before final handoff on high-risk work.
+
+## Server Test Caution
+
+Do not run all `opsml_server` tests casually. The repo guidance warns that broad failures can leave stale state. Prefer isolated tests and cleanup. Use `TestHelper::new(None)` patterns and `helper.cleanup()` where applicable.
+
+Canonical Rust server tests:
+- Use `TestHelper::new(None)`.
+- Send requests through `helper.send_oneshot(request)` so auth headers are added.
+- Use `retry_flaky_test!` for transient SQLite contention.
+- Run with `--test-threads=1`.
+- Mock Scouter and SSO; do not require live external services.
+
+## PyO3 Change Checklist
+
+After changing a Python-exposed Rust type:
+1. Confirm Rust core behavior is tested without Python where possible.
+2. Confirm PyO3 registration is complete.
+3. Run `mise run py:setup`.
+4. Confirm imports work from `opsml`, not only from `_opsml`.
+5. Add or update Python tests for the user workflow.
+6. Run targeted Python tests or `mise run py:test:unit`.
+
+## Test Philosophy
+
+Tests should prove user journeys and stable contracts:
+- Card creation, serialization, registration, retrieval, and loading.
+- Local and server-backed registry behavior where both apply.
+- Structured error behavior for invalid inputs.
+- Python-visible behavior from the public `opsml` package.
+
+Avoid tests that mirror private implementation details. Add regression tests when fixing a bug.
diff --git a/.codex/skills/opsml-ui/SKILL.md b/.codex/skills/opsml-ui/SKILL.md
index fc7c30218c..fc2e56ac1b 100644
--- a/.codex/skills/opsml-ui/SKILL.md
+++ b/.codex/skills/opsml-ui/SKILL.md
@@ -31,6 +31,11 @@ Follow these repo-specific rules:
 - Prefer server-backed pagination, filtering, sorting, and aggregation for large remote datasets.
 - Use `VirtualScroller.svelte` or `@tanstack/svelte-virtual` for large scrollable views.
 - Do not add new UI libraries unless the user explicitly asks.
+- All functions, classes, methods, and components must have JSDoc comments. Use TSDoc tags like `@param`, `@returns`, `@throws`, and `@example` where relevant.
+
+When debugging, use the browser devtools, Svelte devtools, and Rust logging as your primary tools. Add temporary logging or breakpoints in the Svelte code or Rust backend as needed, but remove them before submitting the PR.
+
+When testing, prefer automated tests with Vitest and Svelte Testing Library. Add tests for new features and bug fixes, and consider adding tests for complex existing features that lack coverage. Use manual testing and build checks for visual polish, accessibility, performance, and exploratory testing of complex interactions.
 
 When making changes, inspect in this order:
 1. The route entrypoint (`+page.svelte`, `+page.ts`, `+page.server.ts`, `+layout.*`)
diff --git a/AGENTS.md b/AGENTS.md
index 66ca56c6b4..2843154251 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -428,6 +428,20 @@ Fixtures in `tests/conftest.py`:
 
 Test markers: `@pytest.mark.tensorflow` gates TF-specific tests; `mise run py:test:unit` excludes them by default.
 
+### ADK agent harness
+
+The offline Google ADK harness lives under `py-opsml/dev/integration/agent/`.
+Use it to verify agent tracing and attached eval behavior without a live Scouter:
+
+```bash
+mise run py:setup-adk
+mise run dev:e2e:smoke:offline
+```
+
+For live E2E runs, keep a sibling Scouter checkout at `../scouter` or set
+`SCOUTER_DIR=/path/to/scouter`, then run `mise run dev:e2e:start:servers`
+before `mise run dev:e2e:agent`.
+
 ---
 
 ## Feature Flags
diff --git a/CLAUDE.md b/CLAUDE.md
index f7fca0953c..9aa330bf2e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,14 +2,4 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-@AGENTS.md
-
-## Claude Code Notes
-
-- After modifying any Rust type exposed to Python, run the `pyo3-checklist` skill to verify all 6 wiring layers are complete (Rust impl → re-export → PyO3 registration → `__init__.py` → `__all__` → `.pyi` stub).
-- Use the `rust-python` skill when working with PyO3 bindings or the Rust↔Python boundary.
-- Use the `opsml-ui` skill when building, editing, or designing any UI component, page, layout, or dashboard.
-- Use the `opsml-ts-svelte` skill when writing TypeScript logic, Svelte 5 components, or SvelteKit routing/data loading.
-- Use the `agentic-architect` skill when modifying GenAI features, LLM client code, tool-calling logic, or anything in `opsml-mcp` / `opsml-genai`.
-- Run the `pre-pr` skill before creating any pull request.
-- Run the `review` skill for a full parallel code review (security, style, bugs, frontend) before merging.
+@AGENTS.md
\ No newline at end of file
diff --git a/Makefile b/Makefile
deleted file mode 100644
index e664b62ec9..0000000000
--- a/Makefile
+++ /dev/null
@@ -1,232 +0,0 @@
-.PHONY: format
-format:
-	cargo fmt --all
-
-.PHONY: lints
-lints:
-	cargo clippy --workspace --all-targets  -- -D warnings
-
-lints.pedantic:
-	cargo clippy --workspace --all-targets  -- -D warnings -W clippy::pedantic -A clippy::must_use_candidate -A clippy::missing_errors_doc
-
-####### TOML tests
-.PHONY: test.toml
-test.toml:
-	cargo test -p opsml-toml -- --nocapture --test-threads=1
-
-####### CLI tests
-.PHONY: test.cli
-test.cli:
-	cargo test -p opsml-cli -- --nocapture --test-threads=1
-
-####### SQL tests
-.PHONY: test.sql.sqlite
-test.sql.sqlite:
-	cargo test -p opsml-sql test_sqlite -- --nocapture --test-threads=1
-
-.PHONY: test.sql.enum
-test.sql.enum:
-	cargo test -p opsml-sql test_enum -- --nocapture --test-threads=1
-
-.PHONY: build.postgres
-build.postgres:
-	docker compose down --volumes
-	docker compose up -d --build postgres --wait
-
-.PHONY: test.sql.postgres
-test.sql.postgres: build.postgres
-	cargo test -p opsml-sql test_postgres -- --nocapture --test-threads=1
-
-.PHONY: build.mysql
-build.mysql:
-	docker compose down --volumes
-	docker compose up -d --build mysql --wait
-
-.PHONY: test.sql.mysql
-test.sql.mysql: build.mysql
-	cargo test -p opsml-sql test_mysql -- --nocapture --test-threads=1
-	docker compose down --volumes
-
-.PHONY: test.sql
-test.sql: test.sql.sqlite test.sql.enum test.sql.postgres test.sql.mysql
-
-test.service:
-	cargo test -p opsml-service -- --nocapture --test-threads=1
-
-######## Storage tests
-
-.PHONY: test.storage.local.server
-test.storage.local.server:
-	cargo test -p opsml-storage test_local_storage_server -- --nocapture --test-threads 1
-
-######## Collective Unit Tests
-##.PHONY: test.unit
-##test.unit: test.toml test.cli test.sql test.storage.server test.utils
-
-######## Server tests
-
-.PHONY: start.server
-start.server: stop.server build.ui
-	cargo build -p opsml-server
-	./target/debug/opsml-server
-
-start.server.background: stop.server build.ui
-	cargo build -p opsml-server
-	./target/debug/opsml-server &
-
-.PHONY: stop.server
-stop.server:
-	-lsof -ti:3000 | xargs kill -9 2>/dev/null || true
-#	rm -f opsml.db || true
-#	rm -rf opsml_registries || true
-
-######## Storage tests
-.PHONY: test.storage.client
-test.storage.client:
-	cargo test -p opsml-storage test_local_storage_client -- --nocapture
-
-.PHONY: test.storage.server
-test.storage.server:
-	cargo test -p opsml-storage test_local_storage_server -- --nocapture --test-threads 1
-
-
-.PHONY: test.utils
-test.utils:
-	cargo test -p opsml-utils -- --nocapture
-
-.PHONY: test.opsml.server
-test.server:
-	cargo test -p opsml-server test_opsml_server -- --nocapture --test-threads=1
-
-.PHONY: test.opsml.registry.client
-test.opsml.registry.client:
-	cargo test --features server -p opsml-registry test_registry_client -- --nocapture --test-threads=1
-
-.PHONY: test.version
-test.version:
-	cargo test -p opsml-version -- --nocapture --test-threads=1
-
-.PHONY: test.unit
-test.unit: test.toml test.cli test.sql test.storage.server test.server test.utils test.version
-
-###### UI ######
-UI_DIR = crates/opsml_server/opsml_ui
-PY_DIR = py-opsml
-
-ui.update.deps:
-	cd $(UI_DIR) && pnpm update
-
-.PHONY: ui.install.deps
-install.ui.deps:
-	cd $(UI_DIR) && pnpm install
-
-.PHONY: ui.install.deps.prod
-install.ui.deps.prod:
-	# remove existing node_modules
-	rm -rf $(UI_DIR)/node_modules
-	# install only production dependencies
-	cd $(UI_DIR) && pnpm install --prod
-
-.PHONY: build.ui
-build.ui:
-	cd $(UI_DIR) && pnpm install
-	cd $(UI_DIR) && pnpm build
-
-ui.dev:
-	cd $(UI_DIR) && pnpm run dev
-
-populate.cards:
-	cd $(PY_DIR) && uv run python -m dev.populate_cards
-
-
-.PHONY: changelog
-prepend.changelog:
-	# get version from Cargo.toml
-	@VERSION=$(shell grep '^version =' Cargo.toml | cut -d '"' -f 2) && \
-	git cliff --unreleased --tag $$VERSION --prepend CHANGELOG.md
-
-
-###### Development & Production - Separate Servers ######
-.PHONY: dev.backend
-dev.backend:
-	cargo build -p opsml-server
-	OPSML_SERVER_PORT=8080 ./target/debug/opsml-server
-
-.PHONY: dev.frontend
-dev.frontend:
-	cd $(UI_DIR) && pnpm run dev
-
-.PHONY: build.backend
-build.backend:
-	cargo build -p opsml-server --target
-
-.PHONY: start.backend
-start.backend: build.backend
-	OPSML_SERVER_PORT=8080 ./target/release/opsml-server
-
-.PHONY: start.frontend
-start.frontend: build.ui
-	cd $(UI_DIR) && node build/index.js
-
-.PHONY: dev.both
-dev.both:
-	@echo "Starting both servers in development mode..."
-	@echo "Backend API: http://localhost:8080"
-	@echo "Frontend SSR: http://localhost:3000"
-	@make -j2 dev.backend dev.frontend
-
-.PHONY: start.both
-start.both:
-	@echo "Starting both servers in production mode..."
-	@echo "Backend API: http://localhost:8080"
-	@echo "Frontend SSR: http://localhost:3000"
-	@make -j2 dev.backend start.frontend
-
-.PHONY: stop.both
-stop.both:
-	-lsof -ti:3000 | xargs kill -9 2>/dev/null || true
-	-lsof -ti:8080 | xargs kill -9 2>/dev/null || true
-
-
-###### Scouter Integration
-###### Service B (Scouter) is expected to run independently on port 8000.
-###### Service A (opsml) exposes its backend on 8090 and frontend on 3000.
-###### Stopping Service B will NOT affect Service A — opsml degrades gracefully
-###### (Scouter-backed features show as unavailable; core UI keeps working).
-######
-###### Usage:
-######   Terminal 1: make dev.both.scouter    (starts opsml backend + frontend)
-######   Terminal 2: cd <scouter> && make start.server
-######   To stop opsml only: make stop.both.scouter
-
-.PHONY: dev.backend.scouter
-dev.backend.scouter:
-	cargo build -p opsml-server
-	OPSML_SERVER_PORT=8090 SCOUTER_SERVER_URI=http://localhost:8000 ./target/debug/opsml-server
-
-.PHONY: dev.both.scouter
-dev.both.scouter: stop.both.scouter
-	@echo "Building opsml backend..."
-	@cargo build -p opsml-server
-	@echo "Starting backend on port 8090 (Scouter integration: http://localhost:8000)"
-	@echo "Starting frontend on port 3000"
-	@# Run backend as an independent background process (separate process group so
-	@# Ctrl-C on the frontend does not propagate to it).
-	@OPSML_SERVER_PORT=8090 SCOUTER_SERVER_URI=http://localhost:8000 \
-		nohup ./target/debug/opsml-server > /tmp/opsml-backend.log 2>&1 & \
-		echo $$! > /tmp/opsml-backend.pid && \
-		echo "Backend PID: $$(cat /tmp/opsml-backend.pid) — logs: /tmp/opsml-backend.log"
-	@# Frontend runs in the foreground; kill it with Ctrl-C when done.
-	cd $(UI_DIR) && OPSML_SERVER_PORT=8090 pnpm run dev
-
-.PHONY: stop.both.scouter
-stop.both.scouter:
-	@# Kill by saved PID first (clean shutdown), then fall back to port scan.
-	-[ -f /tmp/opsml-backend.pid ] && kill $$(cat /tmp/opsml-backend.pid) 2>/dev/null || true
-	-rm -f /tmp/opsml-backend.pid
-	-lsof -ti:8090 | xargs kill -9 2>/dev/null || true
-	-lsof -ti:3000 | xargs kill -9 2>/dev/null || true
-
-.PHONY: logs.backend.scouter
-logs.backend.scouter:
-	tail -f /tmp/opsml-backend.log
\ No newline at end of file
diff --git a/crates/opsml_server/opsml_ui/src/lib/components/card/agent/evaluation/AgentEvalDashboard.svelte b/crates/opsml_server/opsml_ui/src/lib/components/card/agent/evaluation/AgentEvalDashboard.svelte
index d34b85e71f..2c375f138b 100644
--- a/crates/opsml_server/opsml_ui/src/lib/components/card/agent/evaluation/AgentEvalDashboard.svelte
+++ b/crates/opsml_server/opsml_ui/src/lib/components/card/agent/evaluation/AgentEvalDashboard.svelte
@@ -37,6 +37,8 @@
     Loader2, TrendingUp, KeySquare
   } from 'lucide-svelte';
 
+  type PageDirection = 'next' | 'previous';
+
   interface Props {
     agentName: string;
     agentVersion: string;
@@ -93,55 +95,82 @@
     } catch (err) {
       console.error('[AgentEvalDashboard] Refresh failed:', err);
     } finally {
+      evalData = [...evalData];
       isRefreshing = false;
       resetRecordTraceMap();
       timeRangeState.endRefresh();
     }
   }
 
-  /** Advance the record page for all evals that have a cursor in that direction. */
-  async function handleRecordPageChange(direction: string) {
+  /**
+   * Clone a successful eval entry after refresh so derived merged pages see
+   * fresh object identities instead of relying on nested `selectedData`
+   * mutation inside `refreshAgentMonitoringData`.
+   */
+  function cloneEvalEntry(e: AgentPromptEvalData): AgentPromptEvalData {
+    if (e.monitoringData.status !== 'success') return e;
+    return {
+      ...e,
+      monitoringData: {
+        ...e.monitoringData,
+        selectedData: { ...e.monitoringData.selectedData },
+      },
+    };
+  }
+
+  /**
+   * Advance the record page for every prompt eval with a cursor in the
+   * requested direction. Evals without that cursor remain on their current page.
+   */
+  async function handleRecordPageChange(direction: PageDirection) {
     isRefreshing = true;
     timeRangeState.beginRefresh();
     try {
-      await Promise.all(
+      const nextEvalData = await Promise.all(
         evalData.map(async (e) => {
-          if (e.monitoringData.status !== 'success') return;
+          if (e.monitoringData.status !== 'success') return e;
           const page = e.monitoringData.selectedData.records;
           const canPage = direction === 'next' ? page?.has_next : page?.has_previous;
           const cursor = direction === 'next' ? page?.next_cursor : page?.previous_cursor;
-          if (!canPage || !cursor) return;
+          if (!canPage || !cursor) return e;
           await refreshAgentMonitoringData(fetch, e.monitoringData, {
             recordCursor: { cursor, direction },
           });
+          return cloneEvalEntry(e);
         })
       );
+      evalData = nextEvalData;
     } catch (err) {
       console.error('[AgentEvalDashboard] Record page change failed:', err);
     } finally {
       isRefreshing = false;
-      appendToRecordTraceMap();
+      resetRecordTraceMap();
       timeRangeState.endRefresh();
     }
   }
 
-  /** Advance the workflow page for all evals that have a cursor in that direction. */
-  async function handleWorkflowPageChange(direction: string) {
+  /**
+   * Advance the workflow page for every prompt eval with a cursor in the
+   * requested direction. Record pagination state is intentionally untouched.
+   */
+  async function handleWorkflowPageChange(direction: PageDirection) {
     isRefreshing = true;
     timeRangeState.beginRefresh();
     try {
-      await Promise.all(
+      const nextEvalData = await Promise.all(
         evalData.map(async (e) => {
-          if (e.monitoringData.status !== 'success') return;
+          if (e.monitoringData.status !== 'success') return e;
           const page = e.monitoringData.selectedData.workflows;
           const canPage = direction === 'next' ? page?.has_next : page?.has_previous;
           const cursor = direction === 'next' ? page?.next_cursor : page?.previous_cursor;
-          if (!canPage || !cursor) return;
+          if (!canPage || !cursor) return e;
           await refreshAgentMonitoringData(fetch, e.monitoringData, {
             workflowCursor: { cursor, direction },
           });
+          return cloneEvalEntry(e);
         })
       );
+      evalData = nextEvalData;
     } catch (err) {
       console.error('[AgentEvalDashboard] Workflow page change failed:', err);
     } finally {
diff --git a/crates/opsml_server/opsml_ui/src/lib/components/card/agent/evaluation/AgentEvalRecordTable.svelte b/crates/opsml_server/opsml_ui/src/lib/components/card/agent/evaluation/AgentEvalRecordTable.svelte
index 7077004de9..25a637c389 100644
--- a/crates/opsml_server/opsml_ui/src/lib/components/card/agent/evaluation/AgentEvalRecordTable.svelte
+++ b/crates/opsml_server/opsml_ui/src/lib/components/card/agent/evaluation/AgentEvalRecordTable.svelte
@@ -15,6 +15,8 @@
   import { ArrowLeft, ArrowRight } from 'lucide-svelte';
   import EvalRecordSideBar from '$lib/components/scouter/agent/record/EvalRecordSideBar.svelte';
 
+  type PageDirection = 'next' | 'previous';
+
   let {
     records,
     hasNext,
@@ -25,7 +27,7 @@
     records: RecordWithAgent[];
     hasNext: boolean;
     hasPrevious: boolean;
-    onPageChange: (direction: string) => void;
+    onPageChange: (direction: PageDirection) => void | Promise<void>;
     isRefreshing?: boolean;
   } = $props();
 
@@ -72,12 +74,23 @@
     isSelected = false;
   }
 
+  /**
+   * Guards the record pagination callback so disabled controls cannot emit
+   * stale page requests while a refresh is already in flight.
+   */
+  async function requestPage(direction: PageDirection) {
+    if (isRefreshing) return;
+    if (direction === 'next' && !hasNext) return;
+    if (direction === 'previous' && !hasPrevious) return;
+    await onPageChange(direction);
+  }
+
   // Prompt column prepended before ID; 1fr on Entity Type consumes whitespace.
   // min-w-[1050px] = EvalRecordTable's 900px + ~150px for the Prompt column.
   const gridLayout = "grid-template-columns: 140px 80px 140px 100px 1fr 140px 140px 100px;";
 </script>
 
-<div class="pt-2 h-full flex flex-col min-h-0 transition-opacity duration-200 {isRefreshing ? 'opacity-60 pointer-events-none' : ''}">
+<div class="pt-2 h-full flex flex-col min-h-0 transition-opacity duration-200 {isRefreshing ? 'opacity-60' : ''}">
   <div class="border-2 border-black rounded-base bg-white flex flex-col h-full max-h-[500px] overflow-hidden">
 
     <div class="overflow-auto flex-1 w-full relative">
@@ -176,16 +189,20 @@
     {#if records.length > 0}
       <div class="border-t-2 border-black bg-gray-50 p-2 flex justify-center gap-2 items-center">
         <button
+          type="button"
+          aria-label="Previous evaluation records page"
           class="btn bg-surface-50 text-primary-800 disabled:text-primary-400 border-black border-2 shadow-small shadow-hover-small h-9 px-3 flex items-center justify-center disabled:opacity-50 disabled:hover:translate-x-0 disabled:hover:translate-y-0 disabled:hover:shadow-small"
-          onclick={() => onPageChange('previous')}
-          disabled={!hasPrevious}
+          onclick={() => requestPage('previous')}
+          disabled={isRefreshing || !hasPrevious}
         >
           <ArrowLeft class="w-4 h-4" color="currentColor"/>
         </button>
         <button
+          type="button"
+          aria-label="Next evaluation records page"
           class="btn bg-surface-50 text-primary-800 disabled:text-primary-400 border-black border-2 shadow-small shadow-hover-small h-9 px-3 flex items-center justify-center disabled:opacity-50 disabled:hover:translate-x-0 disabled:hover:translate-y-0 disabled:hover:shadow-small"
-          onclick={() => onPageChange('next')}
-          disabled={!hasNext}
+          onclick={() => requestPage('next')}
+          disabled={isRefreshing || !hasNext}
         >
           <ArrowRight class="w-4 h-4" color="currentColor"/>
         </button>
diff --git a/crates/opsml_server/opsml_ui/src/lib/components/card/agent/evaluation/AgentEvalWorkflowTable.svelte b/crates/opsml_server/opsml_ui/src/lib/components/card/agent/evaluation/AgentEvalWorkflowTable.svelte
index 149cc4c94d..ccb9f363c4 100644
--- a/crates/opsml_server/opsml_ui/src/lib/components/card/agent/evaluation/AgentEvalWorkflowTable.svelte
+++ b/crates/opsml_server/opsml_ui/src/lib/components/card/agent/evaluation/AgentEvalWorkflowTable.svelte
@@ -11,6 +11,8 @@
   import { ArrowLeft, ArrowRight, ExternalLink } from 'lucide-svelte';
   import AgentEvalWorkflowSideBar from '$lib/components/scouter/agent/workflow/AgentEvalWorkflowSideBar.svelte';
 
+  type PageDirection = 'next' | 'previous';
+
   let {
     workflows,
     hasNext,
@@ -21,7 +23,7 @@
     workflows: WorkflowWithAgent[];
     hasNext: boolean;
     hasPrevious: boolean;
-    onPageChange: (direction: string) => void;
+    onPageChange: (direction: PageDirection) => void | Promise<void>;
     isRefreshing?: boolean;
   } = $props();
 
@@ -61,11 +63,22 @@
     isSelected = false;
   }
 
+  /**
+   * Guards the workflow pagination callback so disabled controls cannot emit
+   * stale page requests while a refresh is already in flight.
+   */
+  async function requestPage(direction: PageDirection) {
+    if (isRefreshing) return;
+    if (direction === 'next' && !hasNext) return;
+    if (direction === 'previous' && !hasPrevious) return;
+    await onPageChange(direction);
+  }
+
   // Prompt + Nav columns added before ID; 1fr on Record UID consumes whitespace
   const gridLayout = "grid-template-columns: 120px 50px 60px 140px 100px 80px 80px 80px 100px 1fr;";
 </script>
 
-<div class="pt-2 h-full flex flex-col min-h-0 transition-opacity duration-200 {isRefreshing ? 'opacity-60 pointer-events-none' : ''}">
+<div class="pt-2 h-full flex flex-col min-h-0 transition-opacity duration-200 {isRefreshing ? 'opacity-60' : ''}">
   <div class="border-2 border-black rounded-lg bg-white flex flex-col h-full max-h-[500px] overflow-hidden">
 
     <div class="overflow-auto flex-1 w-full relative">
@@ -166,16 +179,20 @@
     {#if workflows.length > 0}
       <div class="border-t-2 border-black bg-gray-50 p-2 flex justify-center gap-2 items-center">
         <button
+          type="button"
+          aria-label="Previous workflow results page"
           class="btn bg-surface-50 text-primary-800 disabled:text-primary-400 border-black border-2 shadow-small shadow-hover-small h-9 px-3 flex items-center justify-center disabled:opacity-50 disabled:hover:translate-x-0 disabled:hover:translate-y-0 disabled:hover:shadow-small"
-          onclick={() => onPageChange('previous')}
-          disabled={!hasPrevious}
+          onclick={() => requestPage('previous')}
+          disabled={isRefreshing || !hasPrevious}
         >
           <ArrowLeft class="w-4 h-4" color="currentColor"/>
         </button>
         <button
+          type="button"
+          aria-label="Next workflow results page"
           class="btn bg-surface-50 text-primary-800 disabled:text-primary-400 border-black border-2 shadow-small shadow-hover-small h-9 px-3 flex items-center justify-center disabled:opacity-50 disabled:hover:translate-x-0 disabled:hover:translate-y-0 disabled:hover:shadow-small"
-          onclick={() => onPageChange('next')}
-          disabled={!hasNext}
+          onclick={() => requestPage('next')}
+          disabled={isRefreshing || !hasNext}
         >
           <ArrowRight class="w-4 h-4" color="currentColor"/>
         </button>
diff --git a/crates/opsml_server/opsml_ui/src/lib/components/card/agent/evaluation/__tests__/AgentEvalDashboard.pagination.test.ts b/crates/opsml_server/opsml_ui/src/lib/components/card/agent/evaluation/__tests__/AgentEvalDashboard.pagination.test.ts
new file mode 100644
index 0000000000..54c8d66ee8
--- /dev/null
+++ b/crates/opsml_server/opsml_ui/src/lib/components/card/agent/evaluation/__tests__/AgentEvalDashboard.pagination.test.ts
@@ -0,0 +1,210 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { fireEvent, render, screen, waitFor } from "@testing-library/svelte";
+import AgentEvalDashboard from "../AgentEvalDashboard.svelte";
+import type { AgentPromptEvalData } from "../types";
+import type {
+  AgentMonitoringPageData,
+  AgentRefreshOptions,
+} from "$lib/components/scouter/dashboard/utils";
+import { Status } from "$lib/components/scouter/agent/types";
+import { EntityType } from "$lib/components/scouter/types";
+
+type SuccessfulAgentMonitoringPageData = Extract<
+  AgentMonitoringPageData,
+  { status: "success" }
+>;
+
+const refreshCalls = vi.hoisted(() => [] as unknown[]);
+
+vi.mock("chart.js/auto", () => ({
+  Chart: class {
+    static register = vi.fn();
+    destroy = vi.fn();
+    resetZoom = vi.fn();
+  },
+}));
+vi.mock("chart.js", () => ({ Filler: {} }));
+vi.mock("chartjs-plugin-zoom", () => ({ default: {} }));
+vi.mock("chartjs-plugin-annotation", () => ({ default: {} }));
+vi.mock("chartjs-adapter-date-fns", () => ({}));
+
+vi.mock("$lib/components/scouter/dashboard/utils", async () => {
+  const actual = await vi.importActual<typeof import("$lib/components/scouter/dashboard/utils")>(
+    "$lib/components/scouter/dashboard/utils",
+  );
+  return {
+    ...actual,
+    refreshAgentMonitoringData: vi.fn(async (
+      _fetch: typeof globalThis.fetch,
+      monitoringData: SuccessfulAgentMonitoringPageData,
+      options: AgentRefreshOptions = {},
+    ) => {
+      refreshCalls.push(options);
+      if (options.recordCursor) {
+        monitoringData.selectedData = {
+          ...monitoringData.selectedData,
+          records: {
+            items: [makeRecord("pagetwo2", 2, "2026-01-02T00:00:00Z")],
+            has_next: false,
+            has_previous: true,
+            previous_cursor: { id: 2, created_at: "2026-01-02T00:00:00Z" },
+          },
+        };
+      }
+      if (options.workflowCursor) {
+        monitoringData.selectedData = {
+          ...monitoringData.selectedData,
+          workflows: {
+            items: [makeWorkflow(2, "workflow-record-page-2", "2026-01-02T00:00:00Z")],
+            has_next: false,
+            has_previous: true,
+            previous_cursor: { id: 2, created_at: "2026-01-02T00:00:00Z" },
+          },
+        };
+      }
+    }),
+  };
+});
+
+/** Builds a minimal evaluation record with cursor fields needed by pagination. */
+function makeRecord(uid: string, id: number, createdAt: string) {
+  return {
+    record_id: `record-${id}`,
+    created_at: createdAt,
+    uid,
+    context: {},
+    id,
+    updated_at: null,
+    processing_started_at: null,
+    processing_ended_at: null,
+    processing_duration: null,
+    entity_id: id,
+    entity_uid: `entity-${id}`,
+    status: Status.Processed,
+    entity_type: EntityType.Agent,
+    trace_id: `trace-${id}`,
+  };
+}
+
+/** Builds a minimal workflow result with cursor fields needed by pagination. */
+function makeWorkflow(id: number, recordUid: string, createdAt: string) {
+  return {
+    id,
+    record_uid: recordUid,
+    entity_id: id,
+    entity_uid: `entity-${id}`,
+    created_at: createdAt,
+    total_tasks: 4,
+    passed_tasks: 4,
+    failed_tasks: 0,
+    pass_rate: 1,
+    duration_ms: 1200,
+    execution_plan: { stages: [], nodes: {} },
+  };
+}
+
+/** Builds dashboard props with one next-page cursor for records and workflows. */
+function makeEvalData(): AgentPromptEvalData[] {
+  return [
+    {
+      promptCard: {
+        space: "default",
+        name: "triage_prompt",
+        version: "1.0.0",
+      },
+      monitoringData: {
+        status: "success",
+        uid: "eval-profile-1",
+        registryType: "prompt",
+        selectedTimeRange: {
+          label: "Past 24 Hours",
+          value: "24hours",
+          startTime: "2026-01-01T00:00:00Z",
+          endTime: "2026-01-02T00:00:00Z",
+          bucketInterval: "1 hours",
+        },
+        profile: {
+          config: {
+            uid: "eval-profile-1",
+            space: "default",
+          },
+        },
+        selectedData: {
+          metrics: { workflow: { metrics: {} } },
+          driftAlerts: { items: [], has_next: false, has_previous: false },
+          records: {
+            items: [makeRecord("pageone1", 1, "2026-01-01T00:00:00Z")],
+            has_next: true,
+            next_cursor: { id: 1, created_at: "2026-01-01T00:00:00Z" },
+            has_previous: false,
+          },
+          workflows: {
+            items: [makeWorkflow(1, "workflow-record-page-1", "2026-01-01T00:00:00Z")],
+            has_next: true,
+            next_cursor: { id: 1, created_at: "2026-01-01T00:00:00Z" },
+            has_previous: false,
+          },
+        },
+      },
+    } as unknown as AgentPromptEvalData,
+  ];
+}
+
+describe("AgentEvalDashboard pagination", () => {
+  beforeEach(() => {
+    Object.defineProperty(window, "matchMedia", {
+      writable: true,
+      value: vi.fn().mockImplementation((query: string) => ({
+        matches: false,
+        media: query,
+        onchange: null,
+        addEventListener: vi.fn(),
+        removeEventListener: vi.fn(),
+        addListener: vi.fn(),
+        removeListener: vi.fn(),
+        dispatchEvent: vi.fn(),
+      })),
+    });
+  });
+
+  it("pages records with recordCursor and replaces visible record rows", async () => {
+    refreshCalls.length = 0;
+    render(AgentEvalDashboard, {
+      props: {
+        agentName: "support_agent",
+        agentVersion: "1.0.0",
+        agentPromptEvals: makeEvalData(),
+      },
+    });
+
+    expect(screen.getByText("pageone1")).toBeInTheDocument();
+    await fireEvent.click(screen.getByRole("button", { name: "Next evaluation records page" }));
+
+    await waitFor(() => expect(screen.getByText("pagetwo2")).toBeInTheDocument());
+    expect(refreshCalls).toEqual([
+      { recordCursor: { cursor: { id: 1, created_at: "2026-01-01T00:00:00Z" }, direction: "next" } },
+    ]);
+    expect(screen.queryByText("pageone1")).not.toBeInTheDocument();
+  });
+
+  it("pages workflows with workflowCursor and does not send a record cursor", async () => {
+    refreshCalls.length = 0;
+    render(AgentEvalDashboard, {
+      props: {
+        agentName: "support_agent",
+        agentVersion: "1.0.0",
+        agentPromptEvals: makeEvalData(),
+      },
+    });
+
+    expect(screen.getByText("workflow")).toBeInTheDocument();
+    await fireEvent.click(screen.getByRole("button", { name: "Next workflow results page" }));
+
+    await waitFor(() => {
+      expect(refreshCalls).toEqual([
+        { workflowCursor: { cursor: { id: 1, created_at: "2026-01-01T00:00:00Z" }, direction: "next" } },
+      ]);
+    });
+    expect(refreshCalls[0]).not.toHaveProperty("recordCursor");
+  });
+});
diff --git a/crates/opsml_server/opsml_ui/src/lib/components/card/agent/evaluation/__tests__/AgentEvalTables.pagination.test.ts b/crates/opsml_server/opsml_ui/src/lib/components/card/agent/evaluation/__tests__/AgentEvalTables.pagination.test.ts
new file mode 100644
index 0000000000..d828921d18
--- /dev/null
+++ b/crates/opsml_server/opsml_ui/src/lib/components/card/agent/evaluation/__tests__/AgentEvalTables.pagination.test.ts
@@ -0,0 +1,80 @@
+import { fireEvent, render, screen } from "@testing-library/svelte";
+import { describe, expect, it, vi } from "vitest";
+import AgentEvalRecordTable from "../AgentEvalRecordTable.svelte";
+import AgentEvalWorkflowTable from "../AgentEvalWorkflowTable.svelte";
+import type { RecordWithAgent, WorkflowWithAgent } from "../types";
+
+const record = {
+  _agentName: "triage_prompt",
+  _evalPath: "/opsml/prompt/card/default/triage/1.0.0/evaluation",
+  record_id: "record-a",
+  created_at: "2026-01-01T00:00:00Z",
+  uid: "record-uid-a",
+  context: {},
+  id: 1,
+  updated_at: null,
+  processing_started_at: null,
+  processing_ended_at: null,
+  processing_duration: null,
+  entity_id: 1,
+  entity_uid: "entity-a",
+  status: "Processed",
+  entity_type: "Agent",
+  trace_id: "trace-a",
+} as RecordWithAgent;
+
+const workflow = {
+  _agentName: "triage_prompt",
+  _evalPath: "/opsml/prompt/card/default/triage/1.0.0/evaluation",
+  _profile: {} as WorkflowWithAgent["_profile"],
+  _traceId: "trace-a",
+  id: 1,
+  record_uid: "record-uid-a",
+  entity_id: 1,
+  entity_uid: "entity-a",
+  created_at: "2026-01-01T00:00:00Z",
+  total_tasks: 4,
+  passed_tasks: 4,
+  failed_tasks: 0,
+  pass_rate: 1,
+  duration_ms: 1200,
+  execution_plan: { stages: [], nodes: {} },
+} as WorkflowWithAgent;
+
+describe("Agent eval pagination tables", () => {
+  it("emits record pagination directions only when controls are enabled", async () => {
+    const onPageChange = vi.fn();
+    render(AgentEvalRecordTable, {
+      props: {
+        records: [record],
+        hasNext: true,
+        hasPrevious: false,
+        onPageChange,
+      },
+    });
+
+    await fireEvent.click(screen.getByRole("button", { name: "Next evaluation records page" }));
+    await fireEvent.click(screen.getByRole("button", { name: "Previous evaluation records page" }));
+
+    expect(onPageChange).toHaveBeenCalledTimes(1);
+    expect(onPageChange).toHaveBeenCalledWith("next");
+  });
+
+  it("emits workflow pagination directions only when controls are enabled", async () => {
+    const onPageChange = vi.fn();
+    render(AgentEvalWorkflowTable, {
+      props: {
+        workflows: [workflow],
+        hasNext: false,
+        hasPrevious: true,
+        onPageChange,
+      },
+    });
+
+    await fireEvent.click(screen.getByRole("button", { name: "Next workflow results page" }));
+    await fireEvent.click(screen.getByRole("button", { name: "Previous workflow results page" }));
+
+    expect(onPageChange).toHaveBeenCalledTimes(1);
+    expect(onPageChange).toHaveBeenCalledWith("previous");
+  });
+});
diff --git a/crates/opsml_server/opsml_ui/src/lib/components/card/agent/observability/AgentsTable.svelte b/crates/opsml_server/opsml_ui/src/lib/components/card/agent/observability/AgentsTable.svelte
index 7f01ee1b35..ccd6e4d08f 100644
--- a/crates/opsml_server/opsml_ui/src/lib/components/card/agent/observability/AgentsTable.svelte
+++ b/crates/opsml_server/opsml_ui/src/lib/components/card/agent/observability/AgentsTable.svelte
@@ -24,6 +24,35 @@
     const cmp = av < bv ? -1 : av > bv ? 1 : 0;
     return sortAsc ? cmp : -cmp;
   }));
+
+  /**
+   * Builds the stable part of a row key from business identifiers only.
+   * Metric counters and sort position are intentionally excluded so refreshed
+   * activity data does not remount the same logical agent row.
+   */
+  function agentRowKeyBase(row: GenAiAgentActivity): string {
+    const key = [
+      row.agent_id ?? "",
+      row.conversation_id ?? "",
+      row.agent_name ?? "",
+    ].join("|");
+    return key.length > 2 ? key : "unknown-agent";
+  }
+
+  /**
+   * Adds a deterministic duplicate suffix only when two rows share the same
+   * business identity. The suffix is not sort-position based, so reordering the
+   * same rows keeps each rendered row attached to the same logical agent.
+   */
+  const keyedRows = $derived.by(() => {
+    const counts: Record<string, number> = {};
+    return sorted.map((row) => {
+      const base = agentRowKeyBase(row);
+      const seen = counts[base] ?? 0;
+      counts[base] = seen + 1;
+      return { row, key: seen === 0 ? base : `${base}#${seen}` };
+    });
+  });
 </script>
 
 <div class="rounded-base border-2 border-black shadow bg-surface-50 overflow-hidden">
@@ -58,12 +87,12 @@
         </tr>
       </thead>
       <tbody>
-        {#if sorted.length === 0}
+        {#if keyedRows.length === 0}
           <tr>
             <td colspan="4" class="px-2 py-3 text-center text-xs text-primary-700">No data</td>
           </tr>
         {:else}
-          {#each sorted as row (row.agent_id ?? row.agent_name)}
+          {#each keyedRows as { row, key } (key)}
             <tr class="border-b border-black hover:bg-primary-100">
               <td class="px-2 py-1 text-xs font-mono text-primary-900 truncate max-w-[120px]">{row.agent_name ?? '—'}</td>
               <td class="px-2 py-1 text-xs font-mono text-primary-900 text-right">{fmtCompact(row.span_count)}</td>
diff --git a/crates/opsml_server/opsml_ui/src/lib/components/card/agent/observability/__tests__/AgentsTable.test.ts b/crates/opsml_server/opsml_ui/src/lib/components/card/agent/observability/__tests__/AgentsTable.test.ts
new file mode 100644
index 0000000000..33fe8d7c8d
--- /dev/null
+++ b/crates/opsml_server/opsml_ui/src/lib/components/card/agent/observability/__tests__/AgentsTable.test.ts
@@ -0,0 +1,32 @@
+import { render } from "@testing-library/svelte";
+import { describe, expect, it } from "vitest";
+import AgentsTable from "../AgentsTable.svelte";
+import type { GenAiAgentActivity } from "../types";
+
+describe("AgentsTable", () => {
+  it("renders multiple rows sharing the same agent_name", () => {
+    const agents: GenAiAgentActivity[] = [
+      {
+        agent_name: "responder_agent",
+        agent_id: null,
+        conversation_id: "conv-1",
+        span_count: 3,
+        total_input_tokens: 100,
+        total_output_tokens: 50,
+        last_seen: null,
+      },
+      {
+        agent_name: "responder_agent",
+        agent_id: null,
+        conversation_id: "conv-2",
+        span_count: 7,
+        total_input_tokens: 200,
+        total_output_tokens: 90,
+        last_seen: null,
+      },
+    ];
+
+    const { getAllByText } = render(AgentsTable, { props: { agents } });
+    expect(getAllByText("responder_agent")).toHaveLength(2);
+  });
+});
diff --git a/crates/opsml_server/opsml_ui/src/lib/components/trace/TraceDashboard.svelte b/crates/opsml_server/opsml_ui/src/lib/components/trace/TraceDashboard.svelte
index eeb9287029..86deef1809 100644
--- a/crates/opsml_server/opsml_ui/src/lib/components/trace/TraceDashboard.svelte
+++ b/crates/opsml_server/opsml_ui/src/lib/components/trace/TraceDashboard.svelte
@@ -1,6 +1,7 @@
 <script lang="ts">
+  import { replaceState } from "$app/navigation";
+  import { resolve } from "$app/paths";
   import type {
-    ActiveFilter,
     TimeRange,
     TraceFacetDimension,
     TraceFacetsResponse,
@@ -13,6 +14,22 @@
     TracePaginationResponse,
     TraceSpansResponse,
   } from "./types";
+  import {
+    addToClause,
+    attrClause,
+    durationMaxClause,
+    durationMinClause,
+    hasErrorsClause,
+    removeClauseDimension,
+    replaceClauseDimension,
+    serviceClause,
+    serviceInstanceIdClause,
+    serviceNamespaceClause,
+    serviceVersionClause,
+    statusCodeClause,
+    type ActiveFilter,
+    type FilterClause,
+  } from "./clause";
   import type { DateTime } from "$lib/types";
   import ChipBar from "./filters/ChipBar.svelte";
   import FacetSidebar from "./filters/FacetSidebar.svelte";
@@ -71,6 +88,8 @@
     const metricsRequest: TraceMetricsRequest = {
       bucket_interval: filters.bucket_interval,
       ...filters.filters,
+      start_time: filters.filters.start_time ?? selectedTimeRange.startTime,
+      end_time: filters.filters.end_time ?? selectedTimeRange.endTime,
     };
 
     const metrics: TraceMetricsResponse = await getServerTraceMetrics(
@@ -88,18 +107,21 @@
   }
 
   async function getTraceFacetsForRange(): Promise<TraceFacetsResponse> {
-    const [serviceFacets, namespaceFacets, versionFacets, instanceFacets, statusFacets] = await Promise.all([
-      getServerTraceFacets(fetch, { ...filters.filters, service_name: undefined }),
-      getServerTraceFacets(fetch, { ...filters.filters, service_namespace: undefined }),
-      getServerTraceFacets(fetch, { ...filters.filters, service_version: undefined }),
-      getServerTraceFacets(fetch, { ...filters.filters, service_instance_id: undefined }),
-      getServerTraceFacets(fetch, { ...filters.filters, status_code: undefined }),
+    const [serviceFacets, statusFacets] = await Promise.all([
+      getServerTraceFacets(fetch, {
+        ...filters.filters,
+        clause: removeClauseDimension(filters.filters.clause, "service"),
+      }),
+      getServerTraceFacets(fetch, {
+        ...filters.filters,
+        clause: removeClauseDimension(filters.filters.clause, "status_code"),
+      }),
     ]);
     return {
       services: serviceFacets.services,
-      namespaces: namespaceFacets.namespaces ?? [],
-      versions: versionFacets.versions ?? [],
-      instance_ids: instanceFacets.instance_ids ?? [],
+      namespaces: [],
+      versions: [],
+      instance_ids: [],
       status_codes: statusFacets.status_codes,
       total_count: serviceFacets.total_count,
     };
@@ -109,7 +131,7 @@
     const url = new URL(window.location.href);
     if (url.searchParams.has("trace_id")) {
       url.searchParams.delete("trace_id");
-      history.replaceState(history.state, "", url.pathname + url.search);
+      replaceState(resolve((url.pathname + url.search) as `/opsml/${string}`), history.state);
     }
   }
 
@@ -239,149 +261,128 @@
   }
 
   function addService(service: string) {
-    const next = {
-      ...filters,
-      filters: { ...filters.filters, service_name: service },
-    };
-    void handleFiltersChange(next);
+    updateClause(replaceClauseDimension(filters.filters.clause, "service", serviceClause(service)));
   }
 
   function addStatus(status: number) {
-    const next = {
-      ...filters,
-      filters: { ...filters.filters, status_code: status },
-    };
-    void handleFiltersChange(next);
+    updateClause(replaceClauseDimension(filters.filters.clause, "status_code", statusCodeClause(status)));
   }
 
   function addHasErrors() {
-    const next = {
-      ...filters,
-      filters: { ...filters.filters, has_errors: true },
-    };
-    void handleFiltersChange(next);
+    updateClause(replaceClauseDimension(filters.filters.clause, "has_errors", hasErrorsClause(true)));
   }
 
   function addAttribute(raw: string) {
-    const list = [...(filters.filters.attribute_filters ?? []), raw];
-    const next = {
-      ...filters,
-      filters: { ...filters.filters, attribute_filters: list },
-    };
-    void handleFiltersChange(next);
+    const [key, ...rest] = raw.split("=");
+    const value = rest.join("=");
+    if (!key.trim() || !value.trim()) return;
+    updateClause(addToClause(filters.filters.clause, attrClause(key.trim(), value.trim())));
   }
 
   function addDuration(min?: number, max?: number) {
-    const next = {
-      ...filters,
-      filters: {
-        ...filters.filters,
-        ...(min !== undefined ? { duration_min_ms: min } : { duration_min_ms: undefined }),
-        ...(max !== undefined ? { duration_max_ms: max } : { duration_max_ms: undefined }),
-      },
-    };
-    void handleFiltersChange(next);
+    let clause = removeClauseDimension(filters.filters.clause, "duration");
+    if (min !== undefined) clause = addToClause(clause, durationMinClause(min));
+    if (max !== undefined) clause = addToClause(clause, durationMaxClause(max));
+    updateClause(clause);
   }
 
   function setService(service: string) {
-    const next = {
-      ...filters,
-      filters: { ...filters.filters, service_name: service },
-    };
-    void handleFiltersChange(next);
+    updateClause(replaceClauseDimension(filters.filters.clause, "service", serviceClause(service)));
   }
 
   function clearService() {
-    const nextFilters = { ...filters.filters };
-    delete nextFilters.service_name;
-    void handleFiltersChange({ ...filters, filters: nextFilters });
+    updateClause(removeClauseDimension(filters.filters.clause, "service"));
   }
 
   function setNamespace(namespace: string) {
-    const next = {
-      ...filters,
-      filters: { ...filters.filters, service_namespace: namespace },
-    };
-    void handleFiltersChange(next);
+    updateClause(
+      replaceClauseDimension(
+        filters.filters.clause,
+        "service_namespace",
+        serviceNamespaceClause(namespace),
+      ),
+    );
   }
 
   function clearNamespace() {
-    const nextFilters = { ...filters.filters };
-    delete nextFilters.service_namespace;
-    void handleFiltersChange({ ...filters, filters: nextFilters });
+    updateClause(removeClauseDimension(filters.filters.clause, "service_namespace"));
   }
 
   function setVersion(version: string) {
-    const next = {
-      ...filters,
-      filters: { ...filters.filters, service_version: version },
-    };
-    void handleFiltersChange(next);
+    updateClause(
+      replaceClauseDimension(
+        filters.filters.clause,
+        "service_version",
+        serviceVersionClause(version),
+      ),
+    );
   }
 
   function clearVersion() {
-    const nextFilters = { ...filters.filters };
-    delete nextFilters.service_version;
-    void handleFiltersChange({ ...filters, filters: nextFilters });
+    updateClause(removeClauseDimension(filters.filters.clause, "service_version"));
   }
 
   function setInstance(instanceId: string) {
-    const next = {
-      ...filters,
-      filters: { ...filters.filters, service_instance_id: instanceId },
-    };
-    void handleFiltersChange(next);
+    updateClause(
+      replaceClauseDimension(
+        filters.filters.clause,
+        "service_instance_id",
+        serviceInstanceIdClause(instanceId),
+      ),
+    );
   }
 
   function clearInstance() {
-    const nextFilters = { ...filters.filters };
-    delete nextFilters.service_instance_id;
-    void handleFiltersChange({ ...filters, filters: nextFilters });
+    updateClause(removeClauseDimension(filters.filters.clause, "service_instance_id"));
   }
 
   function setStatus(status: number) {
-    const next = {
-      ...filters,
-      filters: { ...filters.filters, status_code: status },
-    };
-    void handleFiltersChange(next);
+    updateClause(replaceClauseDimension(filters.filters.clause, "status_code", statusCodeClause(status)));
   }
 
   function clearStatus() {
-    const nextFilters = { ...filters.filters };
-    delete nextFilters.status_code;
-    void handleFiltersChange({ ...filters, filters: nextFilters });
+    updateClause(removeClauseDimension(filters.filters.clause, "status_code"));
   }
 
   function toggleErrors(enabled: boolean) {
-    const nextFilters = { ...filters.filters };
-    if (enabled) {
-      nextFilters.has_errors = true;
-    } else {
-      delete nextFilters.has_errors;
-    }
-    void handleFiltersChange({ ...filters, filters: nextFilters });
+    updateClause(
+      replaceClauseDimension(
+        filters.filters.clause,
+        "has_errors",
+        enabled ? hasErrorsClause(true) : undefined,
+      ),
+    );
   }
 
   function setDuration(next: { min?: number; max?: number }) {
+    let clause = removeClauseDimension(filters.filters.clause, "duration");
+    if (next.min !== undefined) clause = addToClause(clause, durationMinClause(next.min));
+    if (next.max !== undefined) clause = addToClause(clause, durationMaxClause(next.max));
+    updateClause(clause);
+  }
+
+  function setAttributes(list: string[]) {
+    let clause = removeClauseDimension(filters.filters.clause, "attr");
+    for (const raw of list) {
+      const [key, ...rest] = raw.split("=");
+      const value = rest.join("=");
+      if (key.trim() && value.trim()) {
+        clause = addToClause(clause, attrClause(key.trim(), value.trim()));
+      }
+    }
+    updateClause(clause);
+  }
+
+  function updateClause(clause: FilterClause | undefined) {
     void handleFiltersChange({
       ...filters,
       filters: {
         ...filters.filters,
-        duration_min_ms: next.min,
-        duration_max_ms: next.max,
+        clause,
       },
     });
   }
 
-  function setAttributes(list: string[]) {
-    const next = {
-      ...filters,
-      filters: { ...filters.filters, attribute_filters: list },
-    };
-    void handleFiltersChange(next);
-  }
-
   $effect(() => {
     const cleanup = () => {
       if (pollInterval !== null) {
diff --git a/crates/opsml_server/opsml_ui/src/lib/components/trace/TraceDashboard.test.ts b/crates/opsml_server/opsml_ui/src/lib/components/trace/TraceDashboard.test.ts
new file mode 100644
index 0000000000..6c66c9421a
--- /dev/null
+++ b/crates/opsml_server/opsml_ui/src/lib/components/trace/TraceDashboard.test.ts
@@ -0,0 +1,150 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { fireEvent, render, screen, waitFor } from "@testing-library/svelte";
+import TraceDashboard from "./TraceDashboard.svelte";
+import { andClause, serviceClause, statusCodeClause } from "./clause";
+import type { TracePageFilter } from "./types";
+
+const traceCalls = vi.hoisted(() => ({
+  metrics: [] as unknown[],
+  pages: [] as unknown[],
+  facets: [] as unknown[],
+}));
+
+vi.mock("$app/navigation", () => ({
+  replaceState: vi.fn(),
+}));
+
+vi.mock("$app/paths", () => ({
+  resolve: (path: string) => path,
+}));
+
+vi.mock("chart.js/auto", () => ({
+  Chart: class {
+    static register = vi.fn();
+    destroy = vi.fn();
+    resetZoom = vi.fn();
+  },
+}));
+vi.mock("chart.js", () => ({ Filler: {} }));
+vi.mock("chartjs-plugin-zoom", () => ({ default: {} }));
+vi.mock("chartjs-plugin-annotation", () => ({ default: {} }));
+vi.mock("chartjs-adapter-date-fns", () => ({}));
+
+vi.mock("./utils", async () => {
+  const actual = await vi.importActual<typeof import("./utils")>("./utils");
+  return {
+    ...actual,
+    setCookie: vi.fn(),
+    getServerTraceMetrics: vi.fn(async (_fetch, body) => {
+      traceCalls.metrics.push(body);
+      return { metrics: [] };
+    }),
+    getServerTracePage: vi.fn(async (_fetch, body) => {
+      traceCalls.pages.push(body);
+      return {
+        items: [],
+        has_next: false,
+        has_previous: false,
+      };
+    }),
+    getServerTraceFacets: vi.fn(async (_fetch, body) => {
+      traceCalls.facets.push(body);
+      return {
+        services: [{ value: "payments", trace_count: 2 }],
+        status_codes: [{ value: "500", trace_count: 1 }],
+        total_count: 2,
+      };
+    }),
+  };
+});
+
+/** Builds the initial trace filter state used by the dashboard regression. */
+function initialFilters(): TracePageFilter {
+  return {
+    bucket_interval: "1 hours",
+    selected_range: "custom",
+    filters: {
+      clause: andClause(serviceClause("checkout"), statusCodeClause(500)),
+      start_time: "2026-01-01T00:00:00Z",
+      end_time: "2026-01-02T00:00:00Z",
+    },
+  };
+}
+
+describe("TraceDashboard filter requests", () => {
+  beforeEach(() => {
+    Object.defineProperty(window, "matchMedia", {
+      writable: true,
+      value: vi.fn().mockImplementation((query: string) => ({
+        matches: false,
+        media: query,
+        onchange: null,
+        addEventListener: vi.fn(),
+        removeEventListener: vi.fn(),
+        addListener: vi.fn(),
+        removeListener: vi.fn(),
+        dispatchEvent: vi.fn(),
+      })),
+    });
+    Object.defineProperty(HTMLCanvasElement.prototype, "getContext", {
+      writable: true,
+      value: vi.fn(() => ({})),
+    });
+    Object.defineProperty(window, "ResizeObserver", {
+      writable: true,
+      value: class {
+        observe = vi.fn();
+        unobserve = vi.fn();
+        disconnect = vi.fn();
+      },
+    });
+    traceCalls.metrics.length = 0;
+    traceCalls.pages.length = 0;
+    traceCalls.facets.length = 0;
+  });
+
+  it("posts clause-shaped bodies for facet selection and chip removal", async () => {
+    render(TraceDashboard, {
+      props: {
+        trace_page: { items: [], has_next: false, has_previous: false },
+        trace_metrics: [],
+        trace_facets: {
+          services: [
+            { value: "checkout", trace_count: 1 },
+            { value: "payments", trace_count: 2 },
+          ],
+          status_codes: [{ value: "500", trace_count: 1 }],
+          total_count: 2,
+        },
+        initialFilters: initialFilters(),
+      },
+    });
+
+    await fireEvent.click(screen.getByText("payments"));
+
+    await waitFor(() => expect(traceCalls.metrics).toHaveLength(1));
+    expect(traceCalls.metrics[0]).toMatchObject({
+      start_time: "2026-01-01T00:00:00Z",
+      end_time: "2026-01-02T00:00:00Z",
+      clause: andClause(serviceClause("payments"), statusCodeClause(500)),
+    });
+    expect(traceCalls.metrics[0]).not.toHaveProperty("service_name");
+    expect(traceCalls.pages[0]).toMatchObject({
+      limit: 50,
+      clause: andClause(serviceClause("payments"), statusCodeClause(500)),
+    });
+    expect(traceCalls.facets[0]).toMatchObject({
+      clause: statusCodeClause(500),
+    });
+    expect(traceCalls.facets[1]).toMatchObject({
+      clause: serviceClause("payments"),
+    });
+
+    await fireEvent.click(screen.getByRole("button", { name: "Remove Service: payments" }));
+
+    await waitFor(() => expect(traceCalls.metrics).toHaveLength(2));
+    expect(traceCalls.metrics[1]).toMatchObject({
+      clause: statusCodeClause(500),
+    });
+  });
+});
diff --git a/crates/opsml_server/opsml_ui/src/lib/components/trace/TraceTable.svelte b/crates/opsml_server/opsml_ui/src/lib/components/trace/TraceTable.svelte
index 1010639e2b..003869f065 100644
--- a/crates/opsml_server/opsml_ui/src/lib/components/trace/TraceTable.svelte
+++ b/crates/opsml_server/opsml_ui/src/lib/components/trace/TraceTable.svelte
@@ -1,4 +1,6 @@
 <script lang="ts">
+  import { replaceState } from "$app/navigation";
+  import { resolve } from "$app/paths";
   import TraceDetailSidebar from "./TraceDetailSidebar.svelte";
   import TraceInfiniteScroll from "./TraceInfiniteScroll.svelte";
   import { getServerTraceSpans, getServerGenAiTraceMetrics, buildGenAiBySpanId } from "./utils";
@@ -80,7 +82,7 @@
     const url = new URL(window.location.href);
     if (url.searchParams.has("trace_id")) {
       url.searchParams.delete("trace_id");
-      history.replaceState(history.state, "", url.pathname + url.search);
+      replaceState(resolve((url.pathname + url.search) as `/opsml/${string}`), history.state);
     }
   }
 
diff --git a/crates/opsml_server/opsml_ui/src/lib/components/trace/TraceWaterfall.svelte b/crates/opsml_server/opsml_ui/src/lib/components/trace/TraceWaterfall.svelte
index ba38789a40..86f9969e4f 100644
--- a/crates/opsml_server/opsml_ui/src/lib/components/trace/TraceWaterfall.svelte
+++ b/crates/opsml_server/opsml_ui/src/lib/components/trace/TraceWaterfall.svelte
@@ -1,7 +1,9 @@
 <script lang="ts">
   import type { TraceSpan } from './types';
   import { formatDuration, hasSpanError } from './utils';
+  import { prepareWaterfallSpans } from './waterfall';
   import { CircleX, Clock, ChevronRight } from 'lucide-svelte';
+  import { SvelteMap, SvelteSet } from 'svelte/reactivity';
 
   // Scroll-sync refs
   let spanScrollContainer: HTMLDivElement;
@@ -82,7 +84,7 @@
   // ─── Tree helpers ────────────────────────────────────────────────────────
 
   function buildParentChildMap(allSpans: TraceSpan[]): Map<string, TraceSpan[]> {
-    const map = new Map<string, TraceSpan[]>();
+    const map = new SvelteMap<string, TraceSpan[]>();
     for (const span of allSpans) {
       if (span.parent_span_id) {
         const existing = map.get(span.parent_span_id) || [];
@@ -131,32 +133,7 @@
     return false;
   }
 
-  function sortSpansDepthFirst(spans: TraceSpan[]): TraceSpan[] {
-    const childrenMap = new Map<string | null, TraceSpan[]>();
-    for (const span of spans) {
-      const parentId = span.parent_span_id || null;
-      if (!childrenMap.has(parentId)) childrenMap.set(parentId, []);
-      childrenMap.get(parentId)!.push(span);
-    }
-    for (const siblings of childrenMap.values()) {
-      siblings.sort((a, b) => {
-        const tA = new Date(a.start_time).getTime();
-        const tB = new Date(b.start_time).getTime();
-        return tA !== tB ? tA - tB : a.span_order - b.span_order;
-      });
-    }
-    const result: TraceSpan[] = [];
-    function traverse(parentId: string | null) {
-      for (const child of childrenMap.get(parentId) || []) {
-        result.push(child);
-        traverse(child.span_id);
-      }
-    }
-    traverse(null);
-    return result;
-  }
-
-  const sortedSpans = $derived(sortSpansDepthFirst(spans));
+  const sortedSpans = $derived(prepareWaterfallSpans(spans));
   const parentChildMap = $derived(buildParentChildMap(sortedSpans));
 
   // ─── Collapsible spans ─────────────────────────────────────────────────
@@ -170,7 +147,7 @@
   const effectiveCollapsed = $derived(collapsedSpans ?? initialCollapsed);
 
   function toggleCollapse(spanId: string) {
-    const next = new Set(effectiveCollapsed);
+    const next = new SvelteSet(effectiveCollapsed);
     if (next.has(spanId)) next.delete(spanId); else next.add(spanId);
     collapsedSpans = next;
   }
@@ -217,6 +194,10 @@
   function onTimelineMouseLeave() {
     hoverX = null;
   }
+
+  function depthLevels(depth: number): number[] {
+    return Array.from({ length: depth }, (_value, index) => index);
+  }
 </script>
 
 <div class="flex flex-col h-full bg-surface-50 text-sm overflow-hidden">
@@ -232,7 +213,7 @@
 
       <!-- Timeline axis -->
       <div class="flex-1 relative flex items-end px-0 pb-1.5 overflow-hidden">
-        {#each AXIS_MARKS as mark, i}
+        {#each AXIS_MARKS as mark, i (mark)}
           {@const pct = mark * 100}
           <div
             class="absolute bottom-0 flex flex-col items-center pointer-events-none"
@@ -286,7 +267,7 @@
         >
           <!-- Tree connector lines -->
           {#if span.depth > 0}
-            {#each Array.from({ length: span.depth }) as _, depthIndex}
+            {#each depthLevels(span.depth) as depthIndex (depthIndex)}
               {@const shouldDrawLine = shouldDrawVerticalLine(span, depthIndex, visibleSpans, parentChildMap)}
               {@const isCurrentLevel = depthIndex === span.depth - 1}
               {@const lineLeft = depthIndex * INDENT_PX + 8}
@@ -358,7 +339,7 @@
       class="flex-1 overflow-y-auto overflow-x-hidden relative bg-surface-50"
     >
       <!-- Vertical tick grid lines behind rows -->
-      {#each AXIS_MARKS.slice(1) as mark}
+      {#each AXIS_MARKS.slice(1) as mark (mark)}
         <div
           class="absolute top-0 bottom-0 w-px bg-black/6 pointer-events-none z-0"
           style="left: {mark * 100}%;"
diff --git a/crates/opsml_server/opsml_ui/src/lib/components/trace/__tests__/mockData.test.ts b/crates/opsml_server/opsml_ui/src/lib/components/trace/__tests__/mockData.test.ts
new file mode 100644
index 0000000000..f51f9ecc6f
--- /dev/null
+++ b/crates/opsml_server/opsml_ui/src/lib/components/trace/__tests__/mockData.test.ts
@@ -0,0 +1,84 @@
+import { describe, expect, it } from "vitest";
+import {
+  andClause,
+  attrClause,
+  durationMaxClause,
+  durationMinClause,
+  hasErrorsClause,
+  notClause,
+  orClause,
+  serviceClause,
+  serviceNamespaceClause,
+  statusCodeClause,
+} from "../clause";
+import { getMockTracePage } from "../mockData";
+
+describe("trace mock FilterClause evaluation", () => {
+  it("filters by AND of service and status code", () => {
+    const page = getMockTracePage({
+      clause: andClause(serviceClause("inference-api"), statusCodeClause(2)),
+      limit: 100,
+    });
+    expect(page.items.length).toBeGreaterThan(0);
+    expect(page.items.every((item) => item.service_name === "inference-api" && item.status_code === 2)).toBe(true);
+  });
+
+  it("filters by OR of two services", () => {
+    const page = getMockTracePage({
+      clause: orClause(serviceClause("inference-api"), serviceClause("llm-gateway")),
+      limit: 100,
+    });
+    expect(page.items.length).toBeGreaterThan(0);
+    expect(page.items.every((item) => ["inference-api", "llm-gateway"].includes(item.service_name))).toBe(true);
+  });
+
+  it("filters by NOT has_errors", () => {
+    const page = getMockTracePage({
+      clause: notClause(hasErrorsClause(true)),
+      limit: 100,
+    });
+    expect(page.items.length).toBeGreaterThan(0);
+    expect(page.items.every((item) => item.has_errors === false)).toBe(true);
+  });
+
+  it("matches service namespace through resource attributes", () => {
+    const matched = getMockTracePage({
+      clause: serviceNamespaceClause("models"),
+      limit: 100,
+    });
+    const missing = getMockTracePage({
+      clause: serviceNamespaceClause("missing"),
+      limit: 100,
+    });
+    expect(matched.items.length).toBeGreaterThan(0);
+    expect(missing.items).toHaveLength(0);
+  });
+
+  it("matches arbitrary resource attributes", () => {
+    const page = getMockTracePage({
+      clause: attrClause("service.version", "1.0.0"),
+      limit: 100,
+    });
+    expect(page.items.length).toBeGreaterThan(0);
+    expect(page.items.every((item) => item.service_name === "llm-gateway")).toBe(true);
+  });
+
+  it("bounds duration with min and max clauses", () => {
+    const page = getMockTracePage({
+      clause: andClause(durationMinClause(300), durationMaxClause(1000)),
+      limit: 100,
+    });
+    expect(page.items.length).toBeGreaterThan(0);
+    expect(page.items.every((item) => (item.duration_ms ?? 0) >= 300 && (item.duration_ms ?? 0) <= 1000)).toBe(true);
+  });
+
+  it("returns all items when no clause is present", () => {
+    const withoutClause = getMockTracePage({ limit: 100 });
+    const withImpossibleClause = getMockTracePage({
+      clause: serviceClause("does-not-exist"),
+      limit: 100,
+    });
+    expect(withoutClause.items.length).toBeGreaterThan(withImpossibleClause.items.length);
+    expect(withImpossibleClause.items).toHaveLength(0);
+  });
+});
diff --git a/crates/opsml_server/opsml_ui/src/lib/components/trace/clause.test.ts b/crates/opsml_server/opsml_ui/src/lib/components/trace/clause.test.ts
new file mode 100644
index 0000000000..5247f82539
--- /dev/null
+++ b/crates/opsml_server/opsml_ui/src/lib/components/trace/clause.test.ts
@@ -0,0 +1,185 @@
+import { describe, expect, it } from "vitest";
+import {
+  addToClause,
+  andClause,
+  attrClause,
+  clauseToActiveFilters,
+  durationMaxClause,
+  durationMinClause,
+  findClauses,
+  hasDimension,
+  hasErrorsClause,
+  notClause,
+  orClause,
+  phraseClause,
+  removeAttr,
+  removeClauseDimension,
+  replaceClauseDimension,
+  serviceClause,
+  serviceInstanceIdClause,
+  serviceNamespaceClause,
+  serviceVersionClause,
+  statusCodeClause,
+} from "./clause";
+
+describe("FilterClause builders and combinators", () => {
+  it("builds leaf clauses", () => {
+    expect(serviceClause("checkout")).toEqual({ op: "service", value: "checkout" });
+    expect(serviceNamespaceClause("prod")).toEqual({ op: "service_namespace", value: "prod" });
+    expect(serviceVersionClause("1.2.3")).toEqual({ op: "service_version", value: "1.2.3" });
+    expect(serviceInstanceIdClause("pod-a")).toEqual({ op: "service_instance_id", value: "pod-a" });
+    expect(statusCodeClause(500)).toEqual({ op: "status_code", value: 500 });
+    expect(hasErrorsClause(true)).toEqual({ op: "has_errors", value: true });
+    expect(durationMinClause(100)).toEqual({ op: "duration_min_ms", value: 100 });
+    expect(durationMaxClause(500)).toEqual({ op: "duration_max_ms", value: 500 });
+    expect(attrClause("env", "prod")).toEqual({ op: "attr", value: { key: "env", value: "prod" } });
+    expect(phraseClause("timeout")).toEqual({ op: "phrase", value: "timeout" });
+  });
+
+  it("handles empty and single-child AND clauses", () => {
+    const service = serviceClause("checkout");
+    expect(andClause()).toBeUndefined();
+    expect(andClause(service)).toEqual(service);
+  });
+
+  it("builds and flattens AND clauses", () => {
+    const a = serviceClause("checkout");
+    const b = statusCodeClause(500);
+    const c = hasErrorsClause(true);
+    expect(andClause(a, b)).toEqual({ op: "and", value: [a, b] });
+    expect(andClause(andClause(a, b), c)).toEqual({ op: "and", value: [a, b, c] });
+  });
+
+  it("handles empty and single-child OR clauses", () => {
+    const service = serviceClause("checkout");
+    expect(orClause()).toBeUndefined();
+    expect(orClause(service)).toEqual(service);
+  });
+
+  it("builds and flattens OR clauses", () => {
+    const a = serviceClause("checkout");
+    const b = serviceClause("payments");
+    const c = serviceClause("catalog");
+    expect(orClause(a, b)).toEqual({ op: "or", value: [a, b] });
+    expect(orClause(orClause(a, b), c)).toEqual({ op: "or", value: [a, b, c] });
+  });
+
+  it("builds explicit NOT clauses without simplification", () => {
+    const service = serviceClause("checkout");
+    expect(notClause(service)).toEqual({ op: "not", value: service });
+    expect(notClause(notClause(service))).toEqual({
+      op: "not",
+      value: { op: "not", value: service },
+    });
+  });
+});
+
+describe("FilterClause mutators", () => {
+  it("adds a clause to an empty tree", () => {
+    expect(addToClause(undefined, serviceClause("checkout"))).toEqual(serviceClause("checkout"));
+  });
+
+  it("adds a clause by flattening with AND", () => {
+    const service = serviceClause("checkout");
+    const status = statusCodeClause(500);
+    const errors = hasErrorsClause(true);
+    expect(addToClause(andClause(service, status), errors)).toEqual({
+      op: "and",
+      value: [service, status, errors],
+    });
+  });
+
+  it("removes one dimension and unwraps the remaining child", () => {
+    expect(removeClauseDimension(andClause(serviceClause("a"), statusCodeClause(500)), "service")).toEqual(
+      statusCodeClause(500),
+    );
+  });
+
+  it("collapses when every matching dimension disappears", () => {
+    expect(removeClauseDimension(andClause(serviceClause("a"), serviceClause("b")), "service")).toBeUndefined();
+  });
+
+  it("removes duration min and max together", () => {
+    expect(
+      removeClauseDimension(
+        andClause(durationMinClause(100), durationMaxClause(500), statusCodeClause(500)),
+        "duration",
+      ),
+    ).toEqual(statusCodeClause(500));
+  });
+
+  it("collapses NOT when the inner leaf is removed", () => {
+    expect(removeClauseDimension(notClause(serviceClause("a")), "service")).toBeUndefined();
+  });
+
+  it("removes one matching attribute leaf", () => {
+    expect(removeAttr(andClause(attrClause("env", "prod"), attrClause("region", "us")), "env", "prod")).toEqual(
+      attrClause("region", "us"),
+    );
+  });
+
+  it("replaces an absent dimension by adding it", () => {
+    expect(replaceClauseDimension(undefined, "service", serviceClause("b"))).toEqual(serviceClause("b"));
+  });
+
+  it("replaces an existing dimension in place", () => {
+    expect(
+      replaceClauseDimension(andClause(serviceClause("a"), statusCodeClause(500)), "service", serviceClause("b")),
+    ).toEqual(andClause(serviceClause("b"), statusCodeClause(500)));
+  });
+
+  it("finds clauses and dimensions anywhere in the tree", () => {
+    const clause = andClause(notClause(serviceClause("a")), durationMinClause(100));
+    expect(findClauses(clause, "service")).toEqual([serviceClause("a")]);
+    expect(hasDimension(clause, "duration")).toBe(true);
+    expect(hasDimension(clause, "status_code")).toBe(false);
+  });
+
+  it("removes phrase leaves by dimension", () => {
+    expect(removeClauseDimension(andClause(phraseClause("timeout"), serviceClause("a")), "phrase")).toEqual(
+      serviceClause("a"),
+    );
+  });
+});
+
+describe("FilterClause projection", () => {
+  it("returns no chips for an empty clause", () => {
+    expect(clauseToActiveFilters(undefined)).toEqual([]);
+  });
+
+  it("projects a single leaf", () => {
+    expect(clauseToActiveFilters(serviceClause("checkout")).map((chip) => chip.label)).toEqual([
+      "Service: checkout",
+    ]);
+  });
+
+  it("projects AND leaves in document order", () => {
+    const labels = clauseToActiveFilters(
+      andClause(serviceClause("checkout"), statusCodeClause(500), attrClause("env", "prod")),
+    ).map((chip) => chip.label);
+    expect(labels).toEqual(["Service: checkout", "Status: 500", "Attr: env=prod"]);
+  });
+
+  it("removes only the selected attr chip through its closure", () => {
+    const clause = andClause(attrClause("env", "prod"), attrClause("region", "us"));
+    const chips = clauseToActiveFilters(clause);
+    expect(chips[0].remove(clause)).toEqual(attrClause("region", "us"));
+  });
+
+  it("removes every service leaf through a service chip closure", () => {
+    const clause = andClause(serviceClause("a"), serviceClause("b"), statusCodeClause(500));
+    const chips = clauseToActiveFilters(clause);
+    expect(chips[0].remove(clause)).toEqual(statusCodeClause(500));
+  });
+
+  it("gives every chip a unique id", () => {
+    const chips = clauseToActiveFilters(andClause(serviceClause("a"), serviceClause("a"), statusCodeClause(500)));
+    expect(new Set(chips.map((chip) => chip.id)).size).toBe(chips.length);
+  });
+
+  it("projects phrase chips", () => {
+    expect(clauseToActiveFilters(phraseClause("timeout")).map((chip) => chip.label)).toEqual([
+      "Phrase: timeout",
+    ]);
+  });
+});
diff --git a/crates/opsml_server/opsml_ui/src/lib/components/trace/clause.ts b/crates/opsml_server/opsml_ui/src/lib/components/trace/clause.ts
new file mode 100644
index 0000000000..0fde221ca4
--- /dev/null
+++ b/crates/opsml_server/opsml_ui/src/lib/components/trace/clause.ts
@@ -0,0 +1,369 @@
+export type FilterClause =
+  | { op: "and"; value: FilterClause[] }
+  | { op: "or"; value: FilterClause[] }
+  | { op: "not"; value: FilterClause }
+  | { op: "phrase"; value: string }
+  | { op: "service"; value: string }
+  | { op: "service_namespace"; value: string }
+  | { op: "service_version"; value: string }
+  | { op: "service_instance_id"; value: string }
+  | { op: "status_code"; value: number }
+  | { op: "has_errors"; value: boolean }
+  | { op: "duration_min_ms"; value: number }
+  | { op: "duration_max_ms"; value: number }
+  | { op: "attr"; value: { key: string; value: string } };
+
+export type FilterClauseOp = FilterClause["op"];
+
+export type ClauseDimension =
+  | "service"
+  | "service_namespace"
+  | "service_version"
+  | "service_instance_id"
+  | "status_code"
+  | "has_errors"
+  | "duration_min_ms"
+  | "duration_max_ms"
+  | "duration"
+  | "attr"
+  | "phrase";
+
+export interface ActiveFilter {
+  id: string;
+  label: string;
+  remove: (clause: FilterClause | undefined) => FilterClause | undefined;
+}
+
+export const FACET_AXIS_TO_CLAUSE_OP = {
+  service_name: "service",
+  status_code: "status_code",
+} as const satisfies Record<string, FilterClauseOp>;
+
+export const serviceClause = (value: string): FilterClause => ({
+  op: "service",
+  value,
+});
+export const serviceNamespaceClause = (value: string): FilterClause => ({
+  op: "service_namespace",
+  value,
+});
+export const serviceVersionClause = (value: string): FilterClause => ({
+  op: "service_version",
+  value,
+});
+export const serviceInstanceIdClause = (value: string): FilterClause => ({
+  op: "service_instance_id",
+  value,
+});
+export const statusCodeClause = (value: number): FilterClause => ({
+  op: "status_code",
+  value,
+});
+export const hasErrorsClause = (value: boolean): FilterClause => ({
+  op: "has_errors",
+  value,
+});
+export const durationMinClause = (value: number): FilterClause => ({
+  op: "duration_min_ms",
+  value,
+});
+export const durationMaxClause = (value: number): FilterClause => ({
+  op: "duration_max_ms",
+  value,
+});
+export const attrClause = (key: string, value: string): FilterClause => ({
+  op: "attr",
+  value: { key, value },
+});
+export const phraseClause = (value: string): FilterClause => ({
+  op: "phrase",
+  value,
+});
+
+export function andClause(
+  ...children: (FilterClause | undefined)[]
+): FilterClause | undefined {
+  return combineClause("and", children);
+}
+
+export function orClause(
+  ...children: (FilterClause | undefined)[]
+): FilterClause | undefined {
+  return combineClause("or", children);
+}
+
+export function notClause(value: FilterClause): FilterClause {
+  return { op: "not", value };
+}
+
+export function* iterateLeaves(
+  clause: FilterClause | undefined,
+): Iterable<FilterClause> {
+  if (!clause) return;
+  switch (clause.op) {
+    case "and":
+    case "or":
+      for (const child of clause.value) {
+        yield* iterateLeaves(child);
+      }
+      return;
+    case "not":
+      yield* iterateLeaves(clause.value);
+      return;
+    default:
+      yield clause;
+  }
+}
+
+export function findClauses<Op extends FilterClauseOp>(
+  clause: FilterClause | undefined,
+  op: Op,
+): Extract<FilterClause, { op: Op }>[] {
+  return Array.from(iterateLeaves(clause)).filter(
+    (leaf): leaf is Extract<FilterClause, { op: Op }> => leaf.op === op,
+  );
+}
+
+export function hasDimension(
+  clause: FilterClause | undefined,
+  dim: ClauseDimension,
+): boolean {
+  for (const leaf of iterateLeaves(clause)) {
+    if (matchesDimension(leaf, dim)) return true;
+  }
+  return false;
+}
+
+export function addToClause(
+  existing: FilterClause | undefined,
+  added: FilterClause,
+): FilterClause {
+  return andClause(existing, added) ?? added;
+}
+
+export function removeClauseDimension(
+  clause: FilterClause | undefined,
+  dim: ClauseDimension,
+): FilterClause | undefined {
+  if (!clause) return undefined;
+
+  switch (clause.op) {
+    case "and":
+    case "or": {
+      const children = clause.value
+        .map((child) => removeClauseDimension(child, dim))
+        .filter((child): child is FilterClause => child !== undefined);
+      return combineClause(clause.op, children);
+    }
+    case "not": {
+      const inner = removeClauseDimension(clause.value, dim);
+      return inner ? { op: "not", value: inner } : undefined;
+    }
+    default:
+      return matchesDimension(clause, dim) ? undefined : cloneClause(clause);
+  }
+}
+
+export function replaceClauseDimension(
+  clause: FilterClause | undefined,
+  dim: ClauseDimension,
+  next: FilterClause | undefined,
+): FilterClause | undefined {
+  if (!next) return removeClauseDimension(clause, dim);
+
+  const [replaced, found] = replaceDimensionInner(clause, dim, next);
+  if (found) return replaced;
+  return addToClause(replaced, next);
+}
+
+export function removeAttr(
+  clause: FilterClause | undefined,
+  key: string,
+  value: string,
+): FilterClause | undefined {
+  if (!clause) return undefined;
+
+  switch (clause.op) {
+    case "and":
+    case "or": {
+      const children = clause.value
+        .map((child) => removeAttr(child, key, value))
+        .filter((child): child is FilterClause => child !== undefined);
+      return combineClause(clause.op, children);
+    }
+    case "not": {
+      const inner = removeAttr(clause.value, key, value);
+      return inner ? { op: "not", value: inner } : undefined;
+    }
+    case "attr":
+      return clause.value.key === key && clause.value.value === value
+        ? undefined
+        : cloneClause(clause);
+    default:
+      return cloneClause(clause);
+  }
+}
+
+export function clauseToActiveFilters(
+  clause: FilterClause | undefined,
+): ActiveFilter[] {
+  return Array.from(iterateLeaves(clause)).map((leaf, index) => ({
+    id: `${index}:${leaf.op}:${leafLabelValue(leaf)}`,
+    label: labelForLeaf(leaf),
+    remove: removeForLeaf(leaf),
+  }));
+}
+
+function combineClause(
+  op: "and" | "or",
+  children: (FilterClause | undefined)[],
+): FilterClause | undefined {
+  const flattened: FilterClause[] = [];
+  for (const child of children) {
+    if (!child) continue;
+    if (child.op === op) flattened.push(...child.value.map(cloneClause));
+    else flattened.push(cloneClause(child));
+  }
+  if (flattened.length === 0) return undefined;
+  if (flattened.length === 1) return flattened[0];
+  return { op, value: flattened };
+}
+
+function replaceDimensionInner(
+  clause: FilterClause | undefined,
+  dim: ClauseDimension,
+  next: FilterClause,
+): [FilterClause | undefined, boolean] {
+  if (!clause) return [undefined, false];
+
+  switch (clause.op) {
+    case "and":
+    case "or": {
+      let found = false;
+      let inserted = false;
+      const children: FilterClause[] = [];
+      for (const child of clause.value) {
+        const [updated, childFound] = replaceDimensionInner(child, dim, next);
+        found ||= childFound;
+        if (childFound && !inserted) {
+          children.push(cloneClause(next));
+          inserted = true;
+        }
+        if (updated) children.push(updated);
+      }
+      return [combineClause(clause.op, children), found];
+    }
+    case "not": {
+      const [inner, found] = replaceDimensionInner(clause.value, dim, next);
+      return [inner ? { op: "not", value: inner } : undefined, found];
+    }
+    default:
+      return matchesDimension(clause, dim)
+        ? [undefined, true]
+        : [cloneClause(clause), false];
+  }
+}
+
+function matchesDimension(clause: FilterClause, dim: ClauseDimension): boolean {
+  if (dim === "duration") {
+    return clause.op === "duration_min_ms" || clause.op === "duration_max_ms";
+  }
+  return clause.op === dim;
+}
+
+function labelForLeaf(clause: FilterClause): string {
+  switch (clause.op) {
+    case "service":
+      return `Service: ${clause.value}`;
+    case "service_namespace":
+      return `Namespace: ${clause.value}`;
+    case "service_version":
+      return `Version: ${clause.value}`;
+    case "service_instance_id":
+      return `Instance: ${clause.value}`;
+    case "status_code":
+      return `Status: ${clause.value}`;
+    case "has_errors":
+      return `Has errors: ${clause.value}`;
+    case "duration_min_ms":
+      return `Min duration: ${clause.value}ms`;
+    case "duration_max_ms":
+      return `Max duration: ${clause.value}ms`;
+    case "attr":
+      return `Attr: ${clause.value.key}=${clause.value.value}`;
+    case "phrase":
+      return `Phrase: ${clause.value}`;
+    case "and":
+    case "or":
+    case "not":
+      throw new Error(`Cannot label non-leaf clause ${clause.op}`);
+  }
+}
+
+function leafLabelValue(clause: FilterClause): string {
+  return clause.op === "attr"
+    ? `${clause.value.key}=${clause.value.value}`
+    : String(clause.value);
+}
+
+function removeForLeaf(
+  clause: FilterClause,
+): (clause: FilterClause | undefined) => FilterClause | undefined {
+  if (clause.op === "attr") {
+    const { key, value } = clause.value;
+    return (current) => removeAttr(current, key, value);
+  }
+  const dim = dimensionForLeaf(clause);
+  return (current) => removeClauseDimension(current, dim);
+}
+
+/**
+ * Clones a clause without `structuredClone`.
+ *
+ * Clause objects can be wrapped in Svelte proxies when they come from component
+ * state. `structuredClone` rejects those proxies, so the discriminated union is
+ * copied manually before returning data to mutators.
+ */
+function cloneClause(clause: FilterClause): FilterClause {
+  switch (clause.op) {
+    case "and":
+    case "or":
+      return { op: clause.op, value: clause.value.map(cloneClause) };
+    case "not":
+      return { op: "not", value: cloneClause(clause.value) };
+    case "attr":
+      return { op: "attr", value: { key: clause.value.key, value: clause.value.value } };
+    case "phrase":
+    case "service":
+    case "service_namespace":
+    case "service_version":
+    case "service_instance_id":
+      return { op: clause.op, value: clause.value };
+    case "status_code":
+    case "duration_min_ms":
+    case "duration_max_ms":
+      return { op: clause.op, value: clause.value };
+    case "has_errors":
+      return { op: "has_errors", value: clause.value };
+  }
+}
+
+function dimensionForLeaf(clause: FilterClause): ClauseDimension {
+  switch (clause.op) {
+    case "service":
+    case "service_namespace":
+    case "service_version":
+    case "service_instance_id":
+    case "status_code":
+    case "has_errors":
+    case "duration_min_ms":
+    case "duration_max_ms":
+    case "attr":
+    case "phrase":
+      return clause.op;
+    case "and":
+    case "or":
+    case "not":
+      throw new Error(`Cannot derive a filter dimension from ${clause.op}`);
+  }
+}
diff --git a/crates/opsml_server/opsml_ui/src/lib/components/trace/clauseEvaluator.ts b/crates/opsml_server/opsml_ui/src/lib/components/trace/clauseEvaluator.ts
new file mode 100644
index 0000000000..6453dc5f5e
--- /dev/null
+++ b/crates/opsml_server/opsml_ui/src/lib/components/trace/clauseEvaluator.ts
@@ -0,0 +1,46 @@
+import type { FilterClause } from "./clause";
+import type { Attribute, TraceListItem } from "./types";
+
+export function resourceAttr(
+  attrs: Attribute[] | undefined,
+  key: string,
+): string | undefined {
+  const hit = attrs?.find((attr) => attr.key === key);
+  return hit === undefined ? undefined : String(hit.value);
+}
+
+export function evaluateClause(
+  item: TraceListItem,
+  clause: FilterClause,
+): boolean {
+  switch (clause.op) {
+    case "and":
+      return clause.value.every((child) => evaluateClause(item, child));
+    case "or":
+      return clause.value.some((child) => evaluateClause(item, child));
+    case "not":
+      return !evaluateClause(item, clause.value);
+    case "service":
+      return item.service_name === clause.value;
+    case "service_namespace":
+      return resourceAttr(item.resource_attributes, "service.namespace") === clause.value;
+    case "service_version":
+      return resourceAttr(item.resource_attributes, "service.version") === clause.value;
+    case "service_instance_id":
+      return resourceAttr(item.resource_attributes, "service.instance.id") === clause.value;
+    case "status_code":
+      return item.status_code === clause.value;
+    case "has_errors":
+      return item.has_errors === clause.value;
+    case "duration_min_ms":
+      return (item.duration_ms ?? 0) >= clause.value;
+    case "duration_max_ms":
+      return (item.duration_ms ?? Number.POSITIVE_INFINITY) <= clause.value;
+    case "attr":
+      return resourceAttr(item.resource_attributes, clause.value.key) === clause.value.value;
+    case "phrase": {
+      const haystack = `${item.root_operation} ${item.service_name}`.toLowerCase();
+      return haystack.includes(clause.value.toLowerCase());
+    }
+  }
+}
diff --git a/crates/opsml_server/opsml_ui/src/lib/components/trace/filters/ChipBar.svelte b/crates/opsml_server/opsml_ui/src/lib/components/trace/filters/ChipBar.svelte
index 97382081d2..2b758a6722 100644
--- a/crates/opsml_server/opsml_ui/src/lib/components/trace/filters/ChipBar.svelte
+++ b/crates/opsml_server/opsml_ui/src/lib/components/trace/filters/ChipBar.svelte
@@ -1,6 +1,7 @@
 <script lang="ts">
   import { Plus, X } from "lucide-svelte";
-  import type { ActiveFilter, FacetCount } from "../types";
+  import type { FacetCount } from "../types";
+  import type { ActiveFilter } from "../clause";
   import AddFilterMenu from "./AddFilterMenu.svelte";
 
   let {
@@ -33,15 +34,14 @@
     <span class="text-xs font-mono text-gray-400">No filters · click + Add filter</span>
   {/if}
 
-  {#each chips as chip (`${chip.key}:${chip.value}`)}
+  {#each chips as chip (chip.id)}
     <span class="inline-flex items-center gap-1 px-2 py-0.5 text-xs font-bold border-2 border-black bg-white text-primary-800 rounded-base shadow-small">
-      <span class="text-primary-600 font-mono uppercase tracking-wide text-[10px]">{chip.label}:</span>
-      <span class="font-mono">{chip.value}</span>
+      <span class="font-mono">{chip.label}</span>
       <button
         type="button"
         onclick={() => onRemove(chip)}
         class="ml-1 p-0.5 rounded-base hover:bg-error-100 transition-colors duration-100"
-        aria-label={`Remove ${chip.label}:${chip.value}`}
+        aria-label={`Remove ${chip.label}`}
       >
         <X class="w-3 h-3" />
       </button>
diff --git a/crates/opsml_server/opsml_ui/src/lib/components/trace/filters/FacetSidebar.svelte b/crates/opsml_server/opsml_ui/src/lib/components/trace/filters/FacetSidebar.svelte
index 9c7e55f46f..249803b29b 100644
--- a/crates/opsml_server/opsml_ui/src/lib/components/trace/filters/FacetSidebar.svelte
+++ b/crates/opsml_server/opsml_ui/src/lib/components/trace/filters/FacetSidebar.svelte
@@ -1,9 +1,12 @@
 <script lang="ts">
+  // Scouter currently returns facet counts for services and status codes only.
+  // Namespace/version/instance/error/duration/attribute controls update the clause directly.
   import type { FacetCount, TracePageFilter } from "../types";
   import AttributeFacet from "./AttributeFacet.svelte";
   import DurationFacet from "./DurationFacet.svelte";
   import FacetRow from "./FacetRow.svelte";
   import FacetSection from "./FacetSection.svelte";
+  import { findClauses } from "../clause";
 
   let {
     filters,
@@ -47,14 +50,28 @@
     onSetAttributes: (next: string[]) => void;
   }>();
 
-  let namespaceInput = $state(filters.filters.service_namespace ?? "");
-  let versionInput = $state(filters.filters.service_version ?? "");
-  let instanceInput = $state(filters.filters.service_instance_id ?? "");
+  const selectedService = $derived(findClauses(filters.filters.clause, "service")[0]?.value);
+  const selectedStatusCode = $derived(findClauses(filters.filters.clause, "status_code")[0]?.value);
+  const selectedNamespace = $derived(findClauses(filters.filters.clause, "service_namespace")[0]?.value);
+  const selectedVersion = $derived(findClauses(filters.filters.clause, "service_version")[0]?.value);
+  const selectedInstance = $derived(findClauses(filters.filters.clause, "service_instance_id")[0]?.value);
+  const selectedHasErrors = $derived(findClauses(filters.filters.clause, "has_errors")[0]?.value);
+  const selectedMinDuration = $derived(findClauses(filters.filters.clause, "duration_min_ms")[0]?.value);
+  const selectedMaxDuration = $derived(findClauses(filters.filters.clause, "duration_max_ms")[0]?.value);
+  const selectedAttributes = $derived(
+    findClauses(filters.filters.clause, "attr").map(
+      (clause) => `${clause.value.key}=${clause.value.value}`,
+    ),
+  );
+
+  let namespaceInput = $state("");
+  let versionInput = $state("");
+  let instanceInput = $state("");
 
   $effect(() => {
-    namespaceInput = filters.filters.service_namespace ?? "";
-    versionInput = filters.filters.service_version ?? "";
-    instanceInput = filters.filters.service_instance_id ?? "";
+    namespaceInput = selectedNamespace ?? "";
+    versionInput = selectedVersion ?? "";
+    instanceInput = selectedInstance ?? "";
   });
 
   function applyNamespaceInput() {
@@ -84,14 +101,14 @@
   <FacetSection label="Status">
     <FacetRow
       label="Any"
-      selected={filters.filters.status_code === undefined}
+      selected={selectedStatusCode === undefined}
       onSelect={onClearStatus}
     />
     {#each statuses as s (s.value)}
       <FacetRow
         label={s.value}
         count={s.count}
-        selected={String(filters.filters.status_code) === s.value}
+        selected={String(selectedStatusCode) === s.value}
         onSelect={() => onSetStatus(Number(s.value))}
       />
     {/each}
@@ -100,14 +117,14 @@
   <FacetSection label="Service">
     <FacetRow
       label="Any"
-      selected={filters.filters.service_name === undefined}
+      selected={selectedService === undefined}
       onSelect={onClearService}
     />
     {#each services as service (service.value)}
       <FacetRow
         label={service.value}
         count={service.count}
-        selected={filters.filters.service_name === service.value}
+        selected={selectedService === service.value}
         onSelect={() => onSetService(service.value)}
       />
     {/each}
@@ -116,14 +133,14 @@
   <FacetSection label="Namespace">
     <FacetRow
       label="Any"
-      selected={filters.filters.service_namespace === undefined}
+      selected={selectedNamespace === undefined}
       onSelect={onClearNamespace}
     />
     {#each namespaces as namespace (namespace.value)}
       <FacetRow
         label={namespace.value}
         count={namespace.count}
-        selected={filters.filters.service_namespace === namespace.value}
+        selected={selectedNamespace === namespace.value}
         onSelect={() => onSetNamespace(namespace.value)}
       />
     {/each}
@@ -158,14 +175,14 @@
   <FacetSection label="Version">
     <FacetRow
       label="Any"
-      selected={filters.filters.service_version === undefined}
+      selected={selectedVersion === undefined}
       onSelect={onClearVersion}
     />
     {#each versions as version (version.value)}
       <FacetRow
         label={version.value}
         count={version.count}
-        selected={filters.filters.service_version === version.value}
+        selected={selectedVersion === version.value}
         onSelect={() => onSetVersion(version.value)}
       />
     {/each}
@@ -200,14 +217,14 @@
   <FacetSection label="Instance" defaultOpen={false}>
     <FacetRow
       label="Any"
-      selected={filters.filters.service_instance_id === undefined}
+      selected={selectedInstance === undefined}
       onSelect={onClearInstance}
     />
     {#each instances as instance (instance.value)}
       <FacetRow
         label={instance.value}
         count={instance.count}
-        selected={filters.filters.service_instance_id === instance.value}
+        selected={selectedInstance === instance.value}
         onSelect={() => onSetInstance(instance.value)}
       />
     {/each}
@@ -243,7 +260,7 @@
     <label class="flex items-center gap-2 text-xs text-primary-800 cursor-pointer">
       <input
         type="checkbox"
-        checked={filters.filters.has_errors === true}
+        checked={selectedHasErrors === true}
         onchange={(event) =>
           onToggleErrors((event.currentTarget as HTMLInputElement).checked)}
         class="w-4 h-4 border-2 border-black bg-surface-50 accent-primary-500"
@@ -254,15 +271,15 @@
 
   <FacetSection label="Duration" defaultOpen={false}>
     <DurationFacet
-      min={filters.filters.duration_min_ms}
-      max={filters.filters.duration_max_ms}
+      min={selectedMinDuration}
+      max={selectedMaxDuration}
       onApply={onSetDuration}
     />
   </FacetSection>
 
   <FacetSection label="Attributes" defaultOpen={false}>
     <AttributeFacet
-      items={filters.filters.attribute_filters ?? []}
+      items={selectedAttributes}
       onChange={onSetAttributes}
     />
   </FacetSection>
diff --git a/crates/opsml_server/opsml_ui/src/lib/components/trace/filters/FacetSidebar.test.ts b/crates/opsml_server/opsml_ui/src/lib/components/trace/filters/FacetSidebar.test.ts
new file mode 100644
index 0000000000..8faebd7a8c
--- /dev/null
+++ b/crates/opsml_server/opsml_ui/src/lib/components/trace/filters/FacetSidebar.test.ts
@@ -0,0 +1,62 @@
+import { fireEvent, render, screen } from "@testing-library/svelte";
+import { describe, expect, it, vi } from "vitest";
+import { andClause, serviceClause, statusCodeClause } from "../clause";
+import type { TracePageFilter } from "../types";
+import FacetSidebar from "./FacetSidebar.svelte";
+
+function renderSidebar(overrides: Partial<TracePageFilter["filters"]> = {}) {
+  const filters: TracePageFilter = {
+    bucket_interval: "1 minutes",
+    selected_range: "15min",
+    filters: {
+      clause: andClause(serviceClause("checkout"), statusCodeClause(500)),
+      ...overrides,
+    },
+  };
+  const props = {
+    filters,
+    services: [
+      { value: "checkout", count: 3 },
+      { value: "payments", count: 2 },
+    ],
+    namespaces: [],
+    versions: [],
+    instances: [],
+    statuses: [{ value: "500", count: 3 }],
+    onSetService: vi.fn(),
+    onClearService: vi.fn(),
+    onSetNamespace: vi.fn(),
+    onClearNamespace: vi.fn(),
+    onSetVersion: vi.fn(),
+    onClearVersion: vi.fn(),
+    onSetInstance: vi.fn(),
+    onClearInstance: vi.fn(),
+    onSetStatus: vi.fn(),
+    onClearStatus: vi.fn(),
+    onToggleErrors: vi.fn(),
+    onSetDuration: vi.fn(),
+    onSetAttributes: vi.fn(),
+  };
+
+  render(FacetSidebar, { props });
+  return props;
+}
+
+describe("FacetSidebar", () => {
+  it("uses clause state for service and status selection callbacks", async () => {
+    const props = renderSidebar();
+    await fireEvent.click(screen.getByText("payments"));
+    await fireEvent.click(screen.getByText("500"));
+    expect(props.onSetService).toHaveBeenCalledWith("payments");
+    expect(props.onSetStatus).toHaveBeenCalledWith(500);
+  });
+
+  it("keeps unsupported facet axes as manual controls", async () => {
+    const props = renderSidebar();
+    await fireEvent.input(screen.getByPlaceholderText("namespace"), {
+      target: { value: "prod" },
+    });
+    await fireEvent.click(screen.getAllByText("Apply")[0]);
+    expect(props.onSetNamespace).toHaveBeenCalledWith("prod");
+  });
+});
diff --git a/crates/opsml_server/opsml_ui/src/lib/components/trace/filters/filterState.svelte.ts b/crates/opsml_server/opsml_ui/src/lib/components/trace/filters/filterState.svelte.ts
index d5e3fa5dab..d25cfa59ed 100644
--- a/crates/opsml_server/opsml_ui/src/lib/components/trace/filters/filterState.svelte.ts
+++ b/crates/opsml_server/opsml_ui/src/lib/components/trace/filters/filterState.svelte.ts
@@ -1,103 +1,23 @@
-import type {
-  ActiveFilter,
-  TraceFilters,
-  TracePageFilter,
-} from "../types";
+import type { TracePageFilter } from "../types";
+import {
+  clauseToActiveFilters,
+  type ActiveFilter,
+} from "../clause";
 
-export function derivedActiveFilters(
-  page: TracePageFilter,
-): ActiveFilter[] {
-  const f = page.filters;
-  const out: ActiveFilter[] = [];
-
-  if (f.service_name) {
-    out.push({ key: "service_name", label: "Service", value: f.service_name });
-  }
-  if (f.service_namespace) {
-    out.push({ key: "service_namespace", label: "Namespace", value: f.service_namespace });
-  }
-  if (f.service_version) {
-    out.push({ key: "service_version", label: "Version", value: f.service_version });
-  }
-  if (f.service_instance_id) {
-    out.push({ key: "service_instance_id", label: "Instance", value: f.service_instance_id });
-  }
-  if (typeof f.status_code === "number") {
-    out.push({
-      key: "status_code",
-      label: "Status",
-      value: String(f.status_code),
-    });
-  }
-  if (f.has_errors) {
-    out.push({ key: "has_errors", label: "Has errors", value: "true" });
-  }
-  if (typeof f.duration_min_ms === "number") {
-    out.push({
-      key: "duration_min_ms",
-      label: "Min duration",
-      value: `${f.duration_min_ms}ms`,
-    });
-  }
-  if (typeof f.duration_max_ms === "number") {
-    out.push({
-      key: "duration_max_ms",
-      label: "Max duration",
-      value: `${f.duration_max_ms}ms`,
-    });
-  }
-  for (const raw of f.attribute_filters ?? []) {
-    out.push({
-      key: "attribute",
-      label: "Attr",
-      value: raw,
-      attributeRaw: raw,
-    });
-  }
-
-  return out;
+export function derivedActiveFilters(page: TracePageFilter): ActiveFilter[] {
+  return clauseToActiveFilters(page.filters.clause);
 }
 
 export function removeActiveFilter(
   page: TracePageFilter,
   filter: ActiveFilter,
 ): TracePageFilter {
-  const nextFilters: TraceFilters = { ...page.filters };
-
-  switch (filter.key) {
-    case "service_name":
-      delete nextFilters.service_name;
-      break;
-    case "service_namespace":
-      delete nextFilters.service_namespace;
-      break;
-    case "service_version":
-      delete nextFilters.service_version;
-      break;
-    case "service_instance_id":
-      delete nextFilters.service_instance_id;
-      break;
-    case "status_code":
-      delete nextFilters.status_code;
-      break;
-    case "has_errors":
-      delete nextFilters.has_errors;
-      break;
-    case "duration_min_ms":
-      delete nextFilters.duration_min_ms;
-      break;
-    case "duration_max_ms":
-      delete nextFilters.duration_max_ms;
-      break;
-    case "attribute":
-      nextFilters.attribute_filters = (nextFilters.attribute_filters ?? []).filter(
-        (a) => a !== filter.attributeRaw,
-      );
-      if (nextFilters.attribute_filters.length === 0) {
-        delete nextFilters.attribute_filters;
-      }
-      break;
-  }
-
-  return { ...page, filters: nextFilters };
+  const nextClause = filter.remove(page.filters.clause);
+  return {
+    ...page,
+    filters: {
+      ...page.filters,
+      clause: nextClause,
+    },
+  };
 }
diff --git a/crates/opsml_server/opsml_ui/src/lib/components/trace/filters/filterState.test.ts b/crates/opsml_server/opsml_ui/src/lib/components/trace/filters/filterState.test.ts
index 5b8f1b88c5..5947cdd607 100644
--- a/crates/opsml_server/opsml_ui/src/lib/components/trace/filters/filterState.test.ts
+++ b/crates/opsml_server/opsml_ui/src/lib/components/trace/filters/filterState.test.ts
@@ -1,125 +1,108 @@
 import { describe, expect, it } from "vitest";
-import { derivedActiveFilters, removeActiveFilter } from "./filterState.svelte";
+import {
+  andClause,
+  attrClause,
+  durationMaxClause,
+  durationMinClause,
+  hasErrorsClause,
+  serviceClause,
+  serviceInstanceIdClause,
+  serviceNamespaceClause,
+  serviceVersionClause,
+  statusCodeClause,
+} from "../clause";
 import type { TracePageFilter } from "../types";
+import { derivedActiveFilters, removeActiveFilter } from "./filterState.svelte";
 
 function makeFilterState(): TracePageFilter {
   return {
     bucket_interval: "minute",
     selected_range: "15min",
     filters: {
-      service_name: "svc-a",
-      service_namespace: "prod",
-      service_version: "1.2.3",
-      service_instance_id: "pod-a",
-      status_code: 2,
-      has_errors: true,
-      duration_min_ms: 100,
-      duration_max_ms: 300,
-      attribute_filters: ["component=kafka", "env=prod"],
+      clause: andClause(
+        serviceClause("svc-a"),
+        serviceNamespaceClause("prod"),
+        serviceVersionClause("1.2.3"),
+        serviceInstanceIdClause("pod-a"),
+        statusCodeClause(2),
+        hasErrorsClause(true),
+        durationMinClause(100),
+        durationMaxClause(300),
+        attrClause("component", "kafka"),
+        attrClause("env", "prod"),
+      ),
     },
   };
 }
 
 describe("derivedActiveFilters", () => {
-  it("derives all active chips from the unified filter state", () => {
+  it("derives all active chips from the clause state", () => {
     const chips = derivedActiveFilters(makeFilterState());
-    expect(chips).toEqual([
-      { key: "service_name", label: "Service", value: "svc-a" },
-      { key: "service_namespace", label: "Namespace", value: "prod" },
-      { key: "service_version", label: "Version", value: "1.2.3" },
-      { key: "service_instance_id", label: "Instance", value: "pod-a" },
-      { key: "status_code", label: "Status", value: "2" },
-      { key: "has_errors", label: "Has errors", value: "true" },
-      { key: "duration_min_ms", label: "Min duration", value: "100ms" },
-      { key: "duration_max_ms", label: "Max duration", value: "300ms" },
-      {
-        key: "attribute",
-        label: "Attr",
-        value: "component=kafka",
-        attributeRaw: "component=kafka",
-      },
-      {
-        key: "attribute",
-        label: "Attr",
-        value: "env=prod",
-        attributeRaw: "env=prod",
-      },
+    expect(chips.map((chip) => chip.label)).toEqual([
+      "Service: svc-a",
+      "Namespace: prod",
+      "Version: 1.2.3",
+      "Instance: pod-a",
+      "Status: 2",
+      "Has errors: true",
+      "Min duration: 100ms",
+      "Max duration: 300ms",
+      "Attr: component=kafka",
+      "Attr: env=prod",
     ]);
   });
 });
 
 describe("removeActiveFilter", () => {
   it("removes duration bounds from server-backed filters", () => {
-    const next = removeActiveFilter(makeFilterState(), {
-      key: "duration_min_ms",
-      label: "Min duration",
-      value: "100ms",
-    });
-    expect(next.filters.duration_min_ms).toBeUndefined();
-    expect(next.filters.duration_max_ms).toBe(300);
+    const chips = derivedActiveFilters(makeFilterState());
+    const next = removeActiveFilter(
+      makeFilterState(),
+      chips.find((chip) => chip.label === "Min duration: 100ms")!,
+    );
+    expect(derivedActiveFilters(next).map((chip) => chip.label)).not.toContain(
+      "Min duration: 100ms",
+    );
+    expect(derivedActiveFilters(next).map((chip) => chip.label)).toContain(
+      "Max duration: 300ms",
+    );
   });
 
-  it("removes a single attribute filter and drops the list when empty", () => {
+  it("removes a single attribute filter", () => {
     const initial = makeFilterState();
-    const oneRemoved = removeActiveFilter(initial, {
-      key: "attribute",
-      label: "Attr",
-      value: "component=kafka",
-      attributeRaw: "component=kafka",
-    });
-    expect(oneRemoved.filters.attribute_filters).toEqual(["env=prod"]);
-
-    const allRemoved = removeActiveFilter(
-      {
-        ...initial,
-        filters: { ...initial.filters, attribute_filters: ["env=prod"] },
-      },
-      {
-        key: "attribute",
-        label: "Attr",
-        value: "env=prod",
-        attributeRaw: "env=prod",
-      },
+    const chips = derivedActiveFilters(initial);
+    const oneRemoved = removeActiveFilter(
+      initial,
+      chips.find((chip) => chip.label === "Attr: component=kafka")!,
+    );
+    expect(derivedActiveFilters(oneRemoved).map((chip) => chip.label)).toContain(
+      "Attr: env=prod",
+    );
+    expect(derivedActiveFilters(oneRemoved).map((chip) => chip.label)).not.toContain(
+      "Attr: component=kafka",
     );
-    expect(allRemoved.filters.attribute_filters).toBeUndefined();
   });
 
-  it("removes service identity/status/error chips from the main filter object", () => {
-    let next = removeActiveFilter(makeFilterState(), {
-      key: "service_name",
-      label: "Service",
-      value: "svc-a",
-    });
-    next = removeActiveFilter(next, {
-      key: "service_namespace",
-      label: "Namespace",
-      value: "prod",
-    });
-    next = removeActiveFilter(next, {
-      key: "service_version",
-      label: "Version",
-      value: "1.2.3",
-    });
-    next = removeActiveFilter(next, {
-      key: "service_instance_id",
-      label: "Instance",
-      value: "pod-a",
-    });
-    next = removeActiveFilter(next, {
-      key: "status_code",
-      label: "Status",
-      value: "2",
-    });
-    next = removeActiveFilter(next, {
-      key: "has_errors",
-      label: "Has errors",
-      value: "true",
-    });
-    expect(next.filters.service_name).toBeUndefined();
-    expect(next.filters.service_namespace).toBeUndefined();
-    expect(next.filters.service_version).toBeUndefined();
-    expect(next.filters.service_instance_id).toBeUndefined();
-    expect(next.filters.status_code).toBeUndefined();
-    expect(next.filters.has_errors).toBeUndefined();
+  it("removes service identity/status/error chips from the clause", () => {
+    let next = makeFilterState();
+    for (const label of [
+      "Service: svc-a",
+      "Namespace: prod",
+      "Version: 1.2.3",
+      "Instance: pod-a",
+      "Status: 2",
+      "Has errors: true",
+    ]) {
+      const chip = derivedActiveFilters(next).find((item) => item.label === label);
+      expect(chip).toBeDefined();
+      next = removeActiveFilter(next, chip!);
+    }
+    const labels = derivedActiveFilters(next).map((chip) => chip.label);
+    expect(labels).not.toContain("Service: svc-a");
+    expect(labels).not.toContain("Namespace: prod");
+    expect(labels).not.toContain("Version: 1.2.3");
+    expect(labels).not.toContain("Instance: pod-a");
+    expect(labels).not.toContain("Status: 2");
+    expect(labels).not.toContain("Has errors: true");
   });
 });
diff --git a/crates/opsml_server/opsml_ui/src/lib/components/trace/genai/__tests__/utils.genai.test.ts b/crates/opsml_server/opsml_ui/src/lib/components/trace/genai/__tests__/utils.genai.test.ts
index 60342ad548..a5559e7a08 100644
--- a/crates/opsml_server/opsml_ui/src/lib/components/trace/genai/__tests__/utils.genai.test.ts
+++ b/crates/opsml_server/opsml_ui/src/lib/components/trace/genai/__tests__/utils.genai.test.ts
@@ -77,6 +77,7 @@ describe("getServerGenAiTraceMetrics", () => {
     await getServerGenAiTraceMetrics(fetch, "trace/with space");
     const url: string = mockPost.mock.calls[0][0];
     expect(url).toContain("trace%2Fwith%20space");
+    expect(url).toContain("/api/scouter/genai/traces/");
   });
 
   it("sends correct default body shape", async () => {
diff --git a/crates/opsml_server/opsml_ui/src/lib/components/trace/mockData.ts b/crates/opsml_server/opsml_ui/src/lib/components/trace/mockData.ts
index cabbbab584..8726e39a49 100644
--- a/crates/opsml_server/opsml_ui/src/lib/components/trace/mockData.ts
+++ b/crates/opsml_server/opsml_ui/src/lib/components/trace/mockData.ts
@@ -13,8 +13,9 @@ import type {
   TraceFilters,
   TraceMetricsRequest,
   TraceRequest,
-  Attribute,
 } from "$lib/components/trace/types";
+import { evaluateClause } from "./clauseEvaluator";
+import { removeClauseDimension } from "./clause";
 
 // ── Helpers ──────────────────────────────────────────────────────────────
 
@@ -456,19 +457,19 @@ const ALL_BUILDERS = [
 ];
 
 // Service/scope metadata for each trace (used for TraceListItem)
-const TRACE_META: { service: string; scope: string }[] = [
-  { service: "inference-api", scope: "http" },
-  { service: "inference-api", scope: "http" },
-  { service: "llm-gateway", scope: "genai" },
-  { service: "data-pipeline", scope: "batch" },
-  { service: "llm-gateway", scope: "genai" },
-  { service: "inference-api", scope: "http" },
-  { service: "monitoring-agent", scope: "drift" },
-  { service: "inference-api", scope: "http" },
-  { service: "llm-gateway", scope: "genai" },
-  { service: "data-pipeline", scope: "batch" },
-  { service: "inference-api", scope: "http" },
-  { service: "monitoring-agent", scope: "drift" },
+const TRACE_META: { service: string; scope: string; namespace: string; version: string; instance: string }[] = [
+  { service: "inference-api", scope: "http", namespace: "models", version: "3.2.1", instance: "pod-a" },
+  { service: "inference-api", scope: "http", namespace: "models", version: "3.2.1", instance: "pod-b" },
+  { service: "llm-gateway", scope: "genai", namespace: "agents", version: "1.0.0", instance: "pod-c" },
+  { service: "data-pipeline", scope: "batch", namespace: "features", version: "2.4.0", instance: "worker-a" },
+  { service: "llm-gateway", scope: "genai", namespace: "agents", version: "1.0.0", instance: "pod-d" },
+  { service: "inference-api", scope: "http", namespace: "models", version: "2.1.0", instance: "pod-e" },
+  { service: "monitoring-agent", scope: "drift", namespace: "monitoring", version: "0.9.0", instance: "pod-f" },
+  { service: "inference-api", scope: "http", namespace: "models", version: "3.2.1", instance: "pod-g" },
+  { service: "llm-gateway", scope: "genai", namespace: "agents", version: "1.0.0", instance: "pod-h" },
+  { service: "data-pipeline", scope: "batch", namespace: "features", version: "2.4.0", instance: "worker-b" },
+  { service: "inference-api", scope: "http", namespace: "models", version: "1.5.0", instance: "pod-i" },
+  { service: "monitoring-agent", scope: "drift", namespace: "monitoring", version: "0.9.0", instance: "pod-j" },
 ];
 
 // Build all spans once at module load
@@ -498,7 +499,12 @@ function buildTraceListItems(): TraceListItem[] {
       has_errors: errorSpans.length > 0,
       error_count: errorSpans.length,
       created_at: new Date(startMs).toISOString(),
-      resource_attributes: root.attributes,
+      resource_attributes: [
+        ...root.attributes,
+        { key: "service.namespace", value: TRACE_META[i].namespace },
+        { key: "service.version", value: TRACE_META[i].version },
+        { key: "service.instance.id", value: TRACE_META[i].instance },
+      ],
     };
   });
 }
@@ -561,11 +567,14 @@ function buildMetricBuckets(
 export function getMockTracePage(filters: TraceFilters): TracePaginationResponse {
   let items = buildTraceListItems();
 
-  if (filters.service_name) {
-    items = items.filter((t) => t.service_name === filters.service_name);
+  if (filters.clause) items = items.filter((item) => evaluateClause(item, filters.clause!));
+  if (filters.start_time) {
+    const start = new Date(filters.start_time).getTime();
+    items = items.filter((item) => new Date(item.start_time).getTime() >= start);
   }
-  if (filters.has_errors !== undefined) {
-    items = items.filter((t) => t.has_errors === filters.has_errors);
+  if (filters.end_time) {
+    const end = new Date(filters.end_time).getTime();
+    items = items.filter((item) => new Date(item.start_time).getTime() <= end);
   }
 
   const limit = filters.limit || 50;
@@ -598,8 +607,43 @@ export function getMockTraceMetrics(
   const startTime = request.start_time || new Date(Date.now() - 15 * 60_000).toISOString();
   const endTime = request.end_time || new Date().toISOString();
   const bucketInterval = request.bucket_interval || "1 minutes";
+  const matchingItems = request.clause
+    ? buildTraceListItems().filter((item) => evaluateClause(item, request.clause!))
+    : buildTraceListItems();
+  const buckets = buildMetricBuckets(startTime, endTime, bucketInterval);
+
+  return {
+    metrics: buckets.map((bucket) => ({
+      ...bucket,
+      trace_count: Math.min(bucket.trace_count, matchingItems.length),
+    })),
+  };
+}
+
+export function getMockTraceFacets(filters: TraceFilters) {
+  const items = buildTraceListItems();
+  const filterItems = (dimension: "service" | "status_code") => {
+    const clause = removeClauseDimension(filters.clause, dimension);
+    return clause ? items.filter((item) => evaluateClause(item, clause)) : items;
+  };
+  const serviceItems = filterItems("service");
+  const statusItems = filterItems("status_code");
 
   return {
-    metrics: buildMetricBuckets(startTime, endTime, bucketInterval),
+    services: toFacetDimensions(serviceItems.map((item) => item.service_name)),
+    status_codes: toFacetDimensions(statusItems.map((item) => String(item.status_code))),
+    total_count: filters.clause
+      ? items.filter((item) => evaluateClause(item, filters.clause!)).length
+      : items.length,
   };
 }
+
+function toFacetDimensions(values: string[]) {
+  const counts = new Map<string, number>();
+  for (const value of values) {
+    counts.set(value, (counts.get(value) ?? 0) + 1);
+  }
+  return Array.from(counts.entries())
+    .map(([value, trace_count]) => ({ value, trace_count }))
+    .sort((a, b) => b.trace_count - a.trace_count || a.value.localeCompare(b.value));
+}
diff --git a/crates/opsml_server/opsml_ui/src/lib/components/trace/types.ts b/crates/opsml_server/opsml_ui/src/lib/components/trace/types.ts
index 1c88a19abb..484587ac3d 100644
--- a/crates/opsml_server/opsml_ui/src/lib/components/trace/types.ts
+++ b/crates/opsml_server/opsml_ui/src/lib/components/trace/types.ts
@@ -1,4 +1,5 @@
 import type { DateTime } from "$lib/types";
+import type { FilterClause } from "./clause";
 
 export interface TraceListItem {
   trace_id: string;
@@ -28,24 +29,15 @@ export interface TraceMetricBucket {
 }
 
 export interface TraceFilters {
-  service_name?: string;
-  service_namespace?: string;
-  service_version?: string;
-  service_instance_id?: string;
-  has_errors?: boolean;
-  status_code?: number;
+  clause?: FilterClause;
   start_time?: DateTime;
   end_time?: DateTime;
-  duration_min_ms?: number;
-  duration_max_ms?: number;
   limit?: number;
   cursor_start_time?: DateTime;
   cursor_trace_id?: string;
   direction?: "next" | "previous";
-  attribute_filters?: string[];
   trace_ids?: string[];
   entity_uid?: string;
-  queue_uid?: string;
 }
 
 export interface TraceCursor {
@@ -163,45 +155,17 @@ export interface TraceRequest {
 }
 
 export interface TraceMetricsRequest {
-  service_name?: string;
-  service_namespace?: string;
-  service_version?: string;
-  service_instance_id?: string;
-  has_errors?: boolean;
-  status_code?: number;
-  start_time?: DateTime;
-  end_time?: DateTime;
+  clause?: FilterClause;
+  start_time: DateTime;
+  end_time: DateTime;
   bucket_interval?: string;
-  duration_min_ms?: number;
-  duration_max_ms?: number;
-  attribute_filters?: string[];
-  trace_ids?: string[];
   entity_uid?: string;
-  queue_uid?: string;
 }
 
 export interface TraceMetricsResponse {
   metrics: TraceMetricBucket[];
 }
 
-export type ActiveFilterKey =
-  | "service_name"
-  | "service_namespace"
-  | "service_version"
-  | "service_instance_id"
-  | "status_code"
-  | "has_errors"
-  | "duration_min_ms"
-  | "duration_max_ms"
-  | "attribute";
-
-export interface ActiveFilter {
-  key: ActiveFilterKey;
-  label: string;
-  value: string;
-  attributeRaw?: string;
-}
-
 export interface FacetCount {
   value: string;
   count: number;
diff --git a/crates/opsml_server/opsml_ui/src/lib/components/trace/validation.test.ts b/crates/opsml_server/opsml_ui/src/lib/components/trace/validation.test.ts
new file mode 100644
index 0000000000..556459f952
--- /dev/null
+++ b/crates/opsml_server/opsml_ui/src/lib/components/trace/validation.test.ts
@@ -0,0 +1,66 @@
+import { describe, expect, it } from "vitest";
+import { andClause, serviceClause, statusCodeClause } from "./clause";
+import { validateTraceFilters, validateTraceMetricsRequest } from "./validation";
+
+describe("trace request validation", () => {
+  it("accepts representative clause-shaped trace filters", () => {
+    const input = {
+      clause: andClause(serviceClause("checkout"), statusCodeClause(500)),
+      start_time: "2026-01-01T00:00:00Z",
+      end_time: "2026-01-02T00:00:00Z",
+      limit: 50,
+    };
+    expect(validateTraceFilters(input)).toEqual({ ok: true, value: input });
+  });
+
+  it("rejects unknown top-level fields", () => {
+    expect(validateTraceFilters({ service_name: "checkout" })).toEqual({
+      ok: false,
+      error: "unknown field: service_name",
+    });
+  });
+
+  it("rejects unknown clause fields", () => {
+    expect(validateTraceFilters({ clause: { op: "service", value: "checkout", extra: true } })).toEqual({
+      ok: false,
+      error: "clause contains unknown field: extra",
+    });
+  });
+
+  it("rejects unsupported clause ops", () => {
+    expect(validateTraceFilters({ clause: { op: "service_name", value: "checkout" } })).toEqual({
+      ok: false,
+      error: "unsupported clause op: service_name",
+    });
+  });
+
+  it("rejects invalid limits and inverted time ranges", () => {
+    expect(validateTraceFilters({ limit: 1000 })).toEqual({
+      ok: false,
+      error: "limit must be between 1 and 500",
+    });
+    expect(validateTraceFilters({
+      start_time: "2026-01-02T00:00:00Z",
+      end_time: "2026-01-01T00:00:00Z",
+    })).toEqual({
+      ok: false,
+      error: "start_time must be before end_time",
+    });
+  });
+
+  it("requires metrics start and end times", () => {
+    expect(validateTraceMetricsRequest({ end_time: "2026-01-02T00:00:00Z" })).toEqual({
+      ok: false,
+      error: "start_time and end_time are required",
+    });
+  });
+
+  it("accepts metrics requests with optional bucket interval", () => {
+    const input = {
+      start_time: "2026-01-01T00:00:00Z",
+      end_time: "2026-01-02T00:00:00Z",
+      bucket_interval: "1 hours",
+    };
+    expect(validateTraceMetricsRequest(input)).toEqual({ ok: true, value: input });
+  });
+});
diff --git a/crates/opsml_server/opsml_ui/src/lib/components/trace/validation.ts b/crates/opsml_server/opsml_ui/src/lib/components/trace/validation.ts
new file mode 100644
index 0000000000..fc500110ef
--- /dev/null
+++ b/crates/opsml_server/opsml_ui/src/lib/components/trace/validation.ts
@@ -0,0 +1,278 @@
+import type { FilterClause } from "./clause";
+import type { TraceFilters, TraceMetricsRequest } from "./types";
+
+/**
+ * Runtime safety limits for user-submitted trace filters.
+ *
+ * The TypeScript `FilterClause` union keeps authored UI code honest, but these
+ * SvelteKit endpoints also accept arbitrary JSON from authenticated users. The
+ * caps below keep recursive clause evaluation and proxy payloads bounded before
+ * a request reaches dev mocks or the Scouter backend.
+ */
+const MAX_CLAUSE_DEPTH = 8;
+const MAX_CLAUSE_LEAVES = 64;
+const MAX_FILTER_STRING_LENGTH = 512;
+const MAX_ATTR_KEY_LENGTH = 256;
+const MAX_TRACE_IDS = 100;
+const MAX_TRACE_LIMIT = 500;
+const MAX_RANGE_MS = 90 * 24 * 60 * 60 * 1000;
+
+type ValidationResult<T> =
+  | { ok: true; value: T }
+  | { ok: false; error: string };
+
+const TRACE_FILTER_KEYS = new Set([
+  "clause",
+  "start_time",
+  "end_time",
+  "limit",
+  "cursor_start_time",
+  "cursor_trace_id",
+  "direction",
+  "trace_ids",
+  "entity_uid",
+]);
+
+const TRACE_METRICS_KEYS = new Set([
+  "clause",
+  "start_time",
+  "end_time",
+  "bucket_interval",
+  "entity_uid",
+]);
+
+/** Returns true when a JSON value is an object that can carry request fields. */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Lists request keys that are not part of the accepted contract. */
+function unknownKeys(
+  value: Record<string, unknown>,
+  allowed: Set<string>,
+): string[] {
+  return Object.keys(value).filter((key) => !allowed.has(key));
+}
+
+/** Validates bounded non-empty string fields used by trace filters. */
+function validateString(
+  value: unknown,
+  field: string,
+  maxLength = MAX_FILTER_STRING_LENGTH,
+): string | undefined {
+  if (typeof value !== "string") return `${field} must be a string`;
+  if (value.length === 0) return `${field} must not be empty`;
+  if (value.length > maxLength) return `${field} is too long`;
+}
+
+/** Validates a string field that must parse as a date. */
+function validateDateString(value: unknown, field: string): string | undefined {
+  const stringError = validateString(value, field);
+  if (stringError) return stringError;
+  if (Number.isNaN(Date.parse(value as string))) return `${field} must be a valid date`;
+}
+
+/** Validates optional start/end bounds and prevents overly broad trace queries. */
+function validateTimeRange(value: Record<string, unknown>): string | undefined {
+  if (value.start_time !== undefined) {
+    const error = validateDateString(value.start_time, "start_time");
+    if (error) return error;
+  }
+  if (value.end_time !== undefined) {
+    const error = validateDateString(value.end_time, "end_time");
+    if (error) return error;
+  }
+  if (value.start_time === undefined || value.end_time === undefined) return;
+
+  const start = Date.parse(value.start_time as string);
+  const end = Date.parse(value.end_time as string);
+  if (start > end) return "start_time must be before end_time";
+  if (end - start > MAX_RANGE_MS) return "time range is too large";
+}
+
+/** Validates the server-side page size cap for trace list requests. */
+function validateLimit(value: unknown): string | undefined {
+  if (typeof value !== "number" || !Number.isInteger(value)) {
+    return "limit must be an integer";
+  }
+  if (value < 1 || value > MAX_TRACE_LIMIT) {
+    return `limit must be between 1 and ${MAX_TRACE_LIMIT}`;
+  }
+}
+
+/** Validates explicit trace-id filters without allowing unbounded arrays. */
+function validateTraceIds(value: unknown): string | undefined {
+  if (!Array.isArray(value)) return "trace_ids must be an array";
+  if (value.length > MAX_TRACE_IDS) return "trace_ids has too many values";
+  for (const [index, traceId] of value.entries()) {
+    const error = validateString(traceId, `trace_ids[${index}]`);
+    if (error) return error;
+  }
+}
+
+/** Validates clause leaves whose payload is a single string value. */
+function validateLeafString(
+  clause: Record<string, unknown>,
+  op: string,
+): string | undefined {
+  return validateString(clause.value, `${op}.value`);
+}
+
+/**
+ * Validates the recursive `FilterClause` discriminated-union shape.
+ *
+ * The validator intentionally rejects unknown keys so a legacy scalar filter or
+ * typo does not silently pass through the UI proxy with unclear backend
+ * behavior.
+ */
+function validateClauseNode(
+  clause: unknown,
+  depth: number,
+  leafCount: { value: number },
+): string | undefined {
+  if (!isPlainObject(clause)) return "clause must be an object";
+  if (depth > MAX_CLAUSE_DEPTH) return "clause is too deeply nested";
+
+  const keys = unknownKeys(clause, new Set(["op", "value"]));
+  if (keys.length > 0) return `clause contains unknown field: ${keys[0]}`;
+
+  if (typeof clause.op !== "string") return "clause.op must be a string";
+
+  switch (clause.op) {
+    case "and":
+    case "or": {
+      if (!Array.isArray(clause.value)) return `${clause.op}.value must be an array`;
+      if (clause.value.length === 0) return `${clause.op}.value must not be empty`;
+      for (const child of clause.value) {
+        const error = validateClauseNode(child, depth + 1, leafCount);
+        if (error) return error;
+      }
+      return;
+    }
+    case "not":
+      return validateClauseNode(clause.value, depth + 1, leafCount);
+    case "phrase":
+    case "service":
+    case "service_namespace":
+    case "service_version":
+    case "service_instance_id":
+      leafCount.value += 1;
+      if (leafCount.value > MAX_CLAUSE_LEAVES) return "clause has too many leaves";
+      return validateLeafString(clause, clause.op);
+    case "status_code":
+      leafCount.value += 1;
+      if (leafCount.value > MAX_CLAUSE_LEAVES) return "clause has too many leaves";
+      if (typeof clause.value !== "number" || !Number.isInteger(clause.value)) {
+        return "status_code.value must be an integer";
+      }
+      return;
+    case "has_errors":
+      leafCount.value += 1;
+      if (leafCount.value > MAX_CLAUSE_LEAVES) return "clause has too many leaves";
+      if (typeof clause.value !== "boolean") return "has_errors.value must be a boolean";
+      return;
+    case "duration_min_ms":
+    case "duration_max_ms":
+      leafCount.value += 1;
+      if (leafCount.value > MAX_CLAUSE_LEAVES) return "clause has too many leaves";
+      if (typeof clause.value !== "number" || !Number.isInteger(clause.value) || clause.value < 0) {
+        return `${clause.op}.value must be a non-negative integer`;
+      }
+      return;
+    case "attr": {
+      leafCount.value += 1;
+      if (leafCount.value > MAX_CLAUSE_LEAVES) return "clause has too many leaves";
+      if (!isPlainObject(clause.value)) return "attr.value must be an object";
+      const attrKeys = unknownKeys(clause.value, new Set(["key", "value"]));
+      if (attrKeys.length > 0) return `attr.value contains unknown field: ${attrKeys[0]}`;
+      return (
+        validateString(clause.value.key, "attr.key", MAX_ATTR_KEY_LENGTH) ??
+        validateString(clause.value.value, "attr.value")
+      );
+    }
+    default:
+      return `unsupported clause op: ${clause.op}`;
+  }
+}
+
+/** Starts recursive clause validation with a fresh leaf counter. */
+function validateClause(value: unknown): string | undefined {
+  return validateClauseNode(value, 1, { value: 0 });
+}
+
+/** Validates fields shared by trace page, facet, and metrics requests. */
+function validateTraceFilterFields(
+  body: Record<string, unknown>,
+  allowedKeys: Set<string>,
+): string | undefined {
+  const extraKeys = unknownKeys(body, allowedKeys);
+  if (extraKeys.length > 0) return `unknown field: ${extraKeys[0]}`;
+
+  if (body.clause !== undefined) {
+    const error = validateClause(body.clause);
+    if (error) return error;
+  }
+  if (body.limit !== undefined) {
+    const error = validateLimit(body.limit);
+    if (error) return error;
+  }
+  if (body.cursor_start_time !== undefined) {
+    const error = validateDateString(body.cursor_start_time, "cursor_start_time");
+    if (error) return error;
+  }
+  if (body.cursor_trace_id !== undefined) {
+    const error = validateString(body.cursor_trace_id, "cursor_trace_id");
+    if (error) return error;
+  }
+  if (body.direction !== undefined && body.direction !== "next" && body.direction !== "previous") {
+    return "direction must be next or previous";
+  }
+  if (body.trace_ids !== undefined) {
+    const error = validateTraceIds(body.trace_ids);
+    if (error) return error;
+  }
+  if (body.entity_uid !== undefined) {
+    const error = validateString(body.entity_uid, "entity_uid");
+    if (error) return error;
+  }
+
+  return validateTimeRange(body);
+}
+
+/**
+ * Validate a trace page/facet request body before mock evaluation or proxying.
+ *
+ * Returns the original body typed as `TraceFilters` only after checking the
+ * runtime JSON shape, supported clause ops, pagination fields, and optional
+ * time range.
+ */
+export function validateTraceFilters(body: unknown): ValidationResult<TraceFilters> {
+  if (!isPlainObject(body)) return { ok: false, error: "request body must be an object" };
+  const error = validateTraceFilterFields(body, TRACE_FILTER_KEYS);
+  if (error) return { ok: false, error };
+  return { ok: true, value: body as TraceFilters };
+}
+
+/**
+ * Validate a trace metrics request body.
+ *
+ * Metrics always require `start_time` and `end_time`; otherwise this applies the
+ * same clause and common field validation as `validateTraceFilters`.
+ */
+export function validateTraceMetricsRequest(
+  body: unknown,
+): ValidationResult<TraceMetricsRequest> {
+  if (!isPlainObject(body)) return { ok: false, error: "request body must be an object" };
+  const error = validateTraceFilterFields(body, TRACE_METRICS_KEYS);
+  if (error) return { ok: false, error };
+  if (!body.start_time || !body.end_time) {
+    return { ok: false, error: "start_time and end_time are required" };
+  }
+  if (body.bucket_interval !== undefined) {
+    const intervalError = validateString(body.bucket_interval, "bucket_interval", 64);
+    if (intervalError) return { ok: false, error: intervalError };
+  }
+  return { ok: true, value: body as unknown as TraceMetricsRequest };
+}
+
+export type { FilterClause };
diff --git a/crates/opsml_server/opsml_ui/src/lib/components/trace/waterfall.test.ts b/crates/opsml_server/opsml_ui/src/lib/components/trace/waterfall.test.ts
new file mode 100644
index 0000000000..16d5bcfb94
--- /dev/null
+++ b/crates/opsml_server/opsml_ui/src/lib/components/trace/waterfall.test.ts
@@ -0,0 +1,77 @@
+import { describe, expect, it } from "vitest";
+import { prepareWaterfallSpans } from "./waterfall";
+import type { TraceSpan } from "./types";
+
+function span(overrides: Partial<TraceSpan> & Pick<TraceSpan, "span_id" | "span_name">): TraceSpan {
+  return {
+    trace_id: "trace-1",
+    parent_span_id: null,
+    span_kind: "INTERNAL",
+    start_time: "2026-05-11T14:12:53.973265Z",
+    end_time: "2026-05-11T14:12:53.973265Z",
+    duration_ms: 0,
+    status_code: 0,
+    status_message: null,
+    attributes: [],
+    events: [],
+    links: [],
+    depth: 0,
+    path: [],
+    root_span_id: "root",
+    span_order: 0,
+    input: null,
+    output: null,
+    service_name: "svc",
+    ...overrides,
+  };
+}
+
+describe("prepareWaterfallSpans", () => {
+  it("uses spans with missing parents as visual roots", () => {
+    const root = span({
+      span_id: "root",
+      span_name: "agent.request",
+      parent_span_id: "remote-parent",
+      duration_ms: 4400,
+      span_order: 0,
+    });
+    const child = span({
+      span_id: "child",
+      span_name: "invocation",
+      parent_span_id: "root",
+      duration_ms: 1000,
+      span_order: 1,
+    });
+
+    const result = prepareWaterfallSpans([root, child]);
+
+    expect(result.map((item) => item.span_id)).toEqual(["root", "child"]);
+    expect(result.map((item) => item.depth)).toEqual([0, 1]);
+  });
+
+  it("derives nested depth and path from parent_span_id when backend depth is flat", () => {
+    const root = span({ span_id: "root", span_name: "agent.request", depth: 0, span_order: 0 });
+    const child = span({
+      span_id: "child",
+      span_name: "call_llm",
+      parent_span_id: "root",
+      depth: 0,
+      span_order: 1,
+    });
+    const grandchild = span({
+      span_id: "grandchild",
+      span_name: "generate_content",
+      parent_span_id: "child",
+      depth: 0,
+      span_order: 2,
+    });
+
+    const result = prepareWaterfallSpans([grandchild, child, root]);
+
+    expect(result.map((item) => [item.span_id, item.depth, item.path])).toEqual([
+      ["root", 0, []],
+      ["child", 1, ["root"]],
+      ["grandchild", 2, ["root", "child"]],
+    ]);
+  });
+});
diff --git a/crates/opsml_server/opsml_ui/src/lib/components/trace/waterfall.ts b/crates/opsml_server/opsml_ui/src/lib/components/trace/waterfall.ts
new file mode 100644
index 0000000000..9a3ff7a4d4
--- /dev/null
+++ b/crates/opsml_server/opsml_ui/src/lib/components/trace/waterfall.ts
@@ -0,0 +1,60 @@
+import type { TraceSpan } from "./types";
+
+function spanTimestamp(span: TraceSpan): number {
+  const time = new Date(span.start_time).getTime();
+  return Number.isFinite(time) ? time : 0;
+}
+
+function compareSpanOrder(a: TraceSpan, b: TraceSpan): number {
+  const tA = spanTimestamp(a);
+  const tB = spanTimestamp(b);
+  return tA !== tB ? tA - tB : a.span_order - b.span_order;
+}
+
+function visualParentId(span: TraceSpan, spanIds: Set<string>): string | null {
+  return span.parent_span_id && spanIds.has(span.parent_span_id) ? span.parent_span_id : null;
+}
+
+export function prepareWaterfallSpans(spans: TraceSpan[]): TraceSpan[] {
+  const spanIds = new Set(spans.map((span) => span.span_id));
+  const childrenMap = new Map<string | null, TraceSpan[]>();
+
+  for (const span of spans) {
+    const parentId = visualParentId(span, spanIds);
+    if (!childrenMap.has(parentId)) childrenMap.set(parentId, []);
+    childrenMap.get(parentId)!.push(span);
+  }
+
+  for (const siblings of childrenMap.values()) {
+    siblings.sort(compareSpanOrder);
+  }
+
+  const result: TraceSpan[] = [];
+  const visited = new Set<string>();
+
+  function traverse(span: TraceSpan, depth: number, path: string[]) {
+    if (visited.has(span.span_id)) return;
+
+    visited.add(span.span_id);
+    result.push({
+      ...span,
+      depth,
+      path,
+    });
+
+    for (const child of childrenMap.get(span.span_id) ?? []) {
+      traverse(child, depth + 1, [...path, span.span_id]);
+    }
+  }
+
+  for (const root of childrenMap.get(null) ?? []) {
+    traverse(root, 0, []);
+  }
+
+  const remaining = spans.filter((span) => !visited.has(span.span_id)).sort(compareSpanOrder);
+  for (const span of remaining) {
+    traverse(span, 0, []);
+  }
+
+  return result;
+}
diff --git a/crates/opsml_server/opsml_ui/src/lib/server/trace/facets.test.ts b/crates/opsml_server/opsml_ui/src/lib/server/trace/facets.test.ts
deleted file mode 100644
index dc64ee1c69..0000000000
--- a/crates/opsml_server/opsml_ui/src/lib/server/trace/facets.test.ts
+++ /dev/null
@@ -1,80 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import type { TraceFilters, TraceFacetsResponse } from "$lib/components/trace/types";
-import { getTraceFacets } from "$lib/server/trace/facets";
-import { ServerPaths } from "$lib/components/api/routes";
-
-function makeFilters(overrides: Partial<TraceFilters> = {}): TraceFilters {
-  return {
-    start_time: "2026-01-01T00:00:00Z",
-    end_time: "2026-01-01T01:00:00Z",
-    service_name: "svc-a",
-    cursor_start_time: "2026-01-01T00:30:00Z",
-    cursor_trace_id: "abc123",
-    direction: "next",
-    ...overrides,
-  };
-}
-
-function makeFacetsResponse(): TraceFacetsResponse {
-  return {
-    services: [{ value: "svc-a", trace_count: 5 }],
-    status_codes: [{ value: "200", trace_count: 4 }],
-    total_count: 5,
-  };
-}
-
-describe("getTraceFacets", () => {
-  it("POSTs to ServerPaths.TRACE_FACETS and returns response", async () => {
-    const payload = makeFacetsResponse();
-    const mockFetch = vi.fn().mockResolvedValue({
-      ok: true,
-      json: async () => ({ response: payload, error: null }),
-    });
-
-    const result = await getTraceFacets(mockFetch as typeof fetch, makeFilters());
-
-    expect(mockFetch).toHaveBeenCalledOnce();
-    const [url, init] = mockFetch.mock.calls[0];
-    expect(url).toBe(ServerPaths.TRACE_FACETS);
-    expect(init.method).toBe("POST");
-    expect(result).toEqual(payload);
-  });
-
-  it("strips cursor fields from POST body", async () => {
-    const mockFetch = vi.fn().mockResolvedValue({
-      ok: true,
-      json: async () => ({ response: makeFacetsResponse(), error: null }),
-    });
-
-    await getTraceFacets(mockFetch as typeof fetch, makeFilters());
-
-    const body = JSON.parse(mockFetch.mock.calls[0][1].body as string);
-    expect(body).not.toHaveProperty("cursor_start_time");
-    expect(body).not.toHaveProperty("cursor_trace_id");
-    expect(body).not.toHaveProperty("direction");
-    expect(body).toHaveProperty("service_name", "svc-a");
-  });
-
-  it("throws on non-ok response", async () => {
-    const mockFetch = vi.fn().mockResolvedValue({
-      ok: false,
-      status: 503,
-      json: async () => ({}),
-    });
-
-    await expect(getTraceFacets(mockFetch as typeof fetch, makeFilters())).rejects.toThrow(
-      "Facets request failed: 503",
-    );
-  });
-
-  it("throws when response body contains error", async () => {
-    const mockFetch = vi.fn().mockResolvedValue({
-      ok: true,
-      json: async () => ({ response: null, error: "upstream failure" }),
-    });
-
-    await expect(getTraceFacets(mockFetch as typeof fetch, makeFilters())).rejects.toThrow(
-      "upstream failure",
-    );
-  });
-});
diff --git a/crates/opsml_server/opsml_ui/src/lib/server/trace/facets.ts b/crates/opsml_server/opsml_ui/src/lib/server/trace/facets.ts
deleted file mode 100644
index e297142de9..0000000000
--- a/crates/opsml_server/opsml_ui/src/lib/server/trace/facets.ts
+++ /dev/null
@@ -1,20 +0,0 @@
-import type { TraceFilters, TraceFacetsResponse } from "$lib/components/trace/types";
-import { ServerPaths } from "$lib/components/api/routes";
-
-export async function getTraceFacets(
-  fetch: typeof globalThis.fetch,
-  filters: TraceFilters,
-): Promise<TraceFacetsResponse> {
-  const { cursor_start_time, cursor_trace_id, direction, ...facetFilters } = filters;
-  const response = await fetch(ServerPaths.TRACE_FACETS, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify(facetFilters),
-  });
-  if (!response.ok) {
-    throw new Error(`Facets request failed: ${response.status}`);
-  }
-  const { response: data, error } = await response.json();
-  if (error) throw new Error(error);
-  return data as TraceFacetsResponse;
-}
diff --git a/crates/opsml_server/opsml_ui/src/lib/server/trace/mockData.ts b/crates/opsml_server/opsml_ui/src/lib/server/trace/mockData.ts
index 2c2a46d500..64dcf3c9ab 100644
--- a/crates/opsml_server/opsml_ui/src/lib/server/trace/mockData.ts
+++ b/crates/opsml_server/opsml_ui/src/lib/server/trace/mockData.ts
@@ -1,5 +1,6 @@
 export {
   getMockTraceMetrics,
   getMockTracePage,
+  getMockTraceFacets,
   getMockTraceSpans,
 } from "$lib/components/trace/mockData";
diff --git a/crates/opsml_server/opsml_ui/src/lib/server/trace/utils.facets.test.ts b/crates/opsml_server/opsml_ui/src/lib/server/trace/utils.facets.test.ts
new file mode 100644
index 0000000000..457d528843
--- /dev/null
+++ b/crates/opsml_server/opsml_ui/src/lib/server/trace/utils.facets.test.ts
@@ -0,0 +1,54 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { getTraceFacets, TraceServerError } from "./utils";
+import { serviceClause } from "$lib/components/trace/clause";
+import { RoutePaths } from "$lib/components/api/routes";
+
+const clientState = vi.hoisted(() => ({
+  captured: [] as unknown[],
+  ok: true,
+  status: 200,
+  text: "",
+}));
+
+vi.mock("../api/opsmlClient", () => ({
+  createOpsmlClient: () => ({
+    post: vi.fn(async (path, body) => {
+      clientState.captured.push({ path, body });
+      return {
+        ok: clientState.ok,
+        status: clientState.status,
+        text: async () => clientState.text,
+        json: async () => ({ services: [], status_codes: [], total_count: 0 }),
+      };
+    }),
+  }),
+}));
+
+describe("getTraceFacets", () => {
+  beforeEach(() => {
+    clientState.captured.length = 0;
+    clientState.ok = true;
+    clientState.status = 200;
+    clientState.text = "";
+  });
+
+  it("posts filters through the shared trace facets route", async () => {
+    const filters = { clause: serviceClause("checkout") };
+    await getTraceFacets(globalThis.fetch, filters);
+    expect(clientState.captured[0]).toEqual({
+      path: RoutePaths.TRACE_FACETS,
+      body: filters,
+    });
+  });
+
+  it("raises TraceServerError with the backend status when the proxy fails", async () => {
+    clientState.ok = false;
+    clientState.status = 503;
+    clientState.text = "scouter unavailable";
+
+    await expect(getTraceFacets(globalThis.fetch, {})).rejects.toMatchObject({
+      message: "scouter unavailable",
+      status: 503,
+    } satisfies Partial<TraceServerError>);
+  });
+});
diff --git a/crates/opsml_server/opsml_ui/src/lib/server/trace/utils.ts b/crates/opsml_server/opsml_ui/src/lib/server/trace/utils.ts
index ed12fecf34..800f8e24d3 100644
--- a/crates/opsml_server/opsml_ui/src/lib/server/trace/utils.ts
+++ b/crates/opsml_server/opsml_ui/src/lib/server/trace/utils.ts
@@ -6,10 +6,25 @@ import type {
   TraceRequest,
   TraceMetricsRequest,
   TraceSpansResponse,
+  TraceFacetsResponse,
 } from "$lib/components/trace/types";
 import { createOpsmlClient } from "../api/opsmlClient";
 import { RoutePaths } from "$lib/components/api/routes";
 
+/**
+ * Error raised by trace server helpers when the backend returns a non-OK
+ * response and the SvelteKit route should preserve that HTTP status.
+ */
+export class TraceServerError extends Error {
+  constructor(
+    message: string,
+    public status = 500,
+  ) {
+    super(message);
+    this.name = "TraceServerError";
+  }
+}
+
 export async function getTracePage(
   fetch: typeof globalThis.fetch,
   filters: TraceFilters
@@ -43,6 +58,31 @@ export async function getTraceMetrics(
   return (await response.json()) as TraceMetricsResponse;
 }
 
+/**
+ * Fetch trace facets through the shared OpsML server client.
+ *
+ * Keeping this transport logic in the server helper layer matches the other
+ * trace BFF calls and keeps `+server.ts` focused on request parsing, mock-mode
+ * branching, and response enveloping.
+ */
+export async function getTraceFacets(
+  fetch: typeof globalThis.fetch,
+  filters: TraceFilters,
+): Promise<TraceFacetsResponse> {
+  const response = await createOpsmlClient(fetch).post(
+    RoutePaths.TRACE_FACETS,
+    filters,
+  );
+  if (!response.ok) {
+    const errorBody = await response.text();
+    throw new TraceServerError(
+      errorBody || `Facets request failed: ${response.status}`,
+      response.status,
+    );
+  }
+  return (await response.json()) as TraceFacetsResponse;
+}
+
 export async function getTraceSpansFromFilters(
   fetch: typeof globalThis.fetch,
   filters: TraceFilters,
diff --git a/crates/opsml_server/opsml_ui/src/routes/api/scouter/observability/trace/+server.ts b/crates/opsml_server/opsml_ui/src/routes/api/scouter/observability/trace/+server.ts
index 2e0d17033d..484667c3b7 100644
--- a/crates/opsml_server/opsml_ui/src/routes/api/scouter/observability/trace/+server.ts
+++ b/crates/opsml_server/opsml_ui/src/routes/api/scouter/observability/trace/+server.ts
@@ -5,9 +5,21 @@ import type {
 } from "$lib/components/trace/types";
 import { getTracePage } from "$lib/server/trace/utils";
 import { isDevMockEnabled } from "$lib/server/mock/mode";
+import { validateTraceFilters } from "$lib/components/trace/validation";
 
+/**
+ * Proxies trace page requests after validating the shared FilterClause body.
+ *
+ * Dev mocks and Scouter receive the same clause-shaped request contract so the
+ * UI does not keep a legacy scalar-filter translation layer alive.
+ */
 export const POST: RequestHandler = async ({ request, fetch, cookies }) => {
-  const filters: TraceFilters = await request.json();
+  const body = await request.json();
+  const validation = validateTraceFilters(body);
+  if (!validation.ok) {
+    return json({ response: null, error: validation.error }, { status: 400 });
+  }
+  const filters: TraceFilters = validation.value;
 
   if (isDevMockEnabled(cookies)) {
     const { getMockTracePage } = await import("$lib/server/trace/mockData");
diff --git a/crates/opsml_server/opsml_ui/src/routes/api/scouter/observability/trace/metrics/+server.ts b/crates/opsml_server/opsml_ui/src/routes/api/scouter/observability/trace/metrics/+server.ts
index 537348e5ba..ee7b8021ab 100644
--- a/crates/opsml_server/opsml_ui/src/routes/api/scouter/observability/trace/metrics/+server.ts
+++ b/crates/opsml_server/opsml_ui/src/routes/api/scouter/observability/trace/metrics/+server.ts
@@ -5,19 +5,35 @@ import type {
 } from "$lib/components/trace/types";
 import { getTraceMetrics } from "$lib/server/trace/utils";
 import { isDevMockEnabled } from "$lib/server/mock/mode";
+import { validateTraceMetricsRequest } from "$lib/components/trace/validation";
 
+/**
+ * Proxies trace metrics requests after validating time bounds and FilterClause.
+ *
+ * Metrics require explicit `start_time` and `end_time` because both Scouter and
+ * the mock evaluator aggregate over a bounded interval.
+ */
 export const POST: RequestHandler = async ({ request, fetch, cookies }) => {
-  const requestBody: TraceMetricsRequest = await request.json();
+  const input = await request.json();
+  const validation = validateTraceMetricsRequest(input);
+
+  if (!validation.ok) {
+    return json(
+      { response: null, error: validation.error },
+      { status: 400 },
+    );
+  }
+  const body: TraceMetricsRequest = validation.value;
 
   if (isDevMockEnabled(cookies)) {
     const { getMockTraceMetrics } = await import("$lib/server/trace/mockData");
-    return json({ response: getMockTraceMetrics(requestBody), error: null });
+    return json({ response: getMockTraceMetrics(body), error: null });
   }
 
   try {
     const response: TraceMetricsResponse = await getTraceMetrics(
       fetch,
-      requestBody,
+      { bucket_interval: "1 hours", ...body },
     );
     return json({ response, error: null });
   } catch (error) {
diff --git a/crates/opsml_server/opsml_ui/src/routes/api/scouter/observability/trace/metrics/server.test.ts b/crates/opsml_server/opsml_ui/src/routes/api/scouter/observability/trace/metrics/server.test.ts
new file mode 100644
index 0000000000..3b8da954ab
--- /dev/null
+++ b/crates/opsml_server/opsml_ui/src/routes/api/scouter/observability/trace/metrics/server.test.ts
@@ -0,0 +1,101 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { andClause, serviceClause, statusCodeClause } from "$lib/components/trace/clause";
+
+const state = vi.hoisted(() => ({
+  captured: [] as unknown[],
+  mockEnabled: false,
+  mockMetricsCalls: 0,
+}));
+
+vi.mock("$lib/server/trace/utils", () => ({
+  getTraceMetrics: vi.fn(async (_fetch, body) => {
+    state.captured.push(body);
+    return { metrics: [] };
+  }),
+}));
+
+vi.mock("$lib/server/mock/mode", () => ({
+  isDevMockEnabled: () => state.mockEnabled,
+}));
+
+vi.mock("$lib/server/trace/mockData", () => ({
+  getMockTraceMetrics: vi.fn((body) => {
+    state.mockMetricsCalls += 1;
+    state.captured.push(body);
+    return { metrics: [] };
+  }),
+}));
+
+import { POST } from "./+server";
+
+async function postJson(body: unknown) {
+  const request = new Request("http://localhost/api/scouter/observability/trace/metrics", {
+    method: "POST",
+    body: JSON.stringify(body),
+  });
+  return POST({ request, fetch: globalThis.fetch, cookies: {} } as never);
+}
+
+describe("POST /api/scouter/observability/trace/metrics", () => {
+  beforeEach(() => {
+    state.captured.length = 0;
+    state.mockEnabled = false;
+    state.mockMetricsCalls = 0;
+  });
+
+  it("forwards a clause-shaped body with default bucket interval", async () => {
+    const input = {
+      clause: andClause(serviceClause("checkout"), statusCodeClause(500)),
+      start_time: "2026-01-01T00:00:00Z",
+      end_time: "2026-01-02T00:00:00Z",
+      entity_uid: "card-1",
+    };
+    await postJson(input);
+    expect(state.captured[0]).toEqual({ bucket_interval: "1 hours", ...input });
+  });
+
+  it("returns 400 when start_time is missing", async () => {
+    const response = await postJson({ end_time: "2026-01-02T00:00:00Z" });
+    expect(response.status).toBe(400);
+    await expect(response.json()).resolves.toEqual({
+      response: null,
+      error: "start_time and end_time are required",
+    });
+    expect(state.captured).toHaveLength(0);
+  });
+
+  it("returns 400 when end_time is missing", async () => {
+    const response = await postJson({ start_time: "2026-01-01T00:00:00Z" });
+    expect(response.status).toBe(400);
+    await expect(response.json()).resolves.toEqual({
+      response: null,
+      error: "start_time and end_time are required",
+    });
+    expect(state.captured).toHaveLength(0);
+  });
+
+  it("returns 400 for malformed clauses", async () => {
+    const response = await postJson({
+      start_time: "2026-01-01T00:00:00Z",
+      end_time: "2026-01-02T00:00:00Z",
+      clause: { op: "service", value: 42 },
+    });
+    expect(response.status).toBe(400);
+    await expect(response.json()).resolves.toEqual({
+      response: null,
+      error: "service.value must be a string",
+    });
+    expect(state.captured).toHaveLength(0);
+  });
+
+  it("short-circuits to mock metrics when mock mode is enabled", async () => {
+    state.mockEnabled = true;
+    const input = {
+      start_time: "2026-01-01T00:00:00Z",
+      end_time: "2026-01-02T00:00:00Z",
+    };
+    await postJson(input);
+    expect(state.mockMetricsCalls).toBe(1);
+    expect(state.captured[0]).toEqual(input);
+  });
+});
diff --git a/crates/opsml_server/opsml_ui/src/routes/api/scouter/observability/trace/server.test.ts b/crates/opsml_server/opsml_ui/src/routes/api/scouter/observability/trace/server.test.ts
new file mode 100644
index 0000000000..a2b069a0c3
--- /dev/null
+++ b/crates/opsml_server/opsml_ui/src/routes/api/scouter/observability/trace/server.test.ts
@@ -0,0 +1,94 @@
+import { describe, expect, it, vi, beforeEach } from "vitest";
+import { andClause, serviceClause, statusCodeClause } from "$lib/components/trace/clause";
+
+const state = vi.hoisted(() => ({
+  captured: [] as unknown[],
+  mockEnabled: false,
+  throwError: false,
+  mockTracePageCalls: 0,
+}));
+
+vi.mock("$lib/server/trace/utils", () => ({
+  getTracePage: vi.fn(async (_fetch, body) => {
+    state.captured.push(body);
+    if (state.throwError) throw new Error("downstream failed");
+    return { items: [], has_next: false, has_previous: false };
+  }),
+}));
+
+vi.mock("$lib/server/mock/mode", () => ({
+  isDevMockEnabled: () => state.mockEnabled,
+}));
+
+vi.mock("$lib/server/trace/mockData", () => ({
+  getMockTracePage: vi.fn((body) => {
+    state.mockTracePageCalls += 1;
+    state.captured.push(body);
+    return { items: [], has_next: false, has_previous: false };
+  }),
+}));
+
+import { POST } from "./+server";
+
+async function postJson(body: unknown) {
+  const request = new Request("http://localhost/api/scouter/observability/trace", {
+    method: "POST",
+    body: JSON.stringify(body),
+  });
+  return POST({ request, fetch: globalThis.fetch, cookies: {} } as never);
+}
+
+describe("POST /api/scouter/observability/trace", () => {
+  beforeEach(() => {
+    state.captured.length = 0;
+    state.mockEnabled = false;
+    state.throwError = false;
+    state.mockTracePageCalls = 0;
+  });
+
+  it("forwards clause-shaped body verbatim", async () => {
+    const input = {
+      clause: andClause(serviceClause("checkout"), statusCodeClause(500)),
+      start_time: "2026-01-01T00:00:00Z",
+      end_time: "2026-01-02T00:00:00Z",
+      entity_uid: "card-1",
+    };
+    await postJson(input);
+    expect(state.captured[0]).toEqual(input);
+  });
+
+  it("preserves omitted clause", async () => {
+    const input = {
+      start_time: "2026-01-01T00:00:00Z",
+      end_time: "2026-01-02T00:00:00Z",
+    };
+    await postJson(input);
+    expect(state.captured[0]).toEqual(input);
+    expect(state.captured[0]).not.toHaveProperty("clause");
+  });
+
+  it("short-circuits to mock data when mock mode is enabled", async () => {
+    state.mockEnabled = true;
+    await postJson({ start_time: "2026-01-01T00:00:00Z", end_time: "2026-01-02T00:00:00Z" });
+    expect(state.mockTracePageCalls).toBe(1);
+  });
+
+  it("returns 400 for invalid trace filters before mock or proxy work", async () => {
+    state.mockEnabled = true;
+    const response = await postJson({ service_name: "checkout" });
+    expect(response.status).toBe(400);
+    await expect(response.json()).resolves.toEqual({
+      response: null,
+      error: "unknown field: service_name",
+    });
+    expect(state.captured).toHaveLength(0);
+    expect(state.mockTracePageCalls).toBe(0);
+  });
+
+  it("returns 500 when downstream throws", async () => {
+    state.throwError = true;
+    const response = await postJson({ start_time: "2026-01-01T00:00:00Z", end_time: "2026-01-02T00:00:00Z" });
+    expect(response.status).toBe(500);
+    await expect(response.json()).resolves.toMatchObject({ error: "downstream failed" });
+  });
+});
diff --git a/crates/opsml_server/opsml_ui/src/routes/api/scouter/observability/trace/types.test-d.ts b/crates/opsml_server/opsml_ui/src/routes/api/scouter/observability/trace/types.test-d.ts
new file mode 100644
index 0000000000..7f211336aa
--- /dev/null
+++ b/crates/opsml_server/opsml_ui/src/routes/api/scouter/observability/trace/types.test-d.ts
@@ -0,0 +1,15 @@
+import { expectTypeOf } from "vitest";
+import type {
+  TraceFilters,
+  TraceMetricsRequest,
+} from "$lib/components/trace/types";
+
+expectTypeOf<TraceFilters>().not.toHaveProperty("service_name");
+expectTypeOf<TraceFilters>().not.toHaveProperty("status_code");
+expectTypeOf<TraceFilters>().not.toHaveProperty("has_errors");
+expectTypeOf<TraceFilters>().not.toHaveProperty("attribute_filters");
+expectTypeOf<TraceFilters>().not.toHaveProperty("duration_min_ms");
+expectTypeOf<TraceFilters>().not.toHaveProperty("duration_max_ms");
+expectTypeOf<TraceFilters>().not.toHaveProperty("queue_uid");
+expectTypeOf<TraceFilters>().toHaveProperty("clause");
+expectTypeOf<TraceMetricsRequest>().not.toHaveProperty("service_name");
diff --git a/crates/opsml_server/opsml_ui/src/routes/api/scouter/trace/facets/+server.ts b/crates/opsml_server/opsml_ui/src/routes/api/scouter/trace/facets/+server.ts
index 18c692780e..b175ac9037 100644
--- a/crates/opsml_server/opsml_ui/src/routes/api/scouter/trace/facets/+server.ts
+++ b/crates/opsml_server/opsml_ui/src/routes/api/scouter/trace/facets/+server.ts
@@ -1,43 +1,30 @@
 import { type RequestHandler, json } from "@sveltejs/kit";
 import type { TraceFacetsResponse, TraceFilters } from "$lib/components/trace/types";
 import { isDevMockEnabled } from "$lib/server/mock/mode";
-import { deriveTraceFacetsFromSpans } from "$lib/server/trace/utils";
-import { createOpsmlClient } from "$lib/server/api/opsmlClient";
-import { RoutePaths } from "$lib/components/api/routes";
+import { getTraceFacets, TraceServerError } from "$lib/server/trace/utils";
+import { validateTraceFilters } from "$lib/components/trace/validation";
 
+/**
+ * Returns trace facet counts for the current validated FilterClause body.
+ *
+ * Unsupported or malformed filter payloads are rejected before the request can
+ * hit dev mocks or Scouter, which keeps facet refresh behavior deterministic.
+ */
 export const POST: RequestHandler = async ({ request, fetch, cookies }) => {
-  const filters: TraceFilters = await request.json();
+  const body = await request.json();
+  const validation = validateTraceFilters(body);
+  if (!validation.ok) {
+    return json({ response: null, error: validation.error }, { status: 400 });
+  }
+  const filters: TraceFilters = validation.value;
 
   if (isDevMockEnabled(cookies)) {
-    const { getMockTracePage, getMockTraceSpans } = await import("$lib/server/trace/mockData");
-    const page = getMockTracePage({ ...filters, limit: 200 });
-    const spans = page.items.flatMap((trace) =>
-      getMockTraceSpans({
-        trace_id: trace.trace_id,
-        service_name: trace.service_name,
-        start_time: trace.start_time,
-        end_time: trace.end_time ?? undefined,
-      }).spans,
-    );
-    const oldFacets = deriveTraceFacetsFromSpans({ spans });
-    const response: TraceFacetsResponse = {
-      services: oldFacets.services.map((f) => ({ value: f.value, trace_count: f.count })),
-      status_codes: oldFacets.status_codes.map((f) => ({ value: f.value, trace_count: f.count })),
-      total_count: oldFacets.services.reduce((sum, f) => sum + f.count, 0),
-    };
-    return json({ response, error: null });
+    const { getMockTraceFacets } = await import("$lib/server/trace/mockData");
+    return json({ response: getMockTraceFacets(filters), error: null });
   }
 
   try {
-    const resp = await createOpsmlClient(fetch).post(RoutePaths.TRACE_FACETS, filters);
-    if (!resp.ok) {
-      const errorBody = await resp.text();
-      return json(
-        { response: null, error: errorBody || `Facets request failed: ${resp.status}` },
-        { status: resp.status },
-      );
-    }
-    const response = (await resp.json()) as TraceFacetsResponse;
+    const response: TraceFacetsResponse = await getTraceFacets(fetch, filters);
     return json({ response, error: null });
   } catch (error) {
     console.error("Error fetching trace facets:", error);
@@ -46,7 +33,7 @@ export const POST: RequestHandler = async ({ request, fetch, cookies }) => {
         response: null,
         error: error instanceof Error ? error.message : "Failed to fetch trace facets",
       },
-      { status: 500 },
+      { status: error instanceof TraceServerError ? error.status : 500 },
     );
   }
 };
diff --git a/crates/opsml_server/opsml_ui/src/routes/api/scouter/trace/facets/server.test.ts b/crates/opsml_server/opsml_ui/src/routes/api/scouter/trace/facets/server.test.ts
new file mode 100644
index 0000000000..c5cde5b272
--- /dev/null
+++ b/crates/opsml_server/opsml_ui/src/routes/api/scouter/trace/facets/server.test.ts
@@ -0,0 +1,106 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { andClause, serviceClause, statusCodeClause } from "$lib/components/trace/clause";
+
+const state = vi.hoisted(() => ({
+  captured: [] as unknown[],
+  mockEnabled: false,
+  helperStatus: 200,
+  helperError: "",
+  mockFacetCalls: 0,
+}));
+
+vi.mock("$lib/server/trace/utils", () => {
+  class TraceServerError extends Error {
+    constructor(message: string, public status = 500) {
+      super(message);
+    }
+  }
+
+  return {
+    TraceServerError,
+    getTraceFacets: vi.fn(async (_fetch, body) => {
+      state.captured.push({ helper: true, body });
+      if (state.helperError) {
+        throw new TraceServerError(state.helperError, state.helperStatus);
+      }
+      return {
+        services: [{ value: "checkout", trace_count: 4 }],
+        status_codes: [{ value: "500", trace_count: 2 }],
+        total_count: 4,
+      };
+    }),
+  };
+});
+
+vi.mock("$lib/server/mock/mode", () => ({
+  isDevMockEnabled: () => state.mockEnabled,
+}));
+
+vi.mock("$lib/server/trace/mockData", () => ({
+  getMockTraceFacets: vi.fn((body) => {
+    state.mockFacetCalls += 1;
+    state.captured.push({ mock: true, body });
+    return { services: [], status_codes: [], total_count: 0 };
+  }),
+}));
+
+import { POST } from "./+server";
+
+async function postJson(body: unknown) {
+  const request = new Request("http://localhost/api/scouter/trace/facets", {
+    method: "POST",
+    body: JSON.stringify(body),
+  });
+  return POST({ request, fetch: globalThis.fetch, cookies: {} } as never);
+}
+
+describe("POST /api/scouter/trace/facets", () => {
+  beforeEach(() => {
+    state.captured.length = 0;
+    state.mockEnabled = false;
+    state.helperStatus = 200;
+    state.helperError = "";
+    state.mockFacetCalls = 0;
+  });
+
+  it("forwards clause-shaped body verbatim", async () => {
+    const input = {
+      clause: andClause(serviceClause("checkout"), statusCodeClause(500)),
+      start_time: "2026-01-01T00:00:00Z",
+      end_time: "2026-01-02T00:00:00Z",
+    };
+    await postJson(input);
+    expect(state.captured[0]).toEqual({ helper: true, body: input });
+  });
+
+  it("propagates backend non-ok status and body", async () => {
+    state.helperStatus = 503;
+    state.helperError = "scouter unavailable";
+    const response = await postJson({ start_time: "2026-01-01T00:00:00Z" });
+    expect(response.status).toBe(503);
+    await expect(response.json()).resolves.toEqual({
+      response: null,
+      error: "scouter unavailable",
+    });
+  });
+
+  it("returns 400 for invalid trace filters before mock or helper work", async () => {
+    state.mockEnabled = true;
+    const response = await postJson({ clause: { op: "status_code", value: "500" } });
+    expect(response.status).toBe(400);
+    await expect(response.json()).resolves.toEqual({
+      response: null,
+      error: "status_code.value must be an integer",
+    });
+    expect(state.captured).toHaveLength(0);
+    expect(state.mockFacetCalls).toBe(0);
+  });
+
+  it("short-circuits to mock facets when mock mode is enabled", async () => {
+    state.mockEnabled = true;
+    const input = { start_time: "2026-01-01T00:00:00Z" };
+    await postJson(input);
+    expect(state.mockFacetCalls).toBe(1);
+    expect(state.captured[0]).toEqual({ mock: true, body: input });
+  });
+});
diff --git a/crates/opsml_server/opsml_ui/src/routes/opsml/[registry]/card/[space]/[name]/[version]/observability/+page.ts b/crates/opsml_server/opsml_ui/src/routes/opsml/[registry]/card/[space]/[name]/[version]/observability/+page.ts
index fa580259b3..144b525821 100644
--- a/crates/opsml_server/opsml_ui/src/routes/opsml/[registry]/card/[space]/[name]/[version]/observability/+page.ts
+++ b/crates/opsml_server/opsml_ui/src/routes/opsml/[registry]/card/[space]/[name]/[version]/observability/+page.ts
@@ -112,7 +112,6 @@ export const load: PageLoad = async ({ fetch, depends, parent, url }) => {
     }
 
     const metricsRequest: TraceMetricsRequest = {
-      service_name: undefined,
       start_time: startTime,
       end_time: endTime,
       bucket_interval: bucketInterval,
diff --git a/crates/opsml_server/opsml_ui/src/routes/opsml/agent/[registry]/card/[space]/[name]/[version]/observability/+page.ts b/crates/opsml_server/opsml_ui/src/routes/opsml/agent/[registry]/card/[space]/[name]/[version]/observability/+page.ts
index 4e2364774a..df3294bee6 100644
--- a/crates/opsml_server/opsml_ui/src/routes/opsml/agent/[registry]/card/[space]/[name]/[version]/observability/+page.ts
+++ b/crates/opsml_server/opsml_ui/src/routes/opsml/agent/[registry]/card/[space]/[name]/[version]/observability/+page.ts
@@ -22,6 +22,12 @@ import {
   getMockTraceMetrics,
   getMockTracePage,
 } from "$lib/components/trace/mockData";
+import {
+  andClause,
+  serviceClause,
+  serviceNamespaceClause,
+  serviceVersionClause,
+} from "$lib/components/trace/clause";
 import type { CardMetadata } from "$lib/server/card/layout";
 import type { PromptCard } from "$lib/components/card/card_interfaces/promptcard";
 import { RegistryType } from "$lib/utils";
@@ -54,6 +60,17 @@ export const load: PageLoad = async ({ fetch, depends, parent, url }) => {
     const serviceName = isPrompt ? undefined : metadata.name;
     const serviceNamespace = isPrompt ? undefined : metadata.space;
     const serviceVersion = isPrompt ? undefined : metadata.version;
+    const clause = andClause(
+      serviceName ? serviceClause(serviceName) : undefined,
+      serviceNamespace ? serviceNamespaceClause(serviceNamespace) : undefined,
+      serviceVersion ? serviceVersionClause(serviceVersion) : undefined,
+    );
+    /**
+     * Agent cards are scoped by OpenTelemetry service identity. Prompt cards are
+     * scoped by Scouter entity UID. Keeping these shapes exclusive prevents
+     * undefined fields from leaking into tests or internal BFF requests.
+     */
+    const scopeFilters = isPrompt ? { entity_uid } : { clause };
 
     // Fetch trace spans first so we can derive the time window from the trace's timestamp
     let initialTrace: TraceListItem | undefined;
@@ -91,13 +108,10 @@ export const load: PageLoad = async ({ fetch, depends, parent, url }) => {
     }
 
     const metricsRequest: TraceMetricsRequest = {
-      service_name: serviceName,
-      service_namespace: serviceNamespace,
-      service_version: serviceVersion,
       start_time: startTime,
       end_time: endTime,
       bucket_interval: bucketInterval,
-      entity_uid,
+      ...scopeFilters,
     };
 
     const traceMetrics = useMockFallback
@@ -108,19 +122,13 @@ export const load: PageLoad = async ({ fetch, depends, parent, url }) => {
           start_time: startTime,
           end_time: endTime,
           limit: 50,
-          service_name: serviceName,
-          service_namespace: serviceNamespace,
-          service_version: serviceVersion,
-          entity_uid,
+          ...scopeFilters,
         })
       : await getServerTracePage(fetch, {
           start_time: startTime,
           end_time: endTime,
           limit: 50,
-          service_name: serviceName,
-          service_namespace: serviceNamespace,
-          service_version: serviceVersion,
-          entity_uid,
+          ...scopeFilters,
         });
 
     let traceFacets: TraceFacetsResponse = {
@@ -135,10 +143,7 @@ export const load: PageLoad = async ({ fetch, depends, parent, url }) => {
       traceFacets = await getServerTraceFacets(fetch, {
         start_time: startTime,
         end_time: endTime,
-        service_name: serviceName,
-        service_namespace: serviceNamespace,
-        service_version: serviceVersion,
-        entity_uid,
+        ...scopeFilters,
       });
     } catch (facetError) {
       console.warn("Failed to load trace facets:", facetError);
@@ -148,10 +153,7 @@ export const load: PageLoad = async ({ fetch, depends, parent, url }) => {
       filters: {
         start_time: startTime,
         end_time: endTime,
-        service_name: serviceName,
-        service_namespace: serviceNamespace,
-        service_version: serviceVersion,
-        entity_uid,
+        ...scopeFilters,
       },
       bucket_interval: bucketInterval,
       selected_range: selectedRange,
diff --git a/crates/opsml_server/opsml_ui/src/routes/opsml/agent/[registry]/card/[space]/[name]/[version]/observability/__tests__/page.test.ts b/crates/opsml_server/opsml_ui/src/routes/opsml/agent/[registry]/card/[space]/[name]/[version]/observability/__tests__/page.test.ts
new file mode 100644
index 0000000000..5a5151c48a
--- /dev/null
+++ b/crates/opsml_server/opsml_ui/src/routes/opsml/agent/[registry]/card/[space]/[name]/[version]/observability/__tests__/page.test.ts
@@ -0,0 +1,115 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { RegistryType } from "$lib/utils";
+import { load } from "../+page";
+
+const traceCalls = vi.hoisted(() => ({
+  metrics: [] as unknown[],
+  page: [] as unknown[],
+  facets: [] as unknown[],
+}));
+
+vi.mock("$lib/components/trace/utils", async () => {
+  const actual = await vi.importActual<typeof import("$lib/components/trace/utils")>(
+    "$lib/components/trace/utils",
+  );
+  return {
+    ...actual,
+    getCookie: vi.fn(() => "15min"),
+    calculateTimeRange: vi.fn(() => ({
+      startTime: "2026-01-01T00:00:00Z",
+      endTime: "2026-01-02T00:00:00Z",
+      bucketInterval: "1 hours",
+    })),
+    getServerTraceMetrics: vi.fn(async (_fetch, body) => {
+      traceCalls.metrics.push(body);
+      return { metrics: [] };
+    }),
+    getServerTracePage: vi.fn(async (_fetch, body) => {
+      traceCalls.page.push(body);
+      return {
+        items: [
+          {
+            trace_id: "trace-1",
+            service_name: "support-agent",
+            scope: "SERVER",
+            root_operation: "agent.request",
+            start_time: "2026-01-01T00:00:00Z",
+            end_time: "2026-01-01T00:00:01Z",
+            duration_ms: 1000,
+            status_code: 1,
+            status_message: null,
+            span_count: 1,
+            has_errors: false,
+            error_count: 0,
+            created_at: "2026-01-01T00:00:00Z",
+            resource_attributes: [],
+          },
+        ],
+        has_next: false,
+        has_previous: false,
+      };
+    }),
+    getServerTraceFacets: vi.fn(async (_fetch, body) => {
+      traceCalls.facets.push(body);
+      return { services: [], status_codes: [], total_count: 0 };
+    }),
+  };
+});
+
+/** Builds the minimal SvelteKit load event used by route-scope tests. */
+function makeLoadCtx(metadata: Record<string, unknown>) {
+  return {
+    fetch: vi.fn(),
+    depends: vi.fn(),
+    parent: vi.fn().mockResolvedValue({
+      metadata,
+      devMockEnabled: false,
+    }),
+    url: new URL("http://localhost/opsml/agent/agent/card/default/support-agent/1.0.0/observability"),
+  } as unknown as Parameters<typeof load>[0];
+}
+
+describe("agent observability page load", () => {
+  beforeEach(() => {
+    traceCalls.metrics.length = 0;
+    traceCalls.page.length = 0;
+    traceCalls.facets.length = 0;
+  });
+
+  it("scopes agent cards with service identity clauses", async () => {
+    await load(makeLoadCtx({
+      registry_type: RegistryType.Agent,
+      name: "support-agent",
+      space: "prod",
+      version: "1.2.3",
+    }));
+
+    const expectedClause = {
+      op: "and",
+      value: [
+        { op: "service", value: "support-agent" },
+        { op: "service_namespace", value: "prod" },
+        { op: "service_version", value: "1.2.3" },
+      ],
+    };
+    expect(traceCalls.metrics[0]).toMatchObject({ clause: expectedClause });
+    expect(traceCalls.page[0]).toMatchObject({ clause: expectedClause });
+    expect(traceCalls.facets[0]).toMatchObject({ clause: expectedClause });
+    expect(traceCalls.metrics[0]).not.toHaveProperty("entity_uid");
+  });
+
+  it("scopes prompt cards with entity_uid and omits clause", async () => {
+    await load(makeLoadCtx({
+      registry_type: RegistryType.Prompt,
+      name: "triage-prompt",
+      space: "prod",
+      version: "1.2.3",
+      eval_profile: { config: { uid: "eval-profile-1" } },
+    }));
+
+    expect(traceCalls.metrics[0]).toMatchObject({ entity_uid: "eval-profile-1" });
+    expect(traceCalls.page[0]).toMatchObject({ entity_uid: "eval-profile-1" });
+    expect(traceCalls.facets[0]).toMatchObject({ entity_uid: "eval-profile-1" });
+    expect(traceCalls.metrics[0]).not.toHaveProperty("clause");
+  });
+});
diff --git a/crates/opsml_server/opsml_ui/src/routes/opsml/observability/+page.ts b/crates/opsml_server/opsml_ui/src/routes/opsml/observability/+page.ts
index 12513c656e..88bab582e2 100644
--- a/crates/opsml_server/opsml_ui/src/routes/opsml/observability/+page.ts
+++ b/crates/opsml_server/opsml_ui/src/routes/opsml/observability/+page.ts
@@ -27,7 +27,6 @@ export const load: PageLoad = async ({ fetch, depends, parent }) => {
       calculateTimeRange(selectedRange);
 
     const metricsRequest: TraceMetricsRequest = {
-      service_name: undefined,
       start_time: startTime,
       end_time: endTime,
       bucket_interval: bucketInterval,
@@ -51,7 +50,6 @@ export const load: PageLoad = async ({ fetch, depends, parent }) => {
       traceFacets = await getServerTraceFacets(fetch, {
         start_time: startTime,
         end_time: endTime,
-        service_name: undefined,
       });
     } catch (facetError) {
       console.warn("Failed to load trace facets:", facetError);
diff --git a/crates/opsml_server/tests/api/scouter/trace.rs b/crates/opsml_server/tests/api/scouter/trace.rs
index f6a1f16bf5..e28fa35a7d 100644
--- a/crates/opsml_server/tests/api/scouter/trace.rs
+++ b/crates/opsml_server/tests/api/scouter/trace.rs
@@ -5,17 +5,19 @@ use axum::{
 };
 use chrono::{Duration, Utc};
 use reqwest::header;
-use scouter_client::TraceMetricsRequest;
 
-fn trace_metrics_request() -> TraceMetricsRequest {
-    let end_time = Utc::now();
-    TraceMetricsRequest::new(
-        end_time - Duration::minutes(15),
-        end_time,
-        "hour".to_string(),
-        Some("entity-1".to_string()),
-        None,
-    )
+/// Representative clause-shaped trace filter body used to verify that the Rust
+/// proxy accepts and forwards the same JSON shape emitted by the OpsML UI.
+fn clause_filter_body() -> serde_json::Value {
+    serde_json::json!({
+        "clause": {
+            "op": "and",
+            "value": [
+                { "op": "service", "value": "checkout" },
+                { "op": "status_code", "value": 500 }
+            ]
+        }
+    })
 }
 
 fn scouter_error_body() -> &'static str {
@@ -25,7 +27,11 @@ fn scouter_error_body() -> &'static str {
 #[tokio::test]
 async fn test_scouter_routes_trace_paginated() {
     let mut helper = TestHelper::new(None).await;
-    let body = r#"{"limit":25}"#;
+    let body = serde_json::json!({
+        "limit": 25,
+        "clause": clause_filter_body()["clause"].clone(),
+    });
+    let body = serde_json::to_string(&body).unwrap();
 
     let _mock = helper
         .server
@@ -33,6 +39,13 @@ async fn test_scouter_routes_trace_paginated() {
         .mock("POST", "/scouter/trace/paginated")
         .match_body(mockito::Matcher::PartialJson(serde_json::json!({
             "limit": 25,
+            "clause": {
+                "op": "and",
+                "value": [
+                    { "op": "service", "value": "checkout" },
+                    { "op": "status_code", "value": 500 }
+                ]
+            }
         })))
         .with_status(200)
         .with_body(
@@ -82,7 +95,16 @@ async fn test_scouter_routes_trace_spans_query_forwarding() {
 #[tokio::test]
 async fn test_scouter_routes_trace_metrics() {
     let mut helper = TestHelper::new(None).await;
-    let body = serde_json::to_string(&trace_metrics_request()).unwrap();
+    let end_time = Utc::now();
+    let start_time = end_time - Duration::minutes(15);
+    let body = serde_json::json!({
+        "clause": clause_filter_body()["clause"].clone(),
+        "start_time": start_time.to_rfc3339(),
+        "end_time": end_time.to_rfc3339(),
+        "bucket_interval": "hour",
+        "entity_uid": "entity-1",
+    });
+    let body = serde_json::to_string(&body).unwrap();
 
     let _mock = helper
         .server
@@ -91,6 +113,13 @@ async fn test_scouter_routes_trace_metrics() {
         .match_body(mockito::Matcher::PartialJson(serde_json::json!({
             "bucket_interval": "hour",
             "entity_uid": "entity-1",
+            "clause": {
+                "op": "and",
+                "value": [
+                    { "op": "service", "value": "checkout" },
+                    { "op": "status_code", "value": 500 }
+                ]
+            }
         })))
         .with_status(200)
         .with_body(r#"{"metrics":[]}"#)
@@ -135,13 +164,21 @@ async fn test_scouter_routes_trace_spans_filters() {
 #[tokio::test]
 async fn test_scouter_routes_trace_facets() {
     let mut helper = TestHelper::new(None).await;
-    let body = r#"{"service_name":"svc-a"}"#;
+    let body = serde_json::to_string(&clause_filter_body()).unwrap();
 
     let _mock = helper
         .server
         .server
         .mock("POST", "/scouter/trace/facets")
-        .match_body(body)
+        .match_body(mockito::Matcher::PartialJson(serde_json::json!({
+            "clause": {
+                "op": "and",
+                "value": [
+                    { "op": "service", "value": "checkout" },
+                    { "op": "status_code", "value": 500 }
+                ]
+            }
+        })))
         .with_status(200)
         .with_body(r#"{"services":[],"status_codes":[],"total_count":0}"#)
         .create_async()
diff --git a/mise.toml b/mise.toml
index 0612775c7b..7b4439f59d 100644
--- a/mise.toml
+++ b/mise.toml
@@ -12,6 +12,16 @@ UI_DIR = "crates/opsml_server/opsml_ui"
 PY_DIR = "py-opsml"
 SOURCE_OBJECTS = "python/opsml"
 FORMAT_OBJECT = "python/opsml examples"
+SCOUTER_DIR = "../scouter"
+OPSML_E2E_DIR = "/tmp/opsml-e2e"
+OPSML_E2E_BACKEND_PORT = "8090"
+OPSML_E2E_FRONTEND_PORT = "3000"
+SCOUTER_HTTP_PORT = "8000"
+SCOUTER_GRPC_PORT = "50051"
+OPSML_E2E_TRACKING_URI = "http://localhost:8090"
+OPSML_E2E_SCOUTER_URI = "http://localhost:8000"
+OPSML_E2E_SCOUTER_GRPC_URI = "http://localhost:50051"
+OPSML_E2E_QUERY = "Recommend a vegan dinner with chickpeas and a dessert option"
 
 # Rust / workspace
 
@@ -309,41 +319,38 @@ run = "pnpm update"
 # Python tasks
 
 [tasks."py:format"]
-description = "Format Python code (isort + ruff + black)"
+description = "Format Python code with Ruff"
 dir = "py-opsml"
 run = [
-  "uv run isort python/opsml",
-  "uv run ruff check --silent --exit-zero python/opsml examples",
-  "uv run black python/opsml examples",
+  "uv run ruff format python/opsml examples",
+  "uv run ruff check --fix --exit-zero --silent python/opsml examples",
 ]
 
 [tasks."py:lints-ruff"]
-description = "Run Ruff"
+description = "Run Ruff lint checks"
 dir = "py-opsml"
 run = "uv run ruff check python/opsml"
 
-[tasks."py:lints-pylint"]
-description = "Run pylint"
+[tasks."py:typecheck"]
+description = "Run ty type checks"
 dir = "py-opsml"
-run = "uv run pylint python/opsml"
+run = "uv run ty check --ignore unused-type-ignore-comment python/opsml"
 
 [tasks."py:lints-ty"]
-description = "Run ty"
-dir = "py-opsml"
-run = "uv run ty check python/opsml"
+description = "Run ty type checks"
+depends = ["py:typecheck"]
 
 [tasks."py:lints"]
-description = "Run all Python linters"
-depends = ["py:lints-ruff", "py:lints-pylint", "py:lints-ty"]
+description = "Run Python Ruff lint checks and ty type checks"
+depends = ["py:lints-ruff", "py:typecheck"]
 
 [tasks."py:lints-ci"]
-description = "Run CI Python linters"
+description = "Run CI Python Ruff format/lint checks and ty type checks"
 dir = "py-opsml"
 run = [
-  "uv run black --check python/opsml",
+  "uv run ruff format --check python/opsml examples",
   "uv run ruff check python/opsml",
-  "uv run pylint python/opsml",
-  "uv run ty check python/opsml",
+  "uv run ty check --ignore unused-type-ignore-comment python/opsml",
 ]
 
 [tasks."py:build:stubs"]
@@ -351,9 +358,8 @@ description = "Regenerate Python type stubs from Rust bindings"
 dir = "py-opsml"
 run = [
   "uv run python scripts/assemble_stubs.py",
-  "uv run isort python/opsml",
-  "uv run black python/opsml examples",
-  "uv run ruff check --silent --exit-zero python/opsml examples",
+  "uv run ruff format python/opsml examples",
+  "uv run ruff check --fix --exit-zero --silent python/opsml examples",
 ]
 
 [tasks."py:setup"]
@@ -516,3 +522,182 @@ run = [
 description = "Upgrade all Python dependencies"
 dir = "py-opsml"
 run = "uv sync --upgrade --all-extras"
+
+# E2E Integration Harness
+# Scouter defaults to a sibling checkout at ../scouter.
+
+[tasks."dev:e2e:scouter:postgres"]
+description = "Start scouter postgres via docker compose"
+run = """
+mkdir -p $OPSML_E2E_DIR
+[ -f $OPSML_E2E_DIR/scouter-server.pid ] && kill $(cat $OPSML_E2E_DIR/scouter-server.pid) 2>/dev/null || true
+lsof -ti:$SCOUTER_HTTP_PORT | xargs kill -9 2>/dev/null || true
+lsof -ti:$SCOUTER_GRPC_PORT | xargs kill -9 2>/dev/null || true
+cd $SCOUTER_DIR && docker compose down -v
+cd $SCOUTER_DIR && docker compose up -d postgres --wait
+"""
+
+[tasks."dev:e2e:scouter:up"]
+description = "Build and start scouter-server in background"
+depends = ["dev:e2e:scouter:postgres"]
+run = """
+mkdir -p $OPSML_E2E_DIR
+cd $SCOUTER_DIR && cargo build -p scouter-server --all-features
+cd $SCOUTER_DIR
+DATABASE_URI=postgresql://postgres:postgres@localhost:5432/postgres \
+SCOUTER_TRACE_VISIBILITY_BUFFER_SECS=${SCOUTER_TRACE_VISIBILITY_BUFFER_SECS:-10} \
+SCOUTER_SERVER_PORT=$SCOUTER_HTTP_PORT \
+SCOUTER_GRPC_PORT=$SCOUTER_GRPC_PORT \
+nohup ./target/debug/scouter-server > $OPSML_E2E_DIR/scouter-server.log 2>&1 &
+SCOUTER_PID=$!
+disown $SCOUTER_PID
+echo $SCOUTER_PID > $OPSML_E2E_DIR/scouter-server.pid
+echo "Scouter started - PID: $(cat $OPSML_E2E_DIR/scouter-server.pid) - logs: $OPSML_E2E_DIR/scouter-server.log"
+"""
+
+[tasks."dev:e2e:opsml:backend"]
+description = "Build and start opsml-server in background on E2E backend port"
+env = { OPSML_TESTING = "1" }
+run = """
+mkdir -p $OPSML_E2E_DIR
+[ -f $OPSML_E2E_DIR/opsml-backend.pid ] && kill $(cat $OPSML_E2E_DIR/opsml-backend.pid) 2>/dev/null || true
+lsof -ti:$OPSML_E2E_BACKEND_PORT | xargs kill -9 2>/dev/null || true
+rm -f $OPSML_E2E_DIR/opsml.db $OPSML_E2E_DIR/opsml.db-wal $OPSML_E2E_DIR/opsml.db-shm
+rm -f $OPSML_E2E_DIR/opsml.lock
+rm -rf $OPSML_E2E_DIR/opsml_registries
+rm -rf $OPSML_E2E_DIR/opsml_service
+rm -f py-opsml/dev/integration/agent/opsml.lock
+rm -rf py-opsml/dev/integration/agent/opsml_service
+cargo build -p opsml-server
+OPSML_BACKEND_LOG=$OPSML_E2E_DIR/opsml-backend.log
+export OPSML_BACKEND_LOG
+OPSML_BACKEND_PID=$(python -c 'import os, subprocess
+log = open(os.environ["OPSML_BACKEND_LOG"], "ab")
+env = os.environ.copy()
+env.update({
+    "OPSML_SERVER_PORT": os.environ["OPSML_E2E_BACKEND_PORT"],
+    "OPSML_TRACKING_URI": "sqlite://" + os.environ["OPSML_E2E_DIR"] + "/opsml.db",
+    "OPSML_STORAGE_URI": os.environ["OPSML_E2E_DIR"] + "/opsml_registries",
+    "SCOUTER_SERVER_URI": os.environ["OPSML_E2E_SCOUTER_URI"],
+    "SCOUTER_GRPC_URI": os.environ["OPSML_E2E_SCOUTER_GRPC_URI"],
+})
+p = subprocess.Popen(["./target/debug/opsml-server"], stdin=subprocess.DEVNULL, stdout=log, stderr=subprocess.STDOUT, env=env, start_new_session=True)
+print(p.pid)')
+echo $OPSML_BACKEND_PID > $OPSML_E2E_DIR/opsml-backend.pid
+
+OPSML_BACKEND_URL=http://localhost:$OPSML_E2E_BACKEND_PORT/opsml/api/healthcheck
+OPSML_BACKEND_ATTEMPT=0
+while [ $OPSML_BACKEND_ATTEMPT -lt 60 ]; do
+  if ! kill -0 $OPSML_BACKEND_PID 2>/dev/null; then
+    echo "OpsML backend exited before readiness - PID: $OPSML_BACKEND_PID - logs: $OPSML_BACKEND_LOG"
+    tail -n 80 "$OPSML_BACKEND_LOG" 2>/dev/null || true
+    exit 1
+  fi
+  if curl -fsS --max-time 2 "$OPSML_BACKEND_URL" >/dev/null 2>&1; then
+    echo "OpsML backend started - PID: $OPSML_BACKEND_PID - logs: $OPSML_BACKEND_LOG"
+    exit 0
+  fi
+  OPSML_BACKEND_ATTEMPT=$((OPSML_BACKEND_ATTEMPT + 1))
+  sleep 1
+done
+
+echo "Timed out waiting for OpsML backend readiness at $OPSML_BACKEND_URL - PID: $OPSML_BACKEND_PID - logs: $OPSML_BACKEND_LOG"
+tail -n 80 "$OPSML_BACKEND_LOG" 2>/dev/null || true
+exit 1
+"""
+
+[tasks."dev:e2e:opsml:frontend"]
+description = "Start opsml frontend SvelteKit dev server in background"
+env = { OPSML_TESTING = "1" }
+run = """
+mkdir -p $OPSML_E2E_DIR
+cd $UI_DIR
+pnpm install
+OPSML_FRONTEND_LOG=$OPSML_E2E_DIR/opsml-frontend.log
+export OPSML_FRONTEND_LOG
+OPSML_FRONTEND_PID=$(python -c 'import os, subprocess
+log = open(os.environ["OPSML_FRONTEND_LOG"], "ab")
+env = os.environ.copy()
+env["OPSML_SERVER_PORT"] = os.environ["OPSML_E2E_BACKEND_PORT"]
+p = subprocess.Popen(["pnpm", "run", "dev"], stdin=subprocess.DEVNULL, stdout=log, stderr=subprocess.STDOUT, env=env, start_new_session=True)
+print(p.pid)')
+echo $OPSML_FRONTEND_PID > $OPSML_E2E_DIR/opsml-frontend.pid
+
+OPSML_FRONTEND_URL=http://localhost:$OPSML_E2E_FRONTEND_PORT
+OPSML_FRONTEND_ATTEMPT=0
+while [ $OPSML_FRONTEND_ATTEMPT -lt 60 ]; do
+  if ! kill -0 $OPSML_FRONTEND_PID 2>/dev/null; then
+    echo "OpsML frontend exited before readiness - PID: $OPSML_FRONTEND_PID - logs: $OPSML_FRONTEND_LOG"
+    tail -n 80 "$OPSML_FRONTEND_LOG" 2>/dev/null || true
+    exit 1
+  fi
+  if curl -fsS --max-time 2 "$OPSML_FRONTEND_URL" >/dev/null 2>&1; then
+    echo "OpsML frontend started - PID: $OPSML_FRONTEND_PID - logs: $OPSML_FRONTEND_LOG"
+    exit 0
+  fi
+  OPSML_FRONTEND_ATTEMPT=$((OPSML_FRONTEND_ATTEMPT + 1))
+  sleep 1
+done
+
+echo "Timed out waiting for OpsML frontend readiness at $OPSML_FRONTEND_URL - PID: $OPSML_FRONTEND_PID - logs: $OPSML_FRONTEND_LOG"
+tail -n 80 "$OPSML_FRONTEND_LOG" 2>/dev/null || true
+exit 1
+"""
+
+[tasks."dev:e2e:opsml:up"]
+description = "Start opsml backend + frontend in background"
+depends = ["dev:e2e:opsml:backend", "dev:e2e:opsml:frontend"]
+
+[tasks."dev:e2e:start:servers"]
+description = "Start Scouter and OpsML servers for E2E testing"
+depends = ["dev:e2e:scouter:up", "dev:e2e:opsml:up"]
+
+[tasks."dev:e2e:agent"]
+description = "Run one instrumented agent query"
+dir = "py-opsml"
+env = { OPSML_TESTING = "1" }
+run = """
+OPSML_TRACKING_URI=$OPSML_E2E_TRACKING_URI \
+OPSML_STORAGE_URI=$OPSML_E2E_DIR/opsml_registries \
+SCOUTER_SERVER_URI=$OPSML_E2E_SCOUTER_URI \
+SCOUTER_GRPC_URI=$OPSML_E2E_SCOUTER_GRPC_URI \
+uv run python -m dev.integration.agent.main "$OPSML_E2E_QUERY"
+"""
+
+[tasks."dev:e2e:agent:single"]
+description = "Run one online single-agent query"
+dir = "py-opsml"
+env = { OPSML_TESTING = "1" }
+run = """
+OPSML_TRACKING_URI=$OPSML_E2E_TRACKING_URI \
+OPSML_STORAGE_URI=$OPSML_E2E_DIR/opsml_registries \
+SCOUTER_SERVER_URI=$OPSML_E2E_SCOUTER_URI \
+SCOUTER_GRPC_URI=$OPSML_E2E_SCOUTER_GRPC_URI \
+uv run python -m dev.integration.agent.single "$OPSML_E2E_QUERY"
+"""
+
+[tasks."dev:e2e:smoke:offline"]
+description = "Run offline ADK agent evaluation"
+dir = "py-opsml"
+env = { OPSML_TESTING = "1", SCOUTER_OFFLINE = "1" }
+run = """
+OPSML_TRACKING_URI=$OPSML_E2E_TRACKING_URI \
+OPSML_STORAGE_URI=$OPSML_E2E_DIR/opsml_registries \
+SCOUTER_SERVER_URI=$OPSML_E2E_SCOUTER_URI \
+SCOUTER_GRPC_URI=$OPSML_E2E_SCOUTER_GRPC_URI \
+uv run python -m dev.integration.agent.evaluation.evaluate --check
+"""
+
+[tasks."dev:e2e:down"]
+description = "Teardown all E2E services"
+run = """
+[ -f $OPSML_E2E_DIR/opsml-frontend.pid ] && kill $(cat $OPSML_E2E_DIR/opsml-frontend.pid) 2>/dev/null || true
+[ -f $OPSML_E2E_DIR/opsml-backend.pid ] && kill $(cat $OPSML_E2E_DIR/opsml-backend.pid) 2>/dev/null || true
+[ -f $OPSML_E2E_DIR/scouter-server.pid ] && kill $(cat $OPSML_E2E_DIR/scouter-server.pid) 2>/dev/null || true
+rm -f $OPSML_E2E_DIR/*.pid
+lsof -ti:$OPSML_E2E_FRONTEND_PORT | xargs kill -9 2>/dev/null || true
+lsof -ti:$OPSML_E2E_BACKEND_PORT | xargs kill -9 2>/dev/null || true
+lsof -ti:$SCOUTER_HTTP_PORT | xargs kill -9 2>/dev/null || true
+lsof -ti:$SCOUTER_GRPC_PORT | xargs kill -9 2>/dev/null || true
+cd $SCOUTER_DIR && docker compose down
+"""
diff --git a/py-opsml/dev/integration/agent/__init__.py b/py-opsml/dev/integration/agent/__init__.py
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/py-opsml/dev/integration/agent/agents/__init__.py b/py-opsml/dev/integration/agent/agents/__init__.py
new file mode 100644
index 0000000000..b9078f1548
--- /dev/null
+++ b/py-opsml/dev/integration/agent/agents/__init__.py
@@ -0,0 +1,12 @@
+from .pipeline import build_root_agent, build_runner, run_agent_turn, run_query
+from .responder import build_responder_agent
+from .triage import build_triage_agent
+
+__all__ = [
+    "build_responder_agent",
+    "build_root_agent",
+    "build_runner",
+    "build_triage_agent",
+    "run_agent_turn",
+    "run_query",
+]
diff --git a/py-opsml/dev/integration/agent/agents/callbacks.py b/py-opsml/dev/integration/agent/agents/callbacks.py
new file mode 100644
index 0000000000..ff0894745d
--- /dev/null
+++ b/py-opsml/dev/integration/agent/agents/callbacks.py
@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+from dataclasses import asdict
+from typing import Any
+
+from google.adk.agents.callback_context import CallbackContext
+from google.adk.tools.base_tool import BaseTool
+from google.adk.tools.tool_context import ToolContext
+from opsml.scouter import trace
+
+from ..shared import AgentConfig, AttachedEval
+
+QUERY_STATE_KEY = "temp:query"
+TOOL_CALLS_STATE_KEY = "temp:tool_calls"
+TRIAGE_ROUTE_STATE_KEY = "temp:triage_route"
+TRIAGE_RESPONSE_STATE_KEY = "temp:triage_response"
+FINAL_RESPONSE_STATE_KEY = "temp:final_response"
+ATTACHED_EVALS_STATE_KEY = "temp:attached_evals"
+
+
+def capture_tool_call(
+    tool: BaseTool,
+    args: dict[str, Any],
+    tool_context: ToolContext,
+    tool_response: dict[str, Any],
+) -> dict[str, Any] | None:
+    tool_calls = list(tool_context.state.get(TOOL_CALLS_STATE_KEY, []))
+    tool_calls.append(
+        {
+            "name": tool.name,
+            "arguments": args,
+            "response": tool_response,
+        }
+    )
+    tool_context.state[TOOL_CALLS_STATE_KEY] = tool_calls
+    return None
+
+
+def tool_call_names(callback_context: CallbackContext) -> list[str]:
+    tool_calls = list(callback_context.state.get(TOOL_CALLS_STATE_KEY, []))
+    return [str(call.get("name", "")) for call in tool_calls]
+
+
+def tool_results(callback_context: CallbackContext) -> dict[str, Any]:
+    results: dict[str, Any] = {}
+    for call in callback_context.state.get(TOOL_CALLS_STATE_KEY, []):
+        if isinstance(call, dict) and isinstance(call.get("response"), dict):
+            results[str(call["name"])] = call["response"]
+    return results
+
+
+def agent_output(callback_context: CallbackContext, state_key: str) -> str:
+    return str(callback_context.state.get(state_key, ""))
+
+
+def session_id(callback_context: CallbackContext) -> str:
+    session = getattr(callback_context, "session", None)
+    if session is not None:
+        return str(getattr(session, "id", ""))
+    return ""
+
+
+def record_id(
+    callback_context: CallbackContext,
+    agent_name: str,
+    *,
+    run_id: str = "",
+    session_id_value: str = "",
+) -> str:
+    return ":".join(
+        part
+        for part in [
+            run_id,
+            session_id_value,
+            agent_name,
+            str(callback_context.invocation_id),
+        ]
+        if part
+    )
+
+
+def attach_agent_eval(
+    callback_context: CallbackContext,
+    *,
+    config: AgentConfig,
+    agent_name: str,
+    profile_uid: str,
+    context: dict[str, Any],
+    span_name: str,
+    tracer_name: str,
+) -> None:
+    tracer = trace.get_tracer(tracer_name)
+    state = callback_context.state
+    with tracer.start_as_current_span(span_name) as span:
+        attached_session_id = session_id(callback_context)
+        attached_record_id = record_id(
+            callback_context,
+            agent_name,
+            run_id=config.run_id,
+            session_id_value=attached_session_id,
+        )
+        span.attach_eval(
+            profile_uid=profile_uid,
+            context=context,
+            record_id=attached_record_id,
+            session_id=attached_session_id,
+            tags=[
+                "source=google_adk",
+                f"agent={agent_name}",
+                f"run_id={config.run_id}",
+            ],
+        )
+        attached_eval = AttachedEval(
+            run_id=config.run_id,
+            agent_name=agent_name,
+            profile_uid=profile_uid,
+            record_id=attached_record_id,
+            session_id=attached_session_id,
+            trace_id=span.trace_id,
+            span_id=span.span_id,
+        )
+        evals = list(state.get(ATTACHED_EVALS_STATE_KEY, []))
+        evals.append(asdict(attached_eval))
+        state[ATTACHED_EVALS_STATE_KEY] = evals
+        config.record_attached_eval(attached_eval)
diff --git a/py-opsml/dev/integration/agent/agents/pipeline.py b/py-opsml/dev/integration/agent/agents/pipeline.py
new file mode 100644
index 0000000000..2894529e94
--- /dev/null
+++ b/py-opsml/dev/integration/agent/agents/pipeline.py
@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import asyncio
+
+from google.adk.agents import SequentialAgent
+from google.adk.runners import Runner, RunConfig
+from google.adk.sessions import InMemorySessionService
+from google.genai import types
+from opsml.scouter import trace
+
+from ..shared import APP_NAME, AgentConfig, get_shared_config
+from .callbacks import (
+    QUERY_STATE_KEY,
+    TOOL_CALLS_STATE_KEY,
+)
+from .responder import build_responder_agent
+from .triage import build_triage_agent
+
+ROOT_AGENT_NAME = "opsml_e2e_support_pipeline"
+# Expected path is 4 LLM calls. Budget 6 allows one repair turn without masking loops.
+MAX_LLM_CALLS_PER_TURN = 6
+
+
+def build_root_agent(config: AgentConfig | None = None) -> SequentialAgent:
+    active_config = config or get_shared_config()
+    return SequentialAgent(
+        name=ROOT_AGENT_NAME,
+        sub_agents=[
+            build_triage_agent(active_config),
+            build_responder_agent(active_config),
+        ],
+    )
+
+
+def build_runner(
+    config: AgentConfig | None = None,
+) -> tuple[Runner, InMemorySessionService]:
+    active_config = config or get_shared_config()
+    session_service = InMemorySessionService()
+    runner = Runner(
+        agent=build_root_agent(active_config),
+        app_name=APP_NAME,
+        session_service=session_service,
+    )
+    return runner, session_service
+
+
+async def run_agent_turn(
+    runner: Runner,
+    session_service: InMemorySessionService,
+    *,
+    query: str,
+    user_id: str = "e2e_user",
+) -> str:
+    tracer = trace.get_tracer("opsml_e2e_agent.request")
+    response = ""
+    with tracer.start_as_current_span("agent.request") as span:
+        session = await session_service.create_session(
+            app_name=APP_NAME,
+            user_id=user_id,
+            state={
+                QUERY_STATE_KEY: query,
+                TOOL_CALLS_STATE_KEY: [],
+            },
+        )
+        message = types.Content(role="user", parts=[types.Part(text=query)])
+        span.set_attribute("adk.session_id", session.id)
+        span.set_attribute("adk.user_id", user_id)
+        span.set_attribute("agent.query", query)
+        async for event in runner.run_async(
+            user_id=user_id,
+            session_id=session.id,
+            new_message=message,
+            run_config=RunConfig(max_llm_calls=MAX_LLM_CALLS_PER_TURN),
+        ):
+            if event.is_final_response() and event.content and event.content.parts:
+                response = "".join(part.text or "" for part in event.content.parts)
+
+    return response
+
+
+def run_query(query: str) -> str:
+    config = get_shared_config()
+    config.begin_run()
+    runner, session_service = build_runner(config)
+    return asyncio.run(run_agent_turn(runner, session_service, query=query))
diff --git a/py-opsml/dev/integration/agent/agents/responder.py b/py-opsml/dev/integration/agent/agents/responder.py
new file mode 100644
index 0000000000..90d8a6bf4d
--- /dev/null
+++ b/py-opsml/dev/integration/agent/agents/responder.py
@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+from typing import Any
+
+from google.adk.agents import Agent
+from google.adk.agents.callback_context import CallbackContext
+from google.adk.agents.readonly_context import ReadonlyContext
+from google.adk.tools.tool_context import ToolContext
+from google.genai import types
+from opsml.scouter import trace
+
+from ..shared import AgentConfig, get_shared_config
+from .callbacks import (
+    FINAL_RESPONSE_STATE_KEY,
+    QUERY_STATE_KEY,
+    TOOL_CALLS_STATE_KEY,
+    TRIAGE_ROUTE_STATE_KEY,
+    agent_output,
+    attach_agent_eval,
+    capture_tool_call,
+    tool_call_names,
+    tool_results,
+)
+
+RESPONDER_AGENT_NAME = "responder_agent"
+
+
+def plan_weeknight_dinner(query: str, tool_context: ToolContext) -> dict[str, Any]:
+    """Build a simple weeknight dinner plan for dinner-routed requests."""
+    tracer = trace.get_tracer("opsml_e2e_agent.tools")
+    with tracer.start_as_current_span("tool.plan_weeknight_dinner") as span:
+        span.set_attribute("tool.name", "plan_weeknight_dinner")
+        span.set_attribute("tool.query", query)
+        return {
+            "status": "success",
+            "route": "dinner",
+            "query": query,
+            "ingredients": ["protein", "vegetable", "starch"],
+            "next_step": "Choose one ingredient from each category, then build a short prep sequence.",
+        }
+
+
+def debug_api_timeout(query: str, tool_context: ToolContext) -> dict[str, Any]:
+    """Return focused troubleshooting checks for timeout-routed requests."""
+    tracer = trace.get_tracer("opsml_e2e_agent.tools")
+    with tracer.start_as_current_span("tool.debug_api_timeout") as span:
+        span.set_attribute("tool.name", "debug_api_timeout")
+        span.set_attribute("tool.query", query)
+        return {
+            "status": "success",
+            "route": "timeout",
+            "query": query,
+            "checks": ["timeout values", "retry policy", "dependency latency"],
+            "next_step": "Check timeout values, retry policy, and dependency latency.",
+        }
+
+
+def build_responder_agent(config: AgentConfig | None = None) -> Agent:
+    active_config = config or get_shared_config()
+
+    def instruction(context: ReadonlyContext) -> str:
+        query = context.state.get(QUERY_STATE_KEY, "")
+        triage_route = context.state.get(TRIAGE_ROUTE_STATE_KEY, "")
+        return "\n\n".join(
+            [
+                active_config.prompts.responder.prompt.message.text,
+                f"Current user query: {query}",
+                f"Triage route: {triage_route}",
+                (
+                    "Use the triage route to choose one tool: plan_weeknight_dinner "
+                    "for route 'dinner', or debug_api_timeout for route 'timeout'. "
+                    "Call exactly one route tool and do not transfer to another agent."
+                ),
+            ]
+        )
+
+    return Agent(
+        name=RESPONDER_AGENT_NAME,
+        model=active_config.prompts.responder.prompt.model,
+        description="Calls the routed domain tool and produces the final answer.",
+        instruction=instruction,
+        output_key=FINAL_RESPONSE_STATE_KEY,
+        tools=[plan_weeknight_dinner, debug_api_timeout],
+        disallow_transfer_to_parent=True,
+        disallow_transfer_to_peers=True,
+        after_tool_callback=capture_tool_call,
+        after_agent_callback=lambda callback_context: _after_responder_agent(
+            callback_context,
+            active_config,
+        ),
+    )
+
+
+def _after_responder_agent(
+    callback_context: CallbackContext,
+    config: AgentConfig,
+) -> types.Content | None:
+    state = callback_context.state
+    names = tool_call_names(callback_context)
+    results = tool_results(callback_context)
+    response = agent_output(callback_context, FINAL_RESPONSE_STATE_KEY)
+    if not response:
+        response = next(
+            (
+                str(result.get("next_step", ""))
+                for name, result in results.items()
+                if name in {"plan_weeknight_dinner", "debug_api_timeout"}
+                and isinstance(result, dict)
+            ),
+            "",
+        )
+        state[FINAL_RESPONSE_STATE_KEY] = response
+
+    context = {
+        "query": str(state.get(QUERY_STATE_KEY, "")),
+        "response": response,
+        "final_response": response,
+        "tool_call_names": names,
+        "tool_call_path": " -> ".join(names),
+        "tool_call_trajectory": " -> ".join(names),
+        "tool_calls": list(state.get(TOOL_CALLS_STATE_KEY, [])),
+        "tool_results": results,
+        "triage_route": str(state.get(TRIAGE_ROUTE_STATE_KEY, "")),
+    }
+
+    attach_agent_eval(
+        callback_context,
+        config=config,
+        agent_name=RESPONDER_AGENT_NAME,
+        profile_uid=config.responder.eval_profile.config.uid,
+        context=context,
+        span_name="responder.callback",
+        tracer_name="opsml_e2e_agent.responder",
+    )
+
+    return None
diff --git a/py-opsml/dev/integration/agent/agents/triage.py b/py-opsml/dev/integration/agent/agents/triage.py
new file mode 100644
index 0000000000..f5e6f7f697
--- /dev/null
+++ b/py-opsml/dev/integration/agent/agents/triage.py
@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from typing import Any
+
+from google.adk.agents import Agent
+from google.adk.agents.callback_context import CallbackContext
+from google.adk.agents.readonly_context import ReadonlyContext
+from google.adk.tools.tool_context import ToolContext
+from google.genai import types
+from opsml.scouter import trace
+
+from ..shared import AgentConfig, get_shared_config
+from .callbacks import (
+    QUERY_STATE_KEY,
+    TOOL_CALLS_STATE_KEY,
+    TRIAGE_ROUTE_STATE_KEY,
+    TRIAGE_RESPONSE_STATE_KEY,
+    agent_output,
+    attach_agent_eval,
+    capture_tool_call,
+    tool_call_names,
+    tool_results,
+)
+
+TRIAGE_AGENT_NAME = "triage_agent"
+
+
+def classify_request(query: str, tool_context: ToolContext) -> dict[str, Any]:
+    """Classify the support request into the route used by the responder."""
+    tracer = trace.get_tracer("opsml_e2e_agent.tools")
+    lowered = query.lower()
+    route = "timeout" if "timeout" in lowered or "times out" in lowered else "dinner"
+    tool_context.state[TRIAGE_ROUTE_STATE_KEY] = route
+    with tracer.start_as_current_span("tool.classify_request") as span:
+        span.set_attribute("tool.name", "classify_request")
+        span.set_attribute("tool.query", query)
+        span.set_attribute("tool.route", route)
+        return {"status": "success", "query": query, "route": route}
+
+
+def build_triage_agent(config: AgentConfig | None = None) -> Agent:
+    active_config = config or get_shared_config()
+
+    def instruction(context: ReadonlyContext) -> str:
+        query = context.state.get(QUERY_STATE_KEY, "")
+        return "\n\n".join(
+            [
+                active_config.prompts.triage.prompt.message.text,
+                f"Current user query: {query}",
+                "Call classify_request exactly once. Do not transfer to another agent.",
+            ]
+        )
+
+    return Agent(
+        name=TRIAGE_AGENT_NAME,
+        model=active_config.prompts.triage.prompt.model,
+        description="Classifies the user request into the next support route.",
+        instruction=instruction,
+        output_key=TRIAGE_RESPONSE_STATE_KEY,
+        tools=[classify_request],
+        disallow_transfer_to_parent=True,
+        disallow_transfer_to_peers=True,
+        after_tool_callback=capture_tool_call,
+        after_agent_callback=lambda callback_context: _after_triage_agent(
+            callback_context,
+            active_config,
+        ),
+    )
+
+
+def _after_triage_agent(
+    callback_context: CallbackContext,
+    config: AgentConfig,
+) -> types.Content | None:
+    state = callback_context.state
+    results = tool_results(callback_context)
+    triage_route = str(state.get(TRIAGE_ROUTE_STATE_KEY, ""))
+
+    names = tool_call_names(callback_context)
+    response = agent_output(callback_context, TRIAGE_RESPONSE_STATE_KEY)
+    if not response and triage_route:
+        response = f"The request is routed to {triage_route}."
+    context = {
+        "query": str(state.get(QUERY_STATE_KEY, "")),
+        "response": response,
+        "tool_call_names": names,
+        "tool_call_path": " -> ".join(names),
+        "tool_call_trajectory": " -> ".join(names),
+        "tool_calls": list(state.get(TOOL_CALLS_STATE_KEY, [])),
+        "tool_results": results,
+        "triage_route": triage_route,
+    }
+
+    attach_agent_eval(
+        callback_context,
+        config=config,
+        agent_name=TRIAGE_AGENT_NAME,
+        profile_uid=config.triage.eval_profile.config.uid,
+        context=context,
+        span_name="triage.callback",
+        tracer_name="opsml_e2e_agent.triage",
+    )
+
+    return None
diff --git a/py-opsml/dev/integration/agent/evaluation/__init__.py b/py-opsml/dev/integration/agent/evaluation/__init__.py
new file mode 100644
index 0000000000..427060801f
--- /dev/null
+++ b/py-opsml/dev/integration/agent/evaluation/__init__.py
@@ -0,0 +1,18 @@
+from typing import Any
+
+
+def run_offline_evaluation() -> Any:
+    from .evaluate import run_offline_evaluation as _run_offline_evaluation
+
+    return _run_offline_evaluation()
+
+
+def __getattr__(name: str) -> Any:
+    if name == "GoogleAdkEvalOrchestrator":
+        from .evaluate import GoogleAdkEvalOrchestrator
+
+        return GoogleAdkEvalOrchestrator
+    raise AttributeError(name)
+
+
+__all__ = ["GoogleAdkEvalOrchestrator", "run_offline_evaluation"]
diff --git a/py-opsml/dev/integration/agent/evaluation/evaluate.py b/py-opsml/dev/integration/agent/evaluation/evaluate.py
new file mode 100644
index 0000000000..4432a8e6be
--- /dev/null
+++ b/py-opsml/dev/integration/agent/evaluation/evaluate.py
@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import contextvars
+from collections.abc import Coroutine
+from pathlib import Path
+from typing import Any
+
+from opsml.scouter.evaluate import (
+    EvalOrchestrator,
+    EvalScenario,
+    EvalScenarios,
+    ScenarioEvalResults,
+)
+from opsml.scouter.transport import MockConfig
+
+from ..agents import build_runner, run_agent_turn
+from ..shared import get_shared_config, teardown
+from .user_agent import SimulatedUserAgent
+
+_SCENARIOS_PATH = Path(__file__).resolve().parent.parent / "shared" / "scenarios.jsonl"
+
+
+class GoogleAdkEvalOrchestrator(EvalOrchestrator):
+    def __init__(self) -> None:
+        self._config = get_shared_config(transport_config=MockConfig(), register=False)
+        self._config.begin_run()
+        self._runner = asyncio.Runner()
+        self._sim_user = SimulatedUserAgent(
+            config=self._config, run_sync=self._run_sync
+        )
+        self._adk_runner, self._session_service = build_runner(self._config)
+        super().__init__(
+            queue=self._config.app.queue,
+            scenarios=EvalScenarios.from_path(_SCENARIOS_PATH),
+            simulated_user_fn=self._sim_user.turn_factory("__default__"),
+        )
+
+    def _run_sync(self, coro: Coroutine[Any, Any, str]) -> str:
+        return self._runner.run(coro, context=contextvars.copy_context())
+
+    def execute_agent_turn(self, scenario: EvalScenario, message: str) -> str:
+        self._simulated_user_fn = self._sim_user.turn_factory(scenario.id)
+        return self._run_sync(
+            run_agent_turn(
+                self._adk_runner,
+                self._session_service,
+                query=message,
+                user_id="eval_user",
+            )
+        )
+
+    def close(self) -> None:
+        self._sim_user.close()
+        self._runner.close()
+
+
+def run_offline_evaluation() -> ScenarioEvalResults:
+    orchestrator = GoogleAdkEvalOrchestrator()
+    try:
+        return orchestrator.run()
+    finally:
+        orchestrator.close()
+        teardown()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Run offline ADK agent evaluation.")
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Exit non-zero if any offline evaluation scenario fails.",
+    )
+    args = parser.parse_args()
+
+    results = run_offline_evaluation()
+    print(
+        f"\nScenarios : {results.metrics.total_scenarios}  "
+        f"Passed    : {results.metrics.passed_scenarios}  "
+        f"Pass rate : {results.metrics.overall_pass_rate:.0%}"
+    )
+    results.as_table(show_workflow=True)
+    results.agent_summary_table()
+
+    print("\nDetail for 'plan_weeknight_dinner':")
+    detail = results.get_scenario_detail("plan_weeknight_dinner")
+    detail.traces_as_table()
+    detail.tasks_as_table()
+    detail.agent_results_as_table(show_tasks=True)
+
+    print("Spans --------------------------------")
+    spans = detail.traces
+    for span in spans:
+        print(
+            "parent:",
+            span.parent_span_id,
+            "id:",
+            span.span_id,
+            "name:",
+            span.span_name,
+            "depth:",
+            span.depth,
+        )
+    print("-------------------------------------")
+
+    if (
+        args.check
+        and results.metrics.passed_scenarios != results.metrics.total_scenarios
+    ):
+        raise SystemExit(
+            "Offline evaluation failed: "
+            f"{results.metrics.passed_scenarios}/"
+            f"{results.metrics.total_scenarios} scenarios passed"
+        )
+
+    print("\nDetail for 'debug_api_timeout':")
+    detail = results.get_scenario_detail("debug_api_timeout")
+    detail.traces_as_table()
+    detail.tasks_as_table()
+    detail.agent_results_as_table(show_tasks=True)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/py-opsml/dev/integration/agent/evaluation/user_agent.py b/py-opsml/dev/integration/agent/evaluation/user_agent.py
new file mode 100644
index 0000000000..0391d91a9c
--- /dev/null
+++ b/py-opsml/dev/integration/agent/evaluation/user_agent.py
@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable, Coroutine
+from typing import Any
+
+from google.adk.agents import Agent
+from google.adk.runners import Runner
+from google.adk.sessions import InMemorySessionService
+from google.genai import types
+
+from ..shared import AgentConfig
+
+_SIM_USER_NAME = "simulated_user"
+_SIM_USER_APP_NAME = "opsml_e2e_simulated_user"
+
+
+def _instruction(persona: str) -> str:
+    return (
+        f"You are simulating a user with this persona: {persona}.\n"
+        "Read the conversation history. Reply as the user would in one short paragraph.\n"
+        "When the agent's most recent answer fully addresses your goal, end your reply with DONE.\n"
+        "If you still need clarification or a follow-up, do not include DONE.\n"
+    )
+
+
+class SimulatedUserAgent:
+    def __init__(
+        self,
+        config: AgentConfig,
+        persona: str = "a curious data scientist",
+        *,
+        run_sync: Callable[[Coroutine[Any, Any, str]], str] | None = None,
+    ) -> None:
+        self._agent = Agent(
+            name=_SIM_USER_NAME,
+            model=config.prompts.responder.prompt.model,
+            description="Simulates a user driving the agent under evaluation.",
+            instruction=_instruction(persona),
+        )
+        self._session_service = InMemorySessionService()
+        self._runner = Runner(
+            agent=self._agent,
+            app_name=_SIM_USER_APP_NAME,
+            session_service=self._session_service,
+        )
+        if run_sync:
+            self._owned_async_runner = None
+            self._run_sync = run_sync
+        else:
+            self._owned_async_runner = asyncio.Runner()
+            self._run_sync = self._owned_async_runner.run
+        self._sessions: dict[str, str] = {}
+
+    async def _ensure_session(self, scenario_id: str) -> str:
+        if scenario_id in self._sessions:
+            return self._sessions[scenario_id]
+        session = await self._session_service.create_session(
+            app_name=_SIM_USER_APP_NAME,
+            user_id=f"sim_user::{scenario_id}",
+            state={},
+        )
+        self._sessions[scenario_id] = session.id
+        return session.id
+
+    async def _turn_async(self, scenario_id: str, agent_response: Any) -> str:
+        session_id = await self._ensure_session(scenario_id)
+        message = types.Content(
+            role="user", parts=[types.Part(text=str(agent_response))]
+        )
+        last_text = ""
+        try:
+            async for event in self._runner.run_async(
+                user_id=f"sim_user::{scenario_id}",
+                session_id=session_id,
+                new_message=message,
+            ):
+                if event.is_final_response() and event.content and event.content.parts:
+                    for part in event.content.parts:
+                        if part.text:
+                            last_text = part.text
+        except Exception:
+            return "DONE"
+        return last_text or "DONE"
+
+    def turn_factory(
+        self, scenario_id: str
+    ) -> Callable[[str, Any, list[dict[str, Any]]], str]:
+        def _turn(
+            initial_query: str,
+            agent_response: Any,
+            history: list[dict[str, Any]],
+        ) -> str:
+            del initial_query, history
+            return self._run_sync(self._turn_async(scenario_id, agent_response))
+
+        return _turn
+
+    def close(self) -> None:
+        if self._owned_async_runner:
+            self._owned_async_runner.close()
diff --git a/py-opsml/dev/integration/agent/main.py b/py-opsml/dev/integration/agent/main.py
new file mode 100644
index 0000000000..de7fc9b2ff
--- /dev/null
+++ b/py-opsml/dev/integration/agent/main.py
@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+
+os.environ.setdefault("OPSML_TRACKING_URI", "http://localhost:8090")
+os.environ.setdefault("SCOUTER_SERVER_URI", "http://localhost:8000")
+os.environ.setdefault("SCOUTER_GRPC_URI", "http://localhost:50051")
+
+from opsml.logging import LoggingConfig, RustyLogger
+
+from .agents import build_runner, run_agent_turn, run_query
+from .setup import AgentConfig, teardown
+
+logger = RustyLogger.get_logger(LoggingConfig.default())
+
+
+def run_queries(config: AgentConfig, queries: list[str]) -> list[str]:
+    config.begin_run()
+    responses: list[str] = []
+    for query in queries:
+        runner, session_service = build_runner(config)
+        responses.append(
+            asyncio.run(
+                run_agent_turn(
+                    runner,
+                    session_service,
+                    query=query,
+                )
+            )
+        )
+    return responses
+
+
+async def run_queries_async(config: AgentConfig, queries: list[str]) -> list[str]:
+    config.begin_run()
+    responses: list[str] = []
+    for query in queries:
+        runner, session_service = build_runner(config)
+        responses.append(
+            await run_agent_turn(
+                runner,
+                session_service,
+                query=query,
+            )
+        )
+    return responses
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Run E2E support agent.")
+    parser.add_argument(
+        "query",
+        nargs="?",
+        default="Help me plan a weeknight dinner with ingredients and steps.",
+    )
+    args = parser.parse_args()
+
+    try:
+        response = run_query(args.query)
+        print(response)
+    finally:
+        teardown()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/py-opsml/dev/integration/agent/opsmlspec.yaml b/py-opsml/dev/integration/agent/opsmlspec.yaml
new file mode 100644
index 0000000000..60e82c9cef
--- /dev/null
+++ b/py-opsml/dev/integration/agent/opsmlspec.yaml
@@ -0,0 +1,48 @@
+name: "support-e2e-agent"
+space: "scouter_dev"
+type: Agent
+
+metadata:
+  description: "Local E2E support agent for OpsML and Scouter integration inspection"
+  language: "python"
+  tags: ["e2e", "scouter", "agent", "support"]
+
+service:
+  cards:
+    - alias: triage_prompt
+      path: "prompts/triage.yaml"
+      registry_type: prompt
+    - alias: responder_prompt
+      path: "prompts/responder.yaml"
+      registry_type: prompt
+
+  agent:
+    version: "0.3.0"
+    capabilities:
+      streaming: false
+      push_notifications: false
+      extended_agent_card: false
+    default_output_modes: ["text/plain"]
+    default_input_modes: ["text/plain"]
+    description: "Sequential triage -> responder support pipeline used for E2E integration checks."
+    name: "Support E2E Agent"
+    skills:
+      - format: a2a
+        id: "support_e2e"
+        name: "Support E2E"
+        description: "Routes support requests and composes the final answer."
+        input_modes: ["text/plain"]
+        output_modes: ["text/plain"]
+        tags: ["support", "e2e"]
+        examples:
+          - "Help me plan a weeknight dinner"
+          - "My API call times out intermittently"
+    supported_interfaces:
+      - protocol_binding: "HTTP+JSON"
+        protocol_version: "0.3.0"
+        url: "http://localhost:8888"
+
+deploy:
+  - environment: "development"
+    urls: ["http://localhost:8888"]
+    healthcheck: "/health"
diff --git a/py-opsml/dev/integration/agent/prompts/responder.yaml b/py-opsml/dev/integration/agent/prompts/responder.yaml
new file mode 100644
index 0000000000..eb592b60c3
--- /dev/null
+++ b/py-opsml/dev/integration/agent/prompts/responder.yaml
@@ -0,0 +1,100 @@
+space: scouter_dev
+name: responder_prompt
+prompt:
+  model: gemini-3.1-flash-lite-preview
+  provider: Gemini
+  messages:
+    - "You are the responder agent in a multi-agent pipeline. The triage agent already classified the request into route 'dinner' or 'timeout'. If the user asks about dinner, call plan_weeknight_dinner exactly once. If the user asks about API timeout or latency, call debug_api_timeout exactly once. Use the tool result to write a concise final answer."
+evaluation:
+  alias: responder_evaluation
+  config:
+    sample_ratio: 1.0
+    alert_config:
+      dispatch_config:
+        Slack:
+          channel: "#ai-platform"
+      schedule: "0 0 * * * *"
+      alert_condition:
+        baseline_value: 0.8
+        alert_threshold: Below
+        delta: null
+  tasks:
+    - task_type: Assertion
+      id: responder_response_is_string
+      context_path: response
+      operator: IsString
+      expected_value: true
+      description: Validate that the responder produced a string response.
+
+    - task_type: Assertion
+      id: responder_tool_called
+      context_path: tool_call_names
+      operator: ContainsAny
+      expected_value: ["plan_weeknight_dinner", "debug_api_timeout"]
+      description: Validate that the responder invoked exactly one route-specific tool.
+
+    - task_type: Assertion
+      id: responder_tool_path_matches
+      context_path: tool_call_path
+      operator: MatchesRegex
+      expected_value: "^classify_request -> (plan_weeknight_dinner|debug_api_timeout)$"
+      description: Validate the full tool path across triage and responder.
+      depends_on: ["responder_tool_called"]
+
+    - task_type: LLMJudge
+      id: responder_answer_judge
+      context_path: score
+      operator: Equals
+      expected_value: 1
+      description: Judge whether the responder answer is useful for the routed request.
+      max_retries: 3
+      prompt:
+        model: gemini-3.1-flash-lite-preview
+        provider: Google
+        messages:
+          - |
+            Analyze the responder answer and determine if it effectively addresses the user's routed request.
+            Respond with 1 if the response is high quality and effectively addresses the user's question, and 0 if it does not.
+
+            User's question: ${query}
+            Route: ${triage_route}
+            Agent's response: ${response}
+        settings:
+          generation_config:
+            thinking_config:
+              thinking_budget: 0
+        response_format:
+          title: EvaluationResponse
+          type: object
+          properties:
+            score:
+              type: integer
+              minimum: 0
+              maximum: 1
+            reason:
+              type: string
+          required: ["score", "reason"]
+          additionalProperties: false
+
+    - task_type: TraceAssertion
+      id: responder_tool_span_emitted
+      operator: GreaterThanOrEqual
+      expected_value: 1
+      description: Validate that one route-specific responder tool span executed.
+      assertion:
+        SpanCount:
+          filter:
+            Or:
+              filters:
+                - ByName:
+                    name: tool.plan_weeknight_dinner
+                - ByName:
+                    name: tool.debug_api_timeout
+
+    - task_type: TraceAssertion
+      id: responder_latency_budget
+      operator: LessThan
+      expected_value: 7000.0
+      description: Responder should finish under 7 seconds.
+      assertion:
+        TraceDuration: {}
diff --git a/py-opsml/dev/integration/agent/prompts/triage.yaml b/py-opsml/dev/integration/agent/prompts/triage.yaml
new file mode 100644
index 0000000000..c641b0077f
--- /dev/null
+++ b/py-opsml/dev/integration/agent/prompts/triage.yaml
@@ -0,0 +1,88 @@
+space: scouter_dev
+name: triage_prompt
+prompt:
+  model: gemini-3.1-flash-lite-preview
+  provider: Gemini
+  messages:
+    - "You are the triage agent in a multi-agent pipeline. Call classify_request exactly once with the user's query. classify_request returns a route field with value 'dinner' or 'timeout'. Do not produce any other tool call. Reply with a single short sentence acknowledging the route; the responder agent will handle the user-facing answer."
+evaluation:
+  alias: triage_evaluation
+  config:
+    sample_ratio: 1.0
+    alert_config:
+      dispatch_config:
+        Slack:
+          channel: "#ai-platform"
+      schedule: "0 0 * * * *"
+      alert_condition:
+        baseline_value: 0.8
+        alert_threshold: Below
+        delta: null
+  tasks:
+    - task_type: Assertion
+      id: classify_request_tool_called
+      context_path: tool_call_names
+      operator: Contains
+      expected_value: classify_request
+      description: Validate that the triage agent invoked classify_request.
+
+    - task_type: Assertion
+      id: triage_route_valid
+      context_path: triage_route
+      operator: ContainsAny
+      expected_value: ["dinner", "timeout"]
+      description: Validate that classify_request produced a recognised route.
+
+    - task_type: LLMJudge
+      id: triage_response_judge
+      context_path: score
+      operator: Equals
+      expected_value: 1
+      description: Judge whether the triage response correctly acknowledges the route.
+      max_retries: 3
+      prompt:
+        model: gemini-3.1-flash-lite-preview
+        provider: Google
+        messages:
+          - |
+            Analyze the triage response and determine if it correctly acknowledges the route without answering the user's request directly.
+            Respond with 1 if the response is high quality and correctly acknowledges the route, and 0 if it does not.
+
+            User's question: ${query}
+            Route: ${triage_route}
+            Triage response: ${response}
+        settings:
+          generation_config:
+            thinking_config:
+              thinking_budget: 0
+        response_format:
+          title: EvaluationResponse
+          type: object
+          properties:
+            score:
+              type: integer
+              minimum: 0
+              maximum: 1
+            reason:
+              type: string
+          required: ["score", "reason"]
+          additionalProperties: false
+
+    - task_type: TraceAssertion
+      id: classify_tool_span_emitted
+      operator: GreaterThanOrEqual
+      expected_value: 1
+      description: Validate that the span-backed classify_request tool executed.
+      assertion:
+        SpanCount:
+          filter:
+            ByName:
+              name: tool.classify_request
+
+    - task_type: TraceAssertion
+      id: triage_latency_budget
+      operator: LessThan
+      expected_value: 10000.0
+      description: Triage should complete within the live integration budget.
+      assertion:
+        TraceDuration: {}
diff --git a/py-opsml/dev/integration/agent/setup.py b/py-opsml/dev/integration/agent/setup.py
new file mode 100644
index 0000000000..9f2148a1e4
--- /dev/null
+++ b/py-opsml/dev/integration/agent/setup.py
@@ -0,0 +1,22 @@
+from .shared.setup import (
+    APP_NAME,
+    AgentConfig,
+    AttachedEval,
+    PromptSpec,
+    TransportConfig,
+    get_shared_config,
+    teardown,
+)
+
+get_agent_config = get_shared_config
+
+__all__ = [
+    "APP_NAME",
+    "AgentConfig",
+    "AttachedEval",
+    "PromptSpec",
+    "TransportConfig",
+    "get_agent_config",
+    "get_shared_config",
+    "teardown",
+]
diff --git a/py-opsml/dev/integration/agent/shared/__init__.py b/py-opsml/dev/integration/agent/shared/__init__.py
new file mode 100644
index 0000000000..41bc4224ce
--- /dev/null
+++ b/py-opsml/dev/integration/agent/shared/__init__.py
@@ -0,0 +1,10 @@
+from .setup import APP_NAME, AgentConfig, AttachedEval, PromptSpec, get_shared_config, teardown
+
+__all__ = [
+    "APP_NAME",
+    "AgentConfig",
+    "AttachedEval",
+    "PromptSpec",
+    "get_shared_config",
+    "teardown",
+]
diff --git a/py-opsml/dev/integration/agent/shared/scenarios.jsonl b/py-opsml/dev/integration/agent/shared/scenarios.jsonl
new file mode 100644
index 0000000000..c9b6c2ac05
--- /dev/null
+++ b/py-opsml/dev/integration/agent/shared/scenarios.jsonl
@@ -0,0 +1,2 @@
+{"id":"plan_weeknight_dinner","initial_query":"Help me plan a weeknight dinner with ingredients and steps.","expected_outcome":"A practical dinner plan the user can execute.","simulated_user_persona":"busy home cook","termination_signal":"DONE","max_turns":4,"tasks":[{"task_type":"Assertion","id":"final_response_is_string","context_path":"response","operator":"IsString","expected_value":true}]}
+{"id":"debug_api_timeout","initial_query":"My API call times out intermittently. Help me troubleshoot.","expected_outcome":"A step-by-step troubleshooting path with concrete checks.","simulated_user_persona":"backend engineer","termination_signal":"DONE","max_turns":4,"tasks":[{"task_type":"Assertion","id":"final_response_is_string","context_path":"response","operator":"IsString","expected_value":true}]}
diff --git a/py-opsml/dev/integration/agent/shared/setup.py b/py-opsml/dev/integration/agent/shared/setup.py
new file mode 100644
index 0000000000..d6270aaa6c
--- /dev/null
+++ b/py-opsml/dev/integration/agent/shared/setup.py
@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+import os
+import threading
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Union, cast
+
+from pydantic import BaseModel, ConfigDict
+from opsml import PromptCard
+from opsml.app import AppState
+from opsml.scouter.drift import AgentEvalProfile
+from opsml.scouter.tracing import BatchConfig
+from opsml.scouter.transport import GrpcConfig, MockConfig
+
+os.environ.setdefault("OPSML_TRACKING_URI", "http://localhost:8090")
+os.environ.setdefault("SCOUTER_SERVER_URI", "http://localhost:8000")
+os.environ.setdefault("SCOUTER_GRPC_URI", "http://localhost:50051")
+
+_BASE_DIR = Path(__file__).resolve().parent.parent
+TransportConfig = Union[GrpcConfig, MockConfig]
+
+_config: AgentConfig | None = None
+_config_key: tuple[str, str, bool] | None = None
+
+APP_NAME = "opsml_e2e_agent"
+
+
+class Prompts(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    triage: PromptCard
+    responder: PromptCard
+
+
+@dataclass(frozen=True)
+class PromptSpec:
+    alias: str
+    card: PromptCard
+    eval_profile: AgentEvalProfile
+    task_ids: set[str]
+
+
+@dataclass(frozen=True)
+class AttachedEval:
+    run_id: str
+    agent_name: str
+    profile_uid: str
+    record_id: str
+    session_id: str
+    trace_id: str
+    span_id: str
+
+
+@dataclass
+class AgentConfig:
+    app: AppState
+    prompts: Prompts
+    triage: PromptSpec
+    responder: PromptSpec
+    attached_evals: list[AttachedEval] = field(default_factory=list)
+    run_id: str = field(default_factory=lambda: uuid.uuid4().hex)
+    _attached_eval_ids: set[str] = field(default_factory=set, init=False, repr=False)
+    _attached_eval_lock: Any = field(
+        default_factory=threading.RLock, init=False, repr=False
+    )
+
+    def begin_run(self, run_id: str | None = None) -> str:
+        """Reset the integration-test eval ledger for a new harness run."""
+        with self._attached_eval_lock:
+            self.run_id = run_id or uuid.uuid4().hex
+            self.attached_evals.clear()
+            self._attached_eval_ids.clear()
+            return self.run_id
+
+    def clear_attached_evals(self) -> None:
+        """Clear attached evals without changing the current run identity."""
+        with self._attached_eval_lock:
+            self.attached_evals.clear()
+            self._attached_eval_ids.clear()
+
+    def record_attached_eval(self, attached_eval: AttachedEval) -> None:
+        """Record eval metadata for end-of-run integration assertions."""
+        with self._attached_eval_lock:
+            if attached_eval.record_id in self._attached_eval_ids:
+                return
+            self._attached_eval_ids.add(attached_eval.record_id)
+            self.attached_evals.append(attached_eval)
+
+    def attached_eval_snapshot(self) -> list[AttachedEval]:
+        """Return a stable snapshot for assertions that need thread-safe reads."""
+        with self._attached_eval_lock:
+            return list(self.attached_evals)
+
+
+def get_shared_config(
+    *,
+    transport_config: TransportConfig | None = None,
+    register: bool = True,
+) -> AgentConfig:
+    global _config, _config_key
+    config_key = _cache_key(transport_config, register)
+    if _config is not None and _config_key == config_key:
+        return _config
+    if _config is not None:
+        _config.app.shutdown()
+        _config = None
+        _config_key = None
+
+    app = AppState.from_spec(
+        path=_BASE_DIR / "opsmlspec.yaml",
+        transport_config=cast(Any, transport_config or GrpcConfig()),
+        register=register,
+    )
+    app.instrument(batch_config=BatchConfig(scheduled_delay_ms=200))
+
+    triage_card = cast(PromptCard, app.service["triage_prompt"])
+    responder_card = cast(PromptCard, app.service["responder_prompt"])
+    prompts = Prompts(triage=triage_card, responder=responder_card)
+    _config = AgentConfig(
+        app=app,
+        prompts=prompts,
+        triage=_prompt_spec("triage_evaluation", triage_card),
+        responder=_prompt_spec("responder_evaluation", responder_card),
+    )
+    _config_key = config_key
+    return _config
+
+
+def _cache_key(
+    transport_config: TransportConfig | None,
+    register: bool,
+) -> tuple[str, str, bool]:
+    transport_type = GrpcConfig if transport_config is None else type(transport_config)
+    transport_value = "default" if transport_config is None else repr(transport_config)
+    return (
+        f"{transport_type.__module__}.{transport_type.__qualname__}",
+        transport_value,
+        register,
+    )
+
+
+def _prompt_spec(alias: str, card: PromptCard) -> PromptSpec:
+    profile = card.eval_profile
+    if profile is None:
+        raise RuntimeError(f"Prompt card '{alias}' did not load an eval profile")
+    tasks = [
+        *profile.assertion_tasks,
+        *profile.llm_judge_tasks,
+        *profile.trace_assertion_tasks,
+    ]
+    return PromptSpec(
+        alias=alias,
+        card=card,
+        eval_profile=profile,
+        task_ids={str(task.id) for task in tasks},
+    )
+
+
+def teardown() -> None:
+    global _config, _config_key
+    if _config is None:
+        return
+    _config.app.shutdown()
+    _config = None
+    _config_key = None
diff --git a/py-opsml/dev/integration/agent/single.py b/py-opsml/dev/integration/agent/single.py
new file mode 100644
index 0000000000..6488da701c
--- /dev/null
+++ b/py-opsml/dev/integration/agent/single.py
@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+
+os.environ.setdefault("OPSML_TRACKING_URI", "http://localhost:8090")
+os.environ.setdefault("SCOUTER_SERVER_URI", "http://localhost:8000")
+os.environ.setdefault("SCOUTER_GRPC_URI", "http://localhost:50051")
+
+from google.adk.runners import Runner
+from google.adk.sessions import InMemorySessionService
+
+from .agents import run_agent_turn
+from .agents.triage import build_triage_agent
+from .setup import APP_NAME, get_agent_config, teardown
+
+
+def run_single_agent_query(query: str) -> str:
+    config = get_agent_config()
+    config.begin_run()
+    session_service = InMemorySessionService()
+    runner = Runner(
+        agent=build_triage_agent(config),
+        app_name=APP_NAME,
+        session_service=session_service,
+    )
+    return asyncio.run(run_agent_turn(runner, session_service, query=query))
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Run one online single-agent request.")
+    parser.add_argument(
+        "query",
+        nargs="?",
+        default="Classify this request: I need a quick dinner plan for tonight.",
+    )
+    args = parser.parse_args()
+
+    try:
+        response = run_single_agent_query(args.query)
+        print(response)
+    finally:
+        teardown()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/py-opsml/examples/benchmarks/_mlflow/run.py b/py-opsml/examples/benchmarks/_mlflow/run.py
index 00cc43656b..1333d774d0 100644
--- a/py-opsml/examples/benchmarks/_mlflow/run.py
+++ b/py-opsml/examples/benchmarks/_mlflow/run.py
@@ -1,7 +1,8 @@
+import time
+
 import mlflow
-from sklearn.datasets import make_classification
 from sklearn import ensemble  # type: ignore
-import time
+from sklearn.datasets import make_classification
 
 times = []
 
diff --git a/py-opsml/examples/benchmarks/_opsml/run.py b/py-opsml/examples/benchmarks/_opsml/run.py
index 2db213cdb5..f927e2a8f2 100644
--- a/py-opsml/examples/benchmarks/_opsml/run.py
+++ b/py-opsml/examples/benchmarks/_opsml/run.py
@@ -1,9 +1,10 @@
-from opsml.experiment import start_experiment
+import time
+
 from opsml.card import ModelCard
+from opsml.experiment import start_experiment
 from opsml.model import SklearnModel, TaskType
-from sklearn.datasets import make_classification  # type: ignore
 from sklearn import ensemble  # type: ignore
-import time
+from sklearn.datasets import make_classification  # type: ignore
 
 times = []
 
diff --git a/py-opsml/examples/docs/overview_genai.py b/py-opsml/examples/docs/overview_genai.py
index 568faa516c..b84fc09d8d 100644
--- a/py-opsml/examples/docs/overview_genai.py
+++ b/py-opsml/examples/docs/overview_genai.py
@@ -1,6 +1,6 @@
 if __name__ == "__main__":
     from openai import OpenAI
-    from opsml import PromptCard, Prompt, CardRegistry
+    from opsml import CardRegistry, Prompt, PromptCard
 
     client = OpenAI()
 
diff --git a/py-opsml/examples/docs/overview_traditional.py b/py-opsml/examples/docs/overview_traditional.py
index 6484bc277d..1a2a81868f 100644
--- a/py-opsml/examples/docs/overview_traditional.py
+++ b/py-opsml/examples/docs/overview_traditional.py
@@ -1,7 +1,7 @@
 if __name__ == "__main__":
     # create_fake_data requires polars and pandas to be installed
+    from opsml import CardRegistry, ModelCard, RegistryType, SklearnModel, TaskType
     from opsml.helpers.data import create_fake_data
-    from opsml import SklearnModel, CardRegistry, TaskType, ModelCard, RegistryType
     from sklearn import ensemble  # type: ignore
 
     # start registries
diff --git a/py-opsml/examples/experiment/advanced.py b/py-opsml/examples/experiment/advanced.py
index 2ad03b1b42..d87417b44f 100644
--- a/py-opsml/examples/experiment/advanced.py
+++ b/py-opsml/examples/experiment/advanced.py
@@ -1,21 +1,22 @@
+from typing import Union
+
+import matplotlib.pyplot as plt
+import numpy as np
 import pandas as pd
+import seaborn as sns  # type: ignore
 import torch
 import torch.nn as nn
 import torch.optim as optim
-from torch.utils.data import DataLoader, TensorDataset
-from sklearn.model_selection import train_test_split  # type: ignore
-from sklearn.preprocessing import StandardScaler  # type: ignore
-from sklearn.metrics import mean_squared_error, r2_score  # type: ignore
-from pydantic import BaseModel
-import matplotlib.pyplot as plt
-import seaborn as sns  # type: ignore
-from typing import Union
-import numpy as np
-from scipy import stats  # type: ignore
 from opsml import Card, ModelCard, ServiceCard, TaskType
 from opsml.experiment import Experiment, start_experiment
 from opsml.helpers.data import create_fake_data
 from opsml.model import ModelSaveKwargs, TorchModel
+from pydantic import BaseModel
+from scipy import stats  # type: ignore
+from sklearn.metrics import mean_squared_error, r2_score  # type: ignore
+from sklearn.model_selection import train_test_split  # type: ignore
+from sklearn.preprocessing import StandardScaler  # type: ignore
+from torch.utils.data import DataLoader, TensorDataset
 
 
 def plot_residuals_torch(
diff --git a/py-opsml/examples/experiment/agent/agent.py b/py-opsml/examples/experiment/agent/agent.py
index a96ae01dfc..fefb6043d2 100644
--- a/py-opsml/examples/experiment/agent/agent.py
+++ b/py-opsml/examples/experiment/agent/agent.py
@@ -1,26 +1,26 @@
+from typing import Optional, cast
+
+from google.adk.agents.callback_context import CallbackContext
+from google.adk.agents.llm_agent import Agent
+from google.adk.agents.sequential_agent import SequentialAgent
+from google.genai import types  # For types.Content
+from opentelemetry import trace
+from opsml.scouter.queue import EvalRecord, ScouterQueue
 from opsml.scouter.tracing import (
+    ActiveSpan,
+    BatchConfig,
     ScouterInstrumentor,
     TracerProvider,
-    BatchConfig,
-    ActiveSpan,
 )
 from opsml.scouter.transport import GrpcConfig
-from opsml.scouter.queue import ScouterQueue, EvalRecord
-from google.adk.agents.llm_agent import Agent
+
+from .setup.models import Recipe
 from .setup.prompt import (
     recipe_card,
-    recipe_response_card,
     recipe_generation_eval_profile,
+    recipe_response_card,
     recipe_response_eval_profile,
 )
-from .setup.models import Recipe
-from google.adk.agents.callback_context import CallbackContext
-from google.genai import types  # For types.Content
-from typing import Optional
-from opentelemetry import trace
-from typing import cast
-from google.adk.agents.sequential_agent import SequentialAgent
-
 
 queue = ScouterQueue.from_profile(
     profile=[recipe_generation_eval_profile, recipe_response_eval_profile],
diff --git a/py-opsml/examples/experiment/agent/setup/models.py b/py-opsml/examples/experiment/agent/setup/models.py
index bbb58fce86..17c76f78c1 100644
--- a/py-opsml/examples/experiment/agent/setup/models.py
+++ b/py-opsml/examples/experiment/agent/setup/models.py
@@ -1,6 +1,7 @@
-from pydantic import BaseModel
 from typing import List, Optional
 
+from pydantic import BaseModel
+
 
 class Ingredient(BaseModel):
     name: str
diff --git a/py-opsml/examples/experiment/agent/setup/prompt.py b/py-opsml/examples/experiment/agent/setup/prompt.py
index f8335abc68..1ecab760f9 100644
--- a/py-opsml/examples/experiment/agent/setup/prompt.py
+++ b/py-opsml/examples/experiment/agent/setup/prompt.py
@@ -1,9 +1,9 @@
-from opsml.card import PromptCard, RegistryType
 from opsml.agent import Prompt
+from opsml.card import CardRegistry, PromptCard, RegistryType
 from opsml.scouter.drift import AgentEvalProfile
+
 from .models import Recipe
-from .tasks import recipe_tasks, recipe_response_tasks
-from opsml.card import CardRegistry
+from .tasks import recipe_response_tasks, recipe_tasks
 
 
 def create_recipe_generation_prompt() -> Prompt:
diff --git a/py-opsml/examples/experiment/agent/setup/tasks.py b/py-opsml/examples/experiment/agent/setup/tasks.py
index dfe1d636fc..bc4461fec8 100644
--- a/py-opsml/examples/experiment/agent/setup/tasks.py
+++ b/py-opsml/examples/experiment/agent/setup/tasks.py
@@ -1,14 +1,15 @@
+from typing import List
+
 from opsml.agent import Prompt
 from opsml.scouter.evaluate import (
-    LLMJudgeTask,
-    ComparisonOperator,
     AssertionTask,
-    TraceAssertionTask,
-    TraceAssertion,
+    ComparisonOperator,
+    LLMJudgeTask,
     SpanFilter,
+    TraceAssertion,
+    TraceAssertionTask,
 )
 from pydantic import BaseModel
-from typing import List
 
 
 class VegetarianValidation(BaseModel):
diff --git a/py-opsml/examples/genai/agent/crewai/agent.py b/py-opsml/examples/genai/agent/crewai/agent.py
index 32c105be67..ff9a196762 100644
--- a/py-opsml/examples/genai/agent/crewai/agent.py
+++ b/py-opsml/examples/genai/agent/crewai/agent.py
@@ -6,9 +6,9 @@
 from fastapi import FastAPI
 from openinference.instrumentation.crewai import CrewAIInstrumentor
 from opentelemetry.trace import get_tracer_provider
-from pydantic import BaseModel
 from opsml.scouter import trace
 from opsml.scouter.evaluate import EvalRecord
+from pydantic import BaseModel
 
 from ..shared import get_shared_config, teardown
 
@@ -40,7 +40,7 @@ def _emit_eval_record(query: str, response: str) -> None:
 
 
 def _build_crew(query: str, callback: AgentCallback):
-    from crewai import Agent, Crew, LLM, Task
+    from crewai import LLM, Agent, Crew, Task
     from crewai.tasks.task_output import TaskOutput
 
     llm = LLM(
diff --git a/py-opsml/examples/genai/agent/google/agent.py b/py-opsml/examples/genai/agent/google/agent.py
index 28b72f9e48..80c04e34e1 100644
--- a/py-opsml/examples/genai/agent/google/agent.py
+++ b/py-opsml/examples/genai/agent/google/agent.py
@@ -2,6 +2,7 @@
 
 import os
 from typing import Callable, Optional
+
 from fastapi import FastAPI
 from google.adk.agents import Agent
 from google.adk.agents.callback_context import CallbackContext
@@ -10,9 +11,8 @@
 from google.adk.sessions import InMemorySessionService
 from google.genai import types
 from opsml.scouter import trace
-from pydantic import BaseModel
-
 from opsml.scouter.evaluate import EvalRecord
+from pydantic import BaseModel
 
 from ..shared import get_shared_config, teardown
 
diff --git a/py-opsml/examples/genai/agent/openai/agent.py b/py-opsml/examples/genai/agent/openai/agent.py
index 0ddb4ce03a..61e820b2b6 100644
--- a/py-opsml/examples/genai/agent/openai/agent.py
+++ b/py-opsml/examples/genai/agent/openai/agent.py
@@ -5,9 +5,9 @@
 
 from agents import Agent, RunHooks, Runner
 from fastapi import FastAPI
-from pydantic import BaseModel
 from opsml.scouter import trace
 from opsml.scouter.evaluate import EvalRecord
+from pydantic import BaseModel
 
 from ..shared import get_shared_config, teardown
 
diff --git a/py-opsml/examples/genai/google_adk/app/agent/helper.py b/py-opsml/examples/genai/google_adk/app/agent/helper.py
index bdb55ddfa0..2f84f651b3 100644
--- a/py-opsml/examples/genai/google_adk/app/agent/helper.py
+++ b/py-opsml/examples/genai/google_adk/app/agent/helper.py
@@ -6,7 +6,6 @@
 from opsml.logging import LoggingConfig, LogLevel, RustyLogger
 from opsml.scouter import LLMRecord, Queue
 
-
 from .agents import get_agents
 from .utils import parse_response_events, parse_shipment_events
 
diff --git a/py-opsml/examples/genai/google_adk/app/train/eta.py b/py-opsml/examples/genai/google_adk/app/train/eta.py
index 62810c13f5..48f15d0e4e 100644
--- a/py-opsml/examples/genai/google_adk/app/train/eta.py
+++ b/py-opsml/examples/genai/google_adk/app/train/eta.py
@@ -1,9 +1,9 @@
 from opsml import ModelCard, SklearnModel, TaskType
-from opsml.types import DataType
 from opsml.helpers.data import create_fake_data
+from opsml.scouter import CommonCrons
 from opsml.scouter.alert import PsiAlertConfig
 from opsml.scouter.drift import PsiDriftConfig
-from opsml.scouter import CommonCrons
+from opsml.types import DataType
 from sklearn import ensemble  # type: ignore
 
 
diff --git a/py-opsml/examples/genai/google_adk/app/train/prompt.py b/py-opsml/examples/genai/google_adk/app/train/prompt.py
index 098ea748b3..71607a7d08 100644
--- a/py-opsml/examples/genai/google_adk/app/train/prompt.py
+++ b/py-opsml/examples/genai/google_adk/app/train/prompt.py
@@ -1,8 +1,8 @@
-from opsml.card import PromptCard
 from opsml.agent import Prompt
+from opsml.card import PromptCard
+from opsml.scouter import CommonCrons
 from opsml.scouter.alert import LLMAlertConfig
 from opsml.scouter.drift import LLMDriftConfig
-from opsml.scouter import CommonCrons
 
 from .prompt_metrics import shipment_eta_reply_evaluation, shipment_eta_task_evaluation
 
diff --git a/py-opsml/examples/genai/pydantic/app/train/eta.py b/py-opsml/examples/genai/pydantic/app/train/eta.py
index 7ed3b842b3..e648840b55 100644
--- a/py-opsml/examples/genai/pydantic/app/train/eta.py
+++ b/py-opsml/examples/genai/pydantic/app/train/eta.py
@@ -1,9 +1,9 @@
 from opsml import ModelCard, SklearnModel, TaskType
-from opsml.types import DataType
 from opsml.helpers.data import create_fake_data
 from opsml.scouter.alert import PsiAlertConfig
 from opsml.scouter.drift import PsiDriftConfig
 from opsml.scouter.types import CommonCrons
+from opsml.types import DataType
 from sklearn import ensemble  # type: ignore
 
 
diff --git a/py-opsml/examples/genai/pydantic/app/train/prompt.py b/py-opsml/examples/genai/pydantic/app/train/prompt.py
index af35c1ef1e..78ef05c2e8 100644
--- a/py-opsml/examples/genai/pydantic/app/train/prompt.py
+++ b/py-opsml/examples/genai/pydantic/app/train/prompt.py
@@ -1,8 +1,8 @@
-from opsml.card import PromptCard
 from opsml.agent import Prompt
+from opsml.card import PromptCard
+from opsml.scouter import CommonCrons
 from opsml.scouter.alert import LLMAlertConfig
 from opsml.scouter.drift import LLMDriftConfig
-from opsml.scouter import CommonCrons
 
 from .prompt_metrics import shipment_eta_reply_evaluation, shipment_eta_task_evaluation
 
diff --git a/py-opsml/examples/genai/recipe/app/main.py b/py-opsml/examples/genai/recipe/app/main.py
index 2814acf631..f7745e145a 100644
--- a/py-opsml/examples/genai/recipe/app/main.py
+++ b/py-opsml/examples/genai/recipe/app/main.py
@@ -1,17 +1,19 @@
 # pylint: disable=invalid-name
 from contextlib import asynccontextmanager
 from pathlib import Path
-from opsml.scouter.queue import EvalRecord
-from opsml.card import PromptCard
+
 from fastapi import FastAPI, Request
 from opsml.app import AppState
+from opsml.card import PromptCard
 from opsml.scouter import GrpcConfig
+from opsml.scouter.queue import EvalRecord
 from opsml.scouter.tracing import shutdown_tracer
 from pydantic import BaseModel
-from app.tracing import tracer
-from app.models import Recipe
 from pydantic_ai import Agent
 
+from app.models import Recipe
+from app.tracing import tracer
+
 
 class Question(BaseModel):
     question: str
diff --git a/py-opsml/examples/genai/recipe/app/models.py b/py-opsml/examples/genai/recipe/app/models.py
index bbb58fce86..17c76f78c1 100644
--- a/py-opsml/examples/genai/recipe/app/models.py
+++ b/py-opsml/examples/genai/recipe/app/models.py
@@ -1,6 +1,7 @@
-from pydantic import BaseModel
 from typing import List, Optional
 
+from pydantic import BaseModel
+
 
 class Ingredient(BaseModel):
     name: str
diff --git a/py-opsml/examples/genai/recipe/app/tracing.py b/py-opsml/examples/genai/recipe/app/tracing.py
index 95389d6aba..a42869880a 100644
--- a/py-opsml/examples/genai/recipe/app/tracing.py
+++ b/py-opsml/examples/genai/recipe/app/tracing.py
@@ -1,5 +1,5 @@
-from opsml.scouter.tracing import init_tracer, get_tracer
 from opsml.scouter import GrpcConfig
+from opsml.scouter.tracing import get_tracer, init_tracer
 
 init_tracer(
     service_name="agent-recipe-service",
diff --git a/py-opsml/examples/genai/recipe/app/train/evaluation/tasks.py b/py-opsml/examples/genai/recipe/app/train/evaluation/tasks.py
index 42c229a532..e7919fbf62 100644
--- a/py-opsml/examples/genai/recipe/app/train/evaluation/tasks.py
+++ b/py-opsml/examples/genai/recipe/app/train/evaluation/tasks.py
@@ -1,14 +1,15 @@
+from typing import List
+
 from opsml.agent import Prompt
 from opsml.scouter.evaluate import (
-    LLMJudgeTask,
-    ComparisonOperator,
     AssertionTask,
-    TraceAssertionTask,
-    TraceAssertion,
+    ComparisonOperator,
+    LLMJudgeTask,
     SpanFilter,
+    TraceAssertion,
+    TraceAssertionTask,
 )
 from pydantic import BaseModel
-from typing import List
 
 
 class VegetarianValidation(BaseModel):
diff --git a/py-opsml/examples/genai/recipe/app/train/prompt.py b/py-opsml/examples/genai/recipe/app/train/prompt.py
index 275115f2a2..ba5763482d 100644
--- a/py-opsml/examples/genai/recipe/app/train/prompt.py
+++ b/py-opsml/examples/genai/recipe/app/train/prompt.py
@@ -1,8 +1,10 @@
-from opsml.card import PromptCard
 from opsml.agent import Prompt
-from opsml.scouter.drift import AgentAlertConfig, AgentEvalConfig
+from opsml.card import PromptCard
 from opsml.scouter import CommonCrons
+from opsml.scouter.drift import AgentAlertConfig, AgentEvalConfig
+
 from app.models import Recipe  # type: ignore
+
 from .evaluation.tasks import tasks
 
 
diff --git a/py-opsml/examples/getting_started.py b/py-opsml/examples/getting_started.py
index 706db78b8e..3176e1edb4 100644
--- a/py-opsml/examples/getting_started.py
+++ b/py-opsml/examples/getting_started.py
@@ -11,12 +11,13 @@
   4. Stop the server:   opsml ui stop
 """
 
+from pathlib import Path
+
 from opsml import DataCard, ModelCard, SklearnModel, TaskType
 from opsml.data import PandasData
 from opsml.experiment import start_experiment
 from opsml.helpers.data import create_fake_data
 from sklearn import ensemble  # type: ignore
-from pathlib import Path
 
 SPACE = "getting-started"
 
@@ -60,4 +61,4 @@
 
     exp.log_artifacts(artifact_path)  # log all files in the genai directory as artifacts
 
-print(f"\nOpen http://localhost:3000 to browse registered cards.")
+print("\nOpen http://localhost:3000 to browse registered cards.")
diff --git a/py-opsml/makefile b/py-opsml/makefile
deleted file mode 100644
index a3b649c2c9..0000000000
--- a/py-opsml/makefile
+++ /dev/null
@@ -1,145 +0,0 @@
-PROJECT=opml-core
-PYTHON_VERSION=3.12.8
-SOURCE_OBJECTS=python/opsml
-FORMAT_OBJECT=python/opsml examples
-
-format.isort:
-	uv run isort ${SOURCE_OBJECTS}
-format.black:
-	uv run black ${FORMAT_OBJECT}
-format.ruff:
-	uv run ruff check --silent --exit-zero ${FORMAT_OBJECT}
-format: format.isort format.ruff format.black
-
-lints.format_check:
-	uv run black --check ${SOURCE_OBJECTS}
-lints.ruff:
-	uv run ruff check ${SOURCE_OBJECTS}
-lints.ty:
-	uv run ty check ${SOURCE_OBJECTS}
-lints.pylint:
-	uv run pylint ${SOURCE_OBJECTS}
-lints: lints.ruff lints.pylint lints.ty
-lints.ci: lints.format_check lints.ruff lints.pylint lints.ty
-
-build.stubs:
-	uv run python scripts/assemble_stubs.py
-	uv run isort ${SOURCE_OBJECTS}
-	uv run black ${FORMAT_OBJECT}
-	uv run ruff check --silent --exit-zero ${FORMAT_OBJECT}
-
-setup.project: build.stubs
-	uv sync --all-extras --group dev --group docs
-	uv run maturin develop --features server
-
-setup.project.release:
-	uv sync --all-extras --group dev --group docs
-	uv run maturin build --release --out dist
-
-setup.adk:
-	uv sync --group dev --group docs
-	uv pip install -r requirements/requirements.adk.txt
-	uv run maturin develop --features server
-
-test.unit.tensorflow: setup.project
-	uv pip install -r requirements/requirements.tf.txt
-	uv run pytest \
-		--ignore="tests/interfaces/model/test_tensorflow.py" \
-		-m "tensorflow" \
-		--cov \
-		--cov-fail-under=0 \
-		--cov-report xml:./coverage.xml \
-		--cov-report term
-	uv run python tests/interfaces/model/test_tensorflow.py
-
-test.unit:
-	uv run pytest \
-		--ignore="tests/agent/integration/*" \
-		--ignore="tests/interfaces/model/test_tensorflow.py" \
-		--ignore="tests/service" \
-		-m "not tensorflow" \
-		--cov \
-		--cov-fail-under=0 \
-		--cov-report xml:./coverage.xml \
-		--cov-report term 
-
-setup.integration:
-	uv sync --all-extras --group dev,docs
-	uv run maturin develop --release 
-
-test.integration:
-	uv run pytest -s tests/integration
-
-test.service:
-	uv run pytest -s tests/service
-
-test.examples.data:
-	uv run python examples/data/arrow_data.py && \
-	uv run python examples/data/numpy_data.py && \
-	uv run python examples/data/pandas_data.py && \
-	uv run python examples/data/polars_data.py && \
-	uv run python examples/data/custom_data.py
-
-test.examples.model:
-	uv pip install -r requirements/requirements.examples.txt
-	uv run python examples/model/catboost_model.py && \
-	uv run python examples/model/custom_model.py && \
-	uv run python examples/model/hf_model.py && \
-	uv run python examples/model/lightgbm_booster.py && \
-	uv run python examples/model/lightning_model.py && \
-	uv run python examples/model/onnx_model.py && \
-	uv run python examples/model/sklearn_model.py && \
-	uv run python examples/model/torch_model.py && \
-	uv run python examples/model/xgb_booster.py
-
-test.examples: test.examples.data test.examples.model
-
-AGENT_QUERY ?= Help me plan a weeknight dinner with ingredients and steps.
-
-example.agent.openai:
-	uv run python -m examples.genai.agent.openai.agent "$(AGENT_QUERY)"
-
-example.agent.google:
-	uv run python -m examples.genai.agent.google.agent "$(AGENT_QUERY)"
-
-example.agent.crewai:
-	uv run python -m examples.genai.agent.crewai.agent "$(AGENT_QUERY)"
-
-example.eval.openai:
-	uv run python -m examples.genai.agent.openai.evaluate
-
-example.eval.google:
-	uv run python -m examples.genai.agent.google.evaluate
-
-example.eval.crewai:
-	uv run python -m examples.genai.agent.crewai.evaluate
-
-uv.pre.patch:
-	uv version prepatch
-
-uv.sub.pre.tag:
-	$(eval VER = $(shell grep "^version =" pyproject.toml | tr -d '"' | sed "s/^version = //"))
-	$(eval TS = $(shell date +%s))
-	$(eval REL_CANDIDATE = $(subst a0,rc.$(TS),$(VER)))
-	@sed -i "s/$(VER)/$(REL_CANDIDATE)/" pyproject.toml
-
-prep.pre.patch: uv.pre.patch uv.sub.pre.tag
-
-setup.docs:
-	uv sync --group docs
-
-build.docs:
-	uv run python scripts/create_mkdocs_stubs.py
-	uv run mkdocs build
-
-serve.docs:
-	uv run python scripts/create_mkdocs_stubs.py
-	uv run mkdocs serve
-
-publish.docs:
-	uv run python scripts/assemble_stubs.py
-	uv run python scripts/create_mkdocs_stubs.py
-	uv run mkdocs gh-deploy --force
-
-upgrade.deps:
-	uv sync --upgrade --all-extras
diff --git a/py-opsml/pyproject.toml b/py-opsml/pyproject.toml
index d4f412976d..24fabd9099 100644
--- a/py-opsml/pyproject.toml
+++ b/py-opsml/pyproject.toml
@@ -46,10 +46,7 @@ dev = [
     "pytest-cov >= 5.0.0, < 6.0.0",
     "ruff >= 0.1.0, < 1.0.0",
     "ty >= 0.0.35, < 0.1.0",
-    "black >= 24.3.0, < 25.0.0",
-    "pylint >= 3.0.0, < 4.0.0",
     "pytest-lazy-fixture >= 0.6.3, < 1.0.0",
-    "isort >= 5.13.2, < 6.0.0",
     "pip>=24.3.1",
     "transformers>=4.40.0,<4.45.0",
     "optimum<1.27.0",
@@ -82,52 +79,16 @@ docs = [
     "mkdocstrings[python]>=0.29.1",
 ]
 
-[tool.isort]
-profile = "black"
-
 [tool.ruff]
-exclude = [
-    "python/opsml/stubs/*",
-]
-
-[tool.black]
 line-length = 120
-target-version = ['py310']
-include = '\.pyi?$'
-
-[tool.pylint.MASTER]
-load-plugins = ["pylint.extensions.docparams"]
-ignore-patterns = [
+target-version = "py310"
+exclude = [
     "python/opsml/stubs/*",
 ]
 
-
-[tool.pylint.messages_control]
-max-line-length = 130
-disable = [
-    "too-few-public-methods",
-    "design",
-    "duplicate-code",
-    "missing-class-docstring",
-    "missing-function-docstring",
-    "missing-module-docstring",
-    "too-many-nested-blocks",
-    "unused-argument",
-    "fixme",
-    "import-outside-toplevel",
-    "import-self",
-    "too-many-lines",
-    "cyclic-import",
-]
-
-[tool.flake8]
-# This section is just a doc placeholder..see setup.cfg
-max-complexity = 10
-format = "pylint"
-statistics = "True"
-max-line-length = 125
-# ignore non-PEP8 lints
-ignore = ["E203", "W503", "W0511"]
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+ignore = ["E501"]
 
 [tool.pytest.ini_options]
 log_cli = true
diff --git a/py-opsml/python/opsml/__init__.py b/py-opsml/python/opsml/__init__.py
index c633caaf3d..b132ddc122 100644
--- a/py-opsml/python/opsml/__init__.py
+++ b/py-opsml/python/opsml/__init__.py
@@ -2,9 +2,6 @@
 # pylint: disable=no-name-in-module
 # python/opsml/__init__.py
 from . import agent, app, card, data, experiment, logging, mock, model, scouter, types
-from ._opsml import _get_log_level  # type: ignore
-from ._opsml import _log_json  # type: ignore
-from ._opsml import get_opsml_version  # type: ignore
 from ._opsml import (  # top-level modules; # App; # Card; # Data; Experiment; # model
     AgentSkillStandard,
     AppState,
@@ -47,6 +44,9 @@
     TensorFlowModel,
     TorchModel,
     XGBoostModel,
+    _get_log_level,  # type: ignore
+    _log_json,  # type: ignore
+    get_opsml_version,  # type: ignore
     start_experiment,
 )
 
diff --git a/py-opsml/python/opsml/agent/__init__.py b/py-opsml/python/opsml/agent/__init__.py
index 26b4e44be5..e786f95f28 100644
--- a/py-opsml/python/opsml/agent/__init__.py
+++ b/py-opsml/python/opsml/agent/__init__.py
@@ -1,11 +1,10 @@
 # mypy: disable-error-code="attr-defined"
 # pylint: disable=no-name-in-module
 
-from .._opsml import Agent  # PyAgent
-from .._opsml import AgentResponse  # PyAgentResponse
-from .._opsml import Embedder  # PyEmbedder
-from .._opsml import Workflow  # PyWorkflow
 from .._opsml import (  # Prompt interface types; Workflow types; Agent types; Python-exposed classes (Py prefix in Rust)
+    Agent,  # PyAgent
+    AgentResponse,  # PyAgentResponse
+    Embedder,  # PyEmbedder
     EventDetails,
     ModelSettings,
     Prompt,
@@ -17,6 +16,7 @@
     TaskEvent,
     TaskList,
     TaskStatus,
+    Workflow,  # PyWorkflow
     WorkflowResult,
     WorkflowTask,
     list_mcp_servers,
diff --git a/py-opsml/python/opsml/experiment/__init__.py b/py-opsml/python/opsml/experiment/__init__.py
index f7e1db76e0..cbdd2554a8 100644
--- a/py-opsml/python/opsml/experiment/__init__.py
+++ b/py-opsml/python/opsml/experiment/__init__.py
@@ -1,9 +1,8 @@
 # mypy: disable-error-code="attr-defined"
 # python/opsml/card/__init__.py
-from .._opsml import Experiment, ExperimentEvalMetrics
-from .._opsml import ExperimentMetric as Metric
-from .._opsml import ExperimentMetrics as Metrics
 from .._opsml import (
+    Experiment,
+    ExperimentEvalMetrics,
     Parameter,
     Parameters,
     download_artifact,
@@ -11,6 +10,8 @@
     get_experiment_parameters,
     start_experiment,
 )
+from .._opsml import ExperimentMetric as Metric
+from .._opsml import ExperimentMetrics as Metrics
 
 __all__ = [
     "Experiment",
diff --git a/py-opsml/python/opsml/scouter/__init__.py b/py-opsml/python/opsml/scouter/__init__.py
index 3ecb5ecf1b..e817fb2fb5 100644
--- a/py-opsml/python/opsml/scouter/__init__.py
+++ b/py-opsml/python/opsml/scouter/__init__.py
@@ -40,9 +40,6 @@
     QuantileBinning,
     QueryResult,
     Queue,
-)
-from .._opsml import QueueFeature as Feature
-from .._opsml import (
     RabbitMQConfig,
     RedisConfig,
     Rice,
@@ -65,6 +62,7 @@
     TraceAssertionTask,
     WriteConfig,
 )
+from .._opsml import QueueFeature as Feature
 from . import (
     alert,
     bifrost,
diff --git a/py-opsml/python/opsml/scouter/queue/__init__.py b/py-opsml/python/opsml/scouter/queue/__init__.py
index a03e2e4ba1..9c40002605 100644
--- a/py-opsml/python/opsml/scouter/queue/__init__.py
+++ b/py-opsml/python/opsml/scouter/queue/__init__.py
@@ -9,9 +9,13 @@
     Metrics,
     PsiRecord,
     Queue,
+    RecordType,
+    ScouterQueue,
+    ServerRecord,
+    ServerRecords,
+    SpcRecord,
 )
 from ..._opsml import QueueFeature as Feature
-from ..._opsml import RecordType, ScouterQueue, ServerRecord, ServerRecords, SpcRecord
 
 __all__ = [
     "ScouterQueue",
diff --git a/py-opsml/python/opsml/scouter/tracing/__init__.py b/py-opsml/python/opsml/scouter/tracing/__init__.py
index 21471dc02e..293afd7196 100644
--- a/py-opsml/python/opsml/scouter/tracing/__init__.py
+++ b/py-opsml/python/opsml/scouter/tracing/__init__.py
@@ -50,13 +50,11 @@
     flush_tracer,
     get_current_active_span,
     get_function_type,
-)
-from ..._opsml import get_tracer as _get_tracer
-from ..._opsml import (
     get_tracing_headers_from_current_span,
     reset_tracer_provider,
     shutdown_tracer,
 )
+from ..._opsml import get_tracer as _get_tracer
 from .middleware import ScouterTracingMiddleware
 
 SerializedType: TypeAlias = Union[str, int, float, dict, list]
@@ -94,16 +92,16 @@ class BaseInstrumentor:
             """Stub base class when OpenTelemetry is not available."""
 
             def instrument(self, **kwargs):
-                raise ImportError("OpenTelemetry is not installed. Install with: " "pip install opsml[opentelemetry]")
+                raise ImportError("OpenTelemetry is not installed. Install with: pip install opsml[opentelemetry]")
 
             def uninstrument(self, **kwargs):
-                raise ImportError("OpenTelemetry is not installed. Install with: " "pip install opsml[opentelemetry]")
+                raise ImportError("OpenTelemetry is not installed. Install with: pip install opsml[opentelemetry]")
 
         def get_tracer_provider():
-            raise ImportError("OpenTelemetry is not installed. Install with: " "pip install opsml[opentelemetry]")
+            raise ImportError("OpenTelemetry is not installed. Install with: pip install opsml[opentelemetry]")
 
         def set_tracer_provider(provider):
-            raise ImportError("OpenTelemetry is not installed. Install with: " "pip install opsml[opentelemetry]")
+            raise ImportError("OpenTelemetry is not installed. Install with: pip install opsml[opentelemetry]")
 
         _agnosticcontextmanager = contextmanager
 
@@ -858,7 +856,7 @@ def _instrument(self, **kwargs) -> None:
         """Initialize Scouter tracing and set as global provider."""
         if not HAS_OPENTELEMETRY:
             raise ImportError(
-                "OpenTelemetry is required for instrumentation. " "Install with: pip install opsml[opentelemetry]"
+                "OpenTelemetry is required for instrumentation. Install with: pip install opsml[opentelemetry]"
             )
 
         if self._provider is not None:
diff --git a/py-opsml/tests/cli/test_app.py b/py-opsml/tests/cli/test_app.py
index fc256f2856..4854f9259f 100644
--- a/py-opsml/tests/cli/test_app.py
+++ b/py-opsml/tests/cli/test_app.py
@@ -3,8 +3,8 @@
 ###################################################################################################
 
 from opsml.cli import (
-    lock_service,  # type: ignore
-    install_service,  # type: ignore
+    lock_service,
+    install_service,
 )
 from opsml.mock import MockConfig
 import json
@@ -122,7 +122,7 @@ def test_pyproject_app(
 
 
 @pytest.mark.skipif(WINDOWS_EXCLUDE, reason="skipping")
-def test_from_path_resolves_espresso_style_drift_paths_from_project_root(
+def test_from_path_resolves_style_drift_paths_from_project_root(
     mock_environment,
     random_forest_classifier: SklearnModel,
     chat_prompt: Prompt,
@@ -154,9 +154,12 @@ def service_relative_path(path: str) -> Path:
 
             card_map_path = service_path / "card_map.json"
             card_map = json.loads(card_map_path.read_text())
-            card_map["card_paths"] = {alias: f"ignored/{alias}" for alias in card_map["card_paths"]}
+            card_map["card_paths"] = {
+                alias: f"ignored/{alias}" for alias in card_map["card_paths"]
+            }
             card_map["drift_paths"] = {
-                alias: f"opsml_service/{service_relative_path(path)}" for alias, path in card_map["drift_paths"].items()
+                alias: f"opsml_service/{service_relative_path(path)}"
+                for alias, path in card_map["drift_paths"].items()
             }
             card_map_path.write_text(json.dumps(card_map))
 
diff --git a/py-opsml/tests/integration/test_adk_agent_harness.py b/py-opsml/tests/integration/test_adk_agent_harness.py
new file mode 100644
index 0000000000..dd9d6ab9bb
--- /dev/null
+++ b/py-opsml/tests/integration/test_adk_agent_harness.py
@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+import asyncio
+from types import SimpleNamespace
+from typing import Any
+
+from dev.integration.agent.agents import callbacks, pipeline
+from dev.integration.agent.agents.callbacks import (
+    ATTACHED_EVALS_STATE_KEY,
+    FINAL_RESPONSE_STATE_KEY,
+    TOOL_CALLS_STATE_KEY,
+    TRIAGE_ROUTE_STATE_KEY,
+    agent_output,
+    attach_agent_eval,
+    capture_tool_call,
+)
+from dev.integration.agent.agents.triage import classify_request
+from dev.integration.agent.shared.setup import AgentConfig, AttachedEval
+
+
+class _Span:
+    trace_id = "trace-1"
+    span_id = "span-1"
+
+    def __enter__(self) -> "_Span":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        return None
+
+    def attach_eval(self, **kwargs: Any) -> None:
+        self.attached_eval = kwargs
+
+    def set_attribute(self, *_args: Any, **_kwargs: Any) -> None:
+        return None
+
+
+class _Tracer:
+    def start_as_current_span(self, *_args: Any, **_kwargs: Any) -> _Span:
+        return _Span()
+
+
+class _RecordingTracer:
+    def __init__(self) -> None:
+        self.calls: list[dict[str, Any]] = []
+
+    def start_as_current_span(self, *_args: Any, **kwargs: Any) -> _Span:
+        self.calls.append(kwargs)
+        return _Span()
+
+
+class _SessionService:
+    def __init__(self) -> None:
+        self.state: dict[str, Any] | None = None
+
+    async def create_session(self, **kwargs: Any) -> SimpleNamespace:
+        self.state = kwargs["state"]
+        return SimpleNamespace(id="session-1")
+
+
+class _Runner:
+    async def run_async(self, **_kwargs: Any) -> Any:
+        event = SimpleNamespace(
+            content=SimpleNamespace(parts=[SimpleNamespace(text="done")]),
+            is_final_response=lambda: True,
+        )
+        yield event
+
+
+def test_classify_request_writes_route_state() -> None:
+    tool_context = SimpleNamespace(state={})
+
+    result = classify_request("The API times out under load", tool_context)
+
+    assert result["route"] == "timeout"
+    assert tool_context.state[TRIAGE_ROUTE_STATE_KEY] == "timeout"
+
+
+def test_capture_tool_call_records_state_and_returns_none() -> None:
+    tool = SimpleNamespace(name="classify_request")
+    tool_context = SimpleNamespace(state={})
+
+    result = capture_tool_call(
+        tool, {"query": "hello"}, tool_context, {"status": "success"}
+    )
+
+    assert result is None
+    assert tool_context.state[TOOL_CALLS_STATE_KEY] == [
+        {
+            "name": "classify_request",
+            "arguments": {"query": "hello"},
+            "response": {"status": "success"},
+        }
+    ]
+
+
+def test_agent_output_reads_public_state() -> None:
+    callback_context = SimpleNamespace(state={FINAL_RESPONSE_STATE_KEY: "done"})
+
+    assert agent_output(callback_context, FINAL_RESPONSE_STATE_KEY) == "done"
+
+
+def test_agent_config_attached_eval_ledger_dedupes_and_resets() -> None:
+    config = AgentConfig(app=None, prompts=None, triage=None, responder=None)  # type: ignore[arg-type]
+    run_id = config.begin_run("run-1")
+    attached_eval = AttachedEval(
+        run_id=run_id,
+        agent_name="agent",
+        profile_uid="profile",
+        record_id="record",
+        session_id="session",
+        trace_id="trace",
+        span_id="span",
+    )
+
+    config.record_attached_eval(attached_eval)
+    config.record_attached_eval(attached_eval)
+
+    assert config.attached_eval_snapshot() == [attached_eval]
+
+    config.begin_run("run-2")
+
+    assert config.run_id == "run-2"
+    assert config.attached_eval_snapshot() == []
+
+
+def test_attach_agent_eval_records_config_ledger_and_state(monkeypatch) -> None:
+    monkeypatch.setattr(callbacks.trace, "get_tracer", lambda _name: _Tracer())
+    config = AgentConfig(app=None, prompts=None, triage=None, responder=None)  # type: ignore[arg-type]
+    config.begin_run("run-1")
+    callback_context = SimpleNamespace(
+        state={},
+        invocation_id="invocation-1",
+        session=SimpleNamespace(id="session-1"),
+    )
+
+    attach_agent_eval(
+        callback_context,
+        config=config,
+        agent_name="agent",
+        profile_uid="profile",
+        context={"response": "ok"},
+        span_name="agent.callback",
+        tracer_name="test.tracer",
+    )
+
+    [attached_eval] = config.attached_eval_snapshot()
+    assert attached_eval.run_id == "run-1"
+    assert attached_eval.record_id == "run-1:session-1:agent:invocation-1"
+    assert callback_context.state[ATTACHED_EVALS_STATE_KEY] == [
+        {
+            "run_id": "run-1",
+            "agent_name": "agent",
+            "profile_uid": "profile",
+            "record_id": "run-1:session-1:agent:invocation-1",
+            "session_id": "session-1",
+            "trace_id": "trace-1",
+            "span_id": "span-1",
+        }
+    ]
+
+
+def test_run_agent_turn_uses_active_span_context_not_headers(monkeypatch) -> None:
+    tracer = _RecordingTracer()
+    session_service = _SessionService()
+    monkeypatch.setattr(pipeline.trace, "get_tracer", lambda _name: tracer)
+
+    response = asyncio.run(
+        pipeline.run_agent_turn(
+            _Runner(),  # type: ignore[arg-type]
+            session_service,  # type: ignore[arg-type]
+            query="Help me plan dinner",
+        )
+    )
+
+    assert response == "done"
+    assert tracer.calls == [{}]
+    assert session_service.state == {
+        "temp:query": "Help me plan dinner",
+        "temp:tool_calls": [],
+    }
diff --git a/py-opsml/uv.lock b/py-opsml/uv.lock
index a8ba251ff2..05843a99a0 100644
--- a/py-opsml/uv.lock
+++ b/py-opsml/uv.lock
@@ -285,18 +285,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/74/f5/9373290775639cb67a2fce7f629a1c240dce9f12fe927bc32b2736e16dfc/argcomplete-3.6.3-py3-none-any.whl", hash = "sha256:f5007b3a600ccac5d25bbce33089211dfd49eab4a7718da3f10e3082525a92ce", size = 43846, upload-time = "2025-10-20T03:33:33.021Z" },
 ]
 
-[[package]]
-name = "astroid"
-version = "3.3.11"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/18/74/dfb75f9ccd592bbedb175d4a32fc643cf569d7c218508bfbd6ea7ef9c091/astroid-3.3.11.tar.gz", hash = "sha256:1e5a5011af2920c7c67a53f65d536d65bfa7116feeaf2354d8b94f29573bb0ce", size = 400439, upload-time = "2025-07-13T18:04:23.177Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/af/0f/3b8fdc946b4d9cc8cc1e8af42c4e409468c84441b933d037e101b3d72d86/astroid-3.3.11-py3-none-any.whl", hash = "sha256:54c760ae8322ece1abd213057c4b5bba7c49818853fc901ef09719a60dbf9dec", size = 275612, upload-time = "2025-07-13T18:04:21.07Z" },
-]
-
 [[package]]
 name = "asttokens"
 version = "3.0.1"
@@ -467,41 +455,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/71/cc/18245721fa7747065ab478316c7fea7c74777d07f37ae60db2e84f8172e8/beartype-0.22.9-py3-none-any.whl", hash = "sha256:d16c9bbc61ea14637596c5f6fbff2ee99cbe3573e46a716401734ef50c3060c2", size = 1333658, upload-time = "2025-12-13T06:50:28.266Z" },
 ]
 
-[[package]]
-name = "black"
-version = "24.10.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "click" },
-    { name = "mypy-extensions" },
-    { name = "packaging", version = "24.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.12'" },
-    { name = "packaging", version = "25.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.12'" },
-    { name = "pathspec" },
-    { name = "platformdirs" },
-    { name = "tomli", marker = "python_full_version < '3.11'" },
-    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/d8/0d/cc2fb42b8c50d80143221515dd7e4766995bd07c56c9a3ed30baf080b6dc/black-24.10.0.tar.gz", hash = "sha256:846ea64c97afe3bc677b761787993be4991810ecc7a4a937816dd6bddedc4875", size = 645813, upload-time = "2024-10-07T19:20:50.361Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/a3/f3/465c0eb5cddf7dbbfe1fecd9b875d1dcf51b88923cd2c1d7e9ab95c6336b/black-24.10.0-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:e6668650ea4b685440857138e5fe40cde4d652633b1bdffc62933d0db4ed9812", size = 1623211, upload-time = "2024-10-07T19:26:12.43Z" },
-    { url = "https://files.pythonhosted.org/packages/df/57/b6d2da7d200773fdfcc224ffb87052cf283cec4d7102fab450b4a05996d8/black-24.10.0-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:1c536fcf674217e87b8cc3657b81809d3c085d7bf3ef262ead700da345bfa6ea", size = 1457139, upload-time = "2024-10-07T19:25:06.453Z" },
-    { url = "https://files.pythonhosted.org/packages/6e/c5/9023b7673904a5188f9be81f5e129fff69f51f5515655fbd1d5a4e80a47b/black-24.10.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:649fff99a20bd06c6f727d2a27f401331dc0cc861fb69cde910fe95b01b5928f", size = 1753774, upload-time = "2024-10-07T19:23:58.47Z" },
-    { url = "https://files.pythonhosted.org/packages/e1/32/df7f18bd0e724e0d9748829765455d6643ec847b3f87e77456fc99d0edab/black-24.10.0-cp310-cp310-win_amd64.whl", hash = "sha256:fe4d6476887de70546212c99ac9bd803d90b42fc4767f058a0baa895013fbb3e", size = 1414209, upload-time = "2024-10-07T19:24:42.54Z" },
-    { url = "https://files.pythonhosted.org/packages/c2/cc/7496bb63a9b06a954d3d0ac9fe7a73f3bf1cd92d7a58877c27f4ad1e9d41/black-24.10.0-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:5a2221696a8224e335c28816a9d331a6c2ae15a2ee34ec857dcf3e45dbfa99ad", size = 1607468, upload-time = "2024-10-07T19:26:14.966Z" },
-    { url = "https://files.pythonhosted.org/packages/2b/e3/69a738fb5ba18b5422f50b4f143544c664d7da40f09c13969b2fd52900e0/black-24.10.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:f9da3333530dbcecc1be13e69c250ed8dfa67f43c4005fb537bb426e19200d50", size = 1437270, upload-time = "2024-10-07T19:25:24.291Z" },
-    { url = "https://files.pythonhosted.org/packages/c9/9b/2db8045b45844665c720dcfe292fdaf2e49825810c0103e1191515fc101a/black-24.10.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:4007b1393d902b48b36958a216c20c4482f601569d19ed1df294a496eb366392", size = 1737061, upload-time = "2024-10-07T19:23:52.18Z" },
-    { url = "https://files.pythonhosted.org/packages/a3/95/17d4a09a5be5f8c65aa4a361444d95edc45def0de887810f508d3f65db7a/black-24.10.0-cp311-cp311-win_amd64.whl", hash = "sha256:394d4ddc64782e51153eadcaaca95144ac4c35e27ef9b0a42e121ae7e57a9175", size = 1423293, upload-time = "2024-10-07T19:24:41.7Z" },
-    { url = "https://files.pythonhosted.org/packages/90/04/bf74c71f592bcd761610bbf67e23e6a3cff824780761f536512437f1e655/black-24.10.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:b5e39e0fae001df40f95bd8cc36b9165c5e2ea88900167bddf258bacef9bbdc3", size = 1644256, upload-time = "2024-10-07T19:27:53.355Z" },
-    { url = "https://files.pythonhosted.org/packages/4c/ea/a77bab4cf1887f4b2e0bce5516ea0b3ff7d04ba96af21d65024629afedb6/black-24.10.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:d37d422772111794b26757c5b55a3eade028aa3fde43121ab7b673d050949d65", size = 1448534, upload-time = "2024-10-07T19:26:44.953Z" },
-    { url = "https://files.pythonhosted.org/packages/4e/3e/443ef8bc1fbda78e61f79157f303893f3fddf19ca3c8989b163eb3469a12/black-24.10.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:14b3502784f09ce2443830e3133dacf2c0110d45191ed470ecb04d0f5f6fcb0f", size = 1761892, upload-time = "2024-10-07T19:24:10.264Z" },
-    { url = "https://files.pythonhosted.org/packages/52/93/eac95ff229049a6901bc84fec6908a5124b8a0b7c26ea766b3b8a5debd22/black-24.10.0-cp312-cp312-win_amd64.whl", hash = "sha256:30d2c30dc5139211dda799758559d1b049f7f14c580c409d6ad925b74a4208a8", size = 1434796, upload-time = "2024-10-07T19:25:06.239Z" },
-    { url = "https://files.pythonhosted.org/packages/d0/a0/a993f58d4ecfba035e61fca4e9f64a2ecae838fc9f33ab798c62173ed75c/black-24.10.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:1cbacacb19e922a1d75ef2b6ccaefcd6e93a2c05ede32f06a21386a04cedb981", size = 1643986, upload-time = "2024-10-07T19:28:50.684Z" },
-    { url = "https://files.pythonhosted.org/packages/37/d5/602d0ef5dfcace3fb4f79c436762f130abd9ee8d950fa2abdbf8bbc555e0/black-24.10.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:1f93102e0c5bb3907451063e08b9876dbeac810e7da5a8bfb7aeb5a9ef89066b", size = 1448085, upload-time = "2024-10-07T19:28:12.093Z" },
-    { url = "https://files.pythonhosted.org/packages/47/6d/a3a239e938960df1a662b93d6230d4f3e9b4a22982d060fc38c42f45a56b/black-24.10.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ddacb691cdcdf77b96f549cf9591701d8db36b2f19519373d60d31746068dbf2", size = 1760928, upload-time = "2024-10-07T19:24:15.233Z" },
-    { url = "https://files.pythonhosted.org/packages/dd/cf/af018e13b0eddfb434df4d9cd1b2b7892bab119f7a20123e93f6910982e8/black-24.10.0-cp313-cp313-win_amd64.whl", hash = "sha256:680359d932801c76d2e9c9068d05c6b107f2584b2a5b88831c83962eb9984c1b", size = 1436875, upload-time = "2024-10-07T19:24:42.762Z" },
-    { url = "https://files.pythonhosted.org/packages/8d/a7/4b27c50537ebca8bec139b872861f9d2bf501c5ec51fcf897cb924d9e264/black-24.10.0-py3-none-any.whl", hash = "sha256:3bb2b7a1f7b685f85b11fed1ef10f8a9148bceb49853e47a294a3dd963c1dd7d", size = 206898, upload-time = "2024-10-07T19:20:48.317Z" },
-]
-
 [[package]]
 name = "blinker"
 version = "1.9.0"
@@ -1306,15 +1259,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/4e/8c/f3147f5c4b73e7550fe5f9352eaa956ae838d5c51eb58e7a25b9f3e2643b/decorator-5.2.1-py3-none-any.whl", hash = "sha256:d316bb415a2d9e2d2b3abcc4084c6502fc09240e292cd76a76afc106a1c8e04a", size = 9190, upload-time = "2025-02-24T04:41:32.565Z" },
 ]
 
-[[package]]
-name = "dill"
-version = "0.4.0"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/12/80/630b4b88364e9a8c8c5797f4602d0f76ef820909ee32f0bacb9f90654042/dill-0.4.0.tar.gz", hash = "sha256:0633f1d2df477324f53a895b02c901fb961bdbf65a17122586ea7019292cbcf0", size = 186976, upload-time = "2025-04-16T00:41:48.867Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/50/3d/9373ad9c56321fdab5b41197068e1d8c25883b3fea29dd361f9b55116869/dill-0.4.0-py3-none-any.whl", hash = "sha256:44f54bf6412c2c8464c14e8243eb163690a9800dbe2c367330883b19c7561049", size = 119668, upload-time = "2025-04-16T00:41:47.671Z" },
-]
-
 [[package]]
 name = "diskcache"
 version = "5.6.3"
@@ -2907,15 +2851,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/d9/33/1f075bf72b0b747cb3288d011319aaf64083cf2efef8354174e3ed4540e2/ipython_pygments_lexers-1.1.1-py3-none-any.whl", hash = "sha256:a9462224a505ade19a605f71f8fa63c2048833ce50abc86768a0d81d876dc81c", size = 8074, upload-time = "2025-01-17T11:24:33.271Z" },
 ]
 
-[[package]]
-name = "isort"
-version = "5.13.2"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/87/f9/c1eb8635a24e87ade2efce21e3ce8cd6b8630bb685ddc9cdaca1349b2eb5/isort-5.13.2.tar.gz", hash = "sha256:48fdfcb9face5d58a4f6dde2e72a1fb8dcaf8ab26f95ab49fab84c2ddefb0109", size = 175303, upload-time = "2023-12-13T20:37:26.124Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/d1/b3/8def84f539e7d2289a02f0524b944b15d7c75dab7628bedf1c4f0992029c/isort-5.13.2-py3-none-any.whl", hash = "sha256:8ca5e72a8d85860d5a3fa69b8745237f2939afe12dbf656afbcb47fe72d947a6", size = 92310, upload-time = "2023-12-13T20:37:23.244Z" },
-]
-
 [[package]]
 name = "jaraco-classes"
 version = "3.4.0"
@@ -3781,15 +3716,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/15/67/c94f8f5440bc42d54113a2d99de0d6107f06b5a33f31823e52b2715d856f/maturin-1.11.5-py3-none-win_arm64.whl", hash = "sha256:9348f7f0a346108e0c96e6719be91da4470bd43c15802435e9f4157f5cca43d4", size = 7624029, upload-time = "2026-01-09T11:06:08.728Z" },
 ]
 
-[[package]]
-name = "mccabe"
-version = "0.7.0"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/e7/ff/0ffefdcac38932a54d2b5eed4e0ba8a408f215002cd178ad1df0f2806ff8/mccabe-0.7.0.tar.gz", hash = "sha256:348e0240c33b60bbdf4e523192ef919f28cb2c3d7d5c7794f74009290f236325", size = 9658, upload-time = "2022-01-24T01:14:51.113Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/27/1a/1f68f9ba0c207934b35b86a8ca3aad8395a3d6dd7921c0686e23853ff5a9/mccabe-0.7.0-py2.py3-none-any.whl", hash = "sha256:6c2d30ab6be0e4a46919781807b4f0d834ebdd6c6e3dca0bda5a15f863427b6e", size = 7350, upload-time = "2022-01-24T01:14:49.62Z" },
-]
-
 [[package]]
 name = "mcp"
 version = "1.25.0"
@@ -4273,15 +4199,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/b7/da/7d22601b625e241d4f23ef1ebff8acfc60da633c9e7e7922e24d10f592b3/multidict-6.7.0-py3-none-any.whl", hash = "sha256:394fc5c42a333c9ffc3e421a4c85e08580d990e08b99f6bf35b4132114c5dcb3", size = 12317, upload-time = "2025-10-06T14:52:29.272Z" },
 ]
 
-[[package]]
-name = "mypy-extensions"
-version = "1.1.0"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/a2/6e/371856a3fb9d31ca8dac321cda606860fa4548858c0cc45d9d1d4ca2628b/mypy_extensions-1.1.0.tar.gz", hash = "sha256:52e68efc3284861e772bbcd66823fde5ae21fd2fdb51c62a211403730b916558", size = 6343, upload-time = "2025-04-22T14:54:24.164Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/79/7b/2c79738432f5c924bef5071f933bcc9efd0473bac3b4aa584a6f7c1c8df8/mypy_extensions-1.1.0-py3-none-any.whl", hash = "sha256:1be4cccdb0f2482337c4743e60421de3a356cd97508abadd57d47403e94f5505", size = 4963, upload-time = "2025-04-22T14:54:22.983Z" },
-]
-
 [[package]]
 name = "narwhals"
 version = "2.15.0"
@@ -5124,12 +5041,10 @@ sklearn-onnx = [
 [package.dev-dependencies]
 dev = [
     { name = "a2a-sdk" },
-    { name = "black" },
     { name = "catboost" },
     { name = "crewai" },
     { name = "fastapi" },
     { name = "google-adk" },
-    { name = "isort" },
     { name = "lightgbm" },
     { name = "lightning", version = "2.1.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.12'" },
     { name = "lightning", version = "2.6.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.12'" },
@@ -5145,7 +5060,6 @@ dev = [
     { name = "pyarrow" },
     { name = "pydantic" },
     { name = "pydantic-ai" },
-    { name = "pylint" },
     { name = "pytest" },
     { name = "pytest-cov" },
     { name = "pytest-lazy-fixture" },
@@ -5186,12 +5100,10 @@ provides-extras = ["onnx", "onnxruntime", "sklearn-onnx", "opentelemetry"]
 [package.metadata.requires-dev]
 dev = [
     { name = "a2a-sdk", specifier = ">=0.3.22" },
-    { name = "black", specifier = ">=24.3.0,<25.0.0" },
     { name = "catboost", specifier = ">=1.2.5" },
     { name = "crewai", specifier = ">=0.118.0" },
     { name = "fastapi", specifier = ">=0.115.0,<1.0.0" },
     { name = "google-adk", specifier = ">=1.27.2" },
-    { name = "isort", specifier = ">=5.13.2,<6.0.0" },
     { name = "lightgbm", specifier = ">=4.0.0" },
     { name = "lightning", marker = "python_full_version < '3.12'", specifier = "~=2.1.2" },
     { name = "lightning", marker = "python_full_version >= '3.12'", specifier = ">=2.4.0" },
@@ -5207,7 +5119,6 @@ dev = [
     { name = "pyarrow", specifier = ">=18.0.0" },
     { name = "pydantic", specifier = ">=2.10.5" },
     { name = "pydantic-ai", specifier = ">=0.0.41" },
-    { name = "pylint", specifier = ">=3.0.0,<4.0.0" },
     { name = "pytest", specifier = ">=7.0.0,<8.0.0" },
     { name = "pytest-cov", specifier = ">=5.0.0,<6.0.0" },
     { name = "pytest-lazy-fixture", specifier = ">=0.6.3,<1.0.0" },
@@ -6505,25 +6416,6 @@ crypto = [
     { name = "cryptography" },
 ]
 
-[[package]]
-name = "pylint"
-version = "3.3.9"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "astroid" },
-    { name = "colorama", marker = "sys_platform == 'win32'" },
-    { name = "dill" },
-    { name = "isort" },
-    { name = "mccabe" },
-    { name = "platformdirs" },
-    { name = "tomli", marker = "python_full_version < '3.11'" },
-    { name = "tomlkit" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/04/9d/81c84a312d1fa8133b0db0c76148542a98349298a01747ab122f9314b04e/pylint-3.3.9.tar.gz", hash = "sha256:d312737d7b25ccf6b01cc4ac629b5dcd14a0fcf3ec392735ac70f137a9d5f83a", size = 1525946, upload-time = "2025-10-05T18:41:43.786Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/1a/a7/69460c4a6af7575449e615144aa2205b89408dc2969b87bc3df2f262ad0b/pylint-3.3.9-py3-none-any.whl", hash = "sha256:01f9b0462c7730f94786c283f3e52a1fbdf0494bbe0971a78d7277ef46a751e7", size = 523465, upload-time = "2025-10-05T18:41:41.766Z" },
-]
-
 [[package]]
 name = "pymdown-extensions"
 version = "10.20"
@@ -7949,15 +7841,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/c7/18/c86eb8e0202e32dd3df50d43d7ff9854f8e0603945ff398974c1d91ac1ef/tomli_w-1.2.0-py3-none-any.whl", hash = "sha256:188306098d013b691fcadc011abd66727d3c414c571bb01b1a174ba8c983cf90", size = 6675, upload-time = "2025-01-15T12:07:22.074Z" },
 ]
 
-[[package]]
-name = "tomlkit"
-version = "0.14.0"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/c3/af/14b24e41977adb296d6bd1fb59402cf7d60ce364f90c890bd2ec65c43b5a/tomlkit-0.14.0.tar.gz", hash = "sha256:cf00efca415dbd57575befb1f6634c4f42d2d87dbba376128adb42c121b87064", size = 187167, upload-time = "2026-01-13T01:14:53.304Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/b5/11/87d6d29fb5d237229d67973a6c9e06e048f01cf4994dee194ab0ea841814/tomlkit-0.14.0-py3-none-any.whl", hash = "sha256:592064ed85b40fa213469f81ac584f67a4f2992509a7c3ea2d632208623a3680", size = 39310, upload-time = "2026-01-13T01:14:51.965Z" },
-]
-
 [[package]]
 name = "torch"
 version = "2.6.0"

From fb66aa1a8b9e88abb76d7c63517c867a346baab2 Mon Sep 17 00:00:00 2001
From: Thorrester <sjforrester32@gmail.com>
Date: Fri, 15 May 2026 17:29:06 -0400
Subject: [PATCH 2/2] adding fluent layer

---
 .../src/experiment/experimentcard.rs          |  15 +
 crates/opsml_experiment/Cargo.toml            |   2 +-
 crates/opsml_experiment/src/active.rs         | 105 +++++++
 crates/opsml_experiment/src/error.rs          |   8 +
 crates/opsml_experiment/src/experiment.rs     |  36 ++-
 crates/opsml_experiment/src/fluent.rs         | 135 +++++++++
 crates/opsml_experiment/src/lib.rs            |   2 +
 crates/opsml_experiment/tests/active_stack.rs |  35 +++
 crates/opsml_interfaces/src/error.rs          |   3 +
 .../src/model/base/interface.rs               |  73 ++++-
 crates/opsml_mocks/src/mock.rs                |  10 +
 .../src/registries/server/helper.rs           |   6 +
 .../dashboard/utils.agent-pagination.test.ts  | 115 ++++++++
 .../lib/components/scouter/dashboard/utils.ts |  66 ++++-
 .../trace/__tests__/mockData.test.ts          |  19 +-
 .../src/lib/components/trace/mockData.ts      |  96 +++++--
 .../lib/components/trace/validation.test.ts   |  63 ++++
 .../[name]/[version]/observability/+page.ts   |   9 +
 .../observability/__tests__/page.test.ts      |  21 ++
 .../[name]/[version]/observability/+page.ts   |  35 ++-
 .../observability/__tests__/page.test.ts      |  16 ++
 py-opsml/docs/docs/cards/experiment/fluent.md |  37 +++
 py-opsml/docs/docs/cards/experiment/usage.md  |  15 +
 .../docs/docs/cards/frameworks/catboost.md    |   9 +
 .../docs/docs/cards/frameworks/huggingface.md |  10 +
 .../docs/docs/cards/frameworks/lightgbm.md    |  10 +
 .../docs/docs/cards/frameworks/lightning.md   |  10 +
 py-opsml/docs/docs/cards/frameworks/onnx.md   |   9 +
 .../docs/docs/cards/frameworks/sklearn.md     |  10 +
 .../docs/docs/cards/frameworks/tensorflow.md  |   9 +
 py-opsml/docs/docs/cards/frameworks/torch.md  |   9 +
 .../docs/docs/cards/frameworks/xgboost.md     |  10 +
 py-opsml/docs/docs/cards/modelcard.md         |  52 ++--
 py-opsml/docs/docs/cards/overview.md          |  30 +-
 py-opsml/examples/getting_started.py          |  22 +-
 py-opsml/examples/model/catboost_model.py     |  59 ++--
 py-opsml/examples/model/custom_model.py       |  17 +-
 py-opsml/examples/model/hf_model.py           |  76 ++---
 py-opsml/examples/model/lightgbm_booster.py   | 100 +++----
 py-opsml/examples/model/lightning_model.py    | 108 +++----
 py-opsml/examples/model/onnx_model.py         |  90 +++---
 py-opsml/examples/model/sklearn_model.py      | 126 +++-----
 py-opsml/examples/model/tensorflow_model.py   | 124 +++-----
 py-opsml/examples/model/torch_model.py        |  98 ++-----
 py-opsml/examples/model/xgb_booster.py        |  79 ++---
 py-opsml/mkdocs.yml                           |  11 +
 py-opsml/python/opsml/__init__.py             |  22 ++
 py-opsml/python/opsml/_opsml.pyi              | 180 ++++++++++++
 py-opsml/python/opsml/catboost/__init__.py    |   3 +
 py-opsml/python/opsml/catboost/__init__.pyi   |  20 ++
 py-opsml/python/opsml/huggingface/__init__.py |   3 +
 .../python/opsml/huggingface/__init__.pyi     |  23 ++
 py-opsml/python/opsml/lightgbm/__init__.py    |   3 +
 py-opsml/python/opsml/lightgbm/__init__.pyi   |  20 ++
 py-opsml/python/opsml/lightning/__init__.py   |   3 +
 py-opsml/python/opsml/lightning/__init__.pyi  |  20 ++
 py-opsml/python/opsml/onnx/__init__.py        |   3 +
 py-opsml/python/opsml/onnx/__init__.pyi       |  19 ++
 py-opsml/python/opsml/sklearn/__init__.py     |   3 +
 py-opsml/python/opsml/sklearn/__init__.pyi    |  21 ++
 py-opsml/python/opsml/stubs/card.pyi          |  60 ++++
 py-opsml/python/opsml/stubs/opsml.pyi         | 117 ++++++++
 py-opsml/python/opsml/tensorflow/__init__.py  |   3 +
 py-opsml/python/opsml/tensorflow/__init__.pyi |  20 ++
 py-opsml/python/opsml/torch/__init__.py       |   3 +
 py-opsml/python/opsml/torch/__init__.pyi      |  20 ++
 py-opsml/python/opsml/xgboost/__init__.py     |   3 +
 py-opsml/python/opsml/xgboost/__init__.pyi    |  20 ++
 py-opsml/src/experiment.rs                    |  13 +-
 py-opsml/src/flavors.rs                       | 211 ++++++++++++++
 py-opsml/src/lib.rs                           |  11 +
 py-opsml/tests/conftest.py                    |  11 +-
 .../tests/interfaces/model/test_custom.py     |  46 ++-
 py-opsml/tests/test_fluent.py                 | 228 +++++++++++++++
 py-opsml/tests/test_fluent_flavors.py         | 272 ++++++++++++++++++
 75 files changed, 2707 insertions(+), 674 deletions(-)
 create mode 100644 crates/opsml_experiment/src/active.rs
 create mode 100644 crates/opsml_experiment/src/fluent.rs
 create mode 100644 crates/opsml_experiment/tests/active_stack.rs
 create mode 100644 crates/opsml_server/opsml_ui/src/lib/components/scouter/dashboard/utils.agent-pagination.test.ts
 create mode 100644 py-opsml/docs/docs/cards/experiment/fluent.md
 create mode 100644 py-opsml/docs/docs/cards/frameworks/catboost.md
 create mode 100644 py-opsml/docs/docs/cards/frameworks/huggingface.md
 create mode 100644 py-opsml/docs/docs/cards/frameworks/lightgbm.md
 create mode 100644 py-opsml/docs/docs/cards/frameworks/lightning.md
 create mode 100644 py-opsml/docs/docs/cards/frameworks/onnx.md
 create mode 100644 py-opsml/docs/docs/cards/frameworks/sklearn.md
 create mode 100644 py-opsml/docs/docs/cards/frameworks/tensorflow.md
 create mode 100644 py-opsml/docs/docs/cards/frameworks/torch.md
 create mode 100644 py-opsml/docs/docs/cards/frameworks/xgboost.md
 create mode 100644 py-opsml/python/opsml/catboost/__init__.py
 create mode 100644 py-opsml/python/opsml/catboost/__init__.pyi
 create mode 100644 py-opsml/python/opsml/huggingface/__init__.py
 create mode 100644 py-opsml/python/opsml/huggingface/__init__.pyi
 create mode 100644 py-opsml/python/opsml/lightgbm/__init__.py
 create mode 100644 py-opsml/python/opsml/lightgbm/__init__.pyi
 create mode 100644 py-opsml/python/opsml/lightning/__init__.py
 create mode 100644 py-opsml/python/opsml/lightning/__init__.pyi
 create mode 100644 py-opsml/python/opsml/onnx/__init__.py
 create mode 100644 py-opsml/python/opsml/onnx/__init__.pyi
 create mode 100644 py-opsml/python/opsml/sklearn/__init__.py
 create mode 100644 py-opsml/python/opsml/sklearn/__init__.pyi
 create mode 100644 py-opsml/python/opsml/tensorflow/__init__.py
 create mode 100644 py-opsml/python/opsml/tensorflow/__init__.pyi
 create mode 100644 py-opsml/python/opsml/torch/__init__.py
 create mode 100644 py-opsml/python/opsml/torch/__init__.pyi
 create mode 100644 py-opsml/python/opsml/xgboost/__init__.py
 create mode 100644 py-opsml/python/opsml/xgboost/__init__.pyi
 create mode 100644 py-opsml/src/flavors.rs
 create mode 100644 py-opsml/tests/test_fluent.py
 create mode 100644 py-opsml/tests/test_fluent_flavors.py

diff --git a/crates/opsml_cards/src/experiment/experimentcard.rs b/crates/opsml_cards/src/experiment/experimentcard.rs
index 8ce027ead4..8fe2e9dd2a 100644
--- a/crates/opsml_cards/src/experiment/experimentcard.rs
+++ b/crates/opsml_cards/src/experiment/experimentcard.rs
@@ -394,11 +394,26 @@ impl ExperimentCard {
     pub fn tags(&self) -> Vec<String> {
         self.tags.clone()
     }
+
+    pub fn add_tag(&mut self, tag: String) {
+        self.tags.push(tag);
+    }
+
+    #[pyo3(name = "set_tags")]
+    pub fn set_tags_method(&mut self, val: Vec<String>) {
+        self.tags = val;
+    }
+
     #[setter]
     pub fn set_tags(&mut self, val: Vec<String>) {
         self.tags = val;
     }
 
+    #[pyo3(name = "add_subexperiment_experiment")]
+    pub fn add_subexperiment_experiment_py(&mut self, uid: &str) {
+        self.uids.experimentcard_uids.push(uid.to_string());
+    }
+
     #[getter]
     pub fn uids<'py>(&self, py: Python<'py>) -> Result<Bound<'py, PyAny>, CardError> {
         use pyo3::IntoPyObjectExt;
diff --git a/crates/opsml_experiment/Cargo.toml b/crates/opsml_experiment/Cargo.toml
index 10fa0a3a16..8d65aa6203 100644
--- a/crates/opsml_experiment/Cargo.toml
+++ b/crates/opsml_experiment/Cargo.toml
@@ -33,5 +33,5 @@ walkdir = { workspace = true }
 
 [features]
 default = []
+python = ["opsml-cards/python", "opsml-registry/python", "opsml-types/python"]
 server = ["opsml-storage/server"]
-
diff --git a/crates/opsml_experiment/src/active.rs b/crates/opsml_experiment/src/active.rs
new file mode 100644
index 0000000000..189fb32a7f
--- /dev/null
+++ b/crates/opsml_experiment/src/active.rs
@@ -0,0 +1,105 @@
+//! Active experiment stack.
+//!
+//! Scope: SINGLE-THREADED. Concurrent experiments per process are not
+//! supported by the fluent free functions. Concurrent users must use the
+//! explicit `exp.log_metric(...)` form on a captured `Experiment`.
+//!
+//! TODO(threading): migrate to a `contextvars`-backed thread/task-local stack
+//! in a follow-up slice once usage justifies the extra boundary complexity.
+
+use crate::error::ExperimentError;
+use crate::experiment::Experiment;
+use pyo3::prelude::*;
+use std::sync::{Mutex, OnceLock};
+
+pub struct ActiveStack<T> {
+    inner: Mutex<Vec<T>>,
+}
+
+impl<T> Default for ActiveStack<T> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl<T> ActiveStack<T> {
+    pub const fn new() -> Self {
+        Self {
+            inner: Mutex::new(Vec::new()),
+        }
+    }
+
+    pub fn push(&self, value: T) -> Result<(), ExperimentError> {
+        self.inner
+            .lock()
+            .map_err(|_| ExperimentError::ActiveStackPoisoned)?
+            .push(value);
+        Ok(())
+    }
+
+    pub fn depth(&self) -> Result<usize, ExperimentError> {
+        Ok(self
+            .inner
+            .lock()
+            .map_err(|_| ExperimentError::ActiveStackPoisoned)?
+            .len())
+    }
+
+    pub fn pop(&self) -> Result<Option<T>, ExperimentError> {
+        Ok(self
+            .inner
+            .lock()
+            .map_err(|_| ExperimentError::ActiveStackPoisoned)?
+            .pop())
+    }
+
+    pub fn with_top<R>(&self, f: impl FnOnce(&T) -> R) -> Result<Option<R>, ExperimentError> {
+        let guard = self
+            .inner
+            .lock()
+            .map_err(|_| ExperimentError::ActiveStackPoisoned)?;
+        Ok(guard.last().map(f))
+    }
+}
+
+struct ActiveExperiment {
+    uid: String,
+    exp: Py<Experiment>,
+}
+
+static ACTIVE: OnceLock<ActiveStack<ActiveExperiment>> = OnceLock::new();
+
+fn stack() -> &'static ActiveStack<ActiveExperiment> {
+    ACTIVE.get_or_init(ActiveStack::new)
+}
+
+pub fn push(exp: Py<Experiment>, py: Python<'_>) -> Result<(), ExperimentError> {
+    let uid = exp.borrow(py).uid().to_string();
+    stack().push(ActiveExperiment { uid, exp })
+}
+
+pub fn pop(_py: Python<'_>, expected_uid: &str) -> Result<Option<Py<Experiment>>, ExperimentError> {
+    let popped = stack().pop()?;
+    if let Some(active) = popped {
+        if active.uid != expected_uid {
+            tracing::warn!(
+                expected = expected_uid,
+                actual = %active.uid,
+                "active experiment stack pop mismatch"
+            );
+        }
+        Ok(Some(active.exp))
+    } else {
+        Ok(None)
+    }
+}
+
+pub fn current(py: Python<'_>) -> Result<Py<Experiment>, ExperimentError> {
+    stack()
+        .with_top(|active| active.exp.clone_ref(py))?
+        .ok_or(ExperimentError::NoActiveExperiment)
+}
+
+pub fn depth() -> Result<usize, ExperimentError> {
+    stack().depth()
+}
diff --git a/crates/opsml_experiment/src/error.rs b/crates/opsml_experiment/src/error.rs
index 5c1de0dcb2..c9a27347c7 100644
--- a/crates/opsml_experiment/src/error.rs
+++ b/crates/opsml_experiment/src/error.rs
@@ -75,6 +75,14 @@ pub enum ExperimentError {
 
     #[error("{0}")]
     MissingImportError(String),
+
+    #[error(
+        "no active experiment — wrap your code in `with start_experiment(...) as exp:` or call `exp.log_metric(...)` directly"
+    )]
+    NoActiveExperiment,
+
+    #[error("active experiment stack poisoned")]
+    ActiveStackPoisoned,
 }
 
 impl From<std::ffi::OsString> for ExperimentError {
diff --git a/crates/opsml_experiment/src/experiment.rs b/crates/opsml_experiment/src/experiment.rs
index b3d2c48997..9863dcd921 100644
--- a/crates/opsml_experiment/src/experiment.rs
+++ b/crates/opsml_experiment/src/experiment.rs
@@ -191,6 +191,10 @@ pub struct Experiment {
 }
 
 impl Experiment {
+    pub fn uid(&self) -> &str {
+        &self.uid
+    }
+
     #[allow(clippy::too_many_arguments)]
     #[instrument(skip_all)]
     pub fn new(
@@ -478,8 +482,9 @@ impl Experiment {
         Ok(Py::new(py, experiment)?.bind(py).clone())
     }
 
-    fn __enter__(slf: PyRef<'_, Self>) -> Result<PyRef<'_, Self>, ExperimentError> {
+    fn __enter__(slf: Py<Self>, py: Python<'_>) -> Result<Py<Self>, ExperimentError> {
         debug!("Starting experiment");
+        crate::active::push(slf.clone_ref(py), py)?;
         Ok(slf)
     }
 
@@ -491,6 +496,9 @@ impl Experiment {
         exc_value: Option<Py<PyAny>>,
         traceback: Option<Py<PyAny>>,
     ) -> Result<bool, ExperimentError> {
+        let uid = slf.uid().to_string();
+        let _ = crate::active::pop(py, &uid)?;
+
         let card_status = if let (Some(exc_type), Some(exc_value), Some(traceback)) =
             (&exc_type, &exc_value, &traceback)
         {
@@ -608,6 +616,15 @@ impl Experiment {
         Ok(())
     }
 
+    #[pyo3(name = "log_param", signature = (name, value))]
+    pub fn log_param_alias(
+        &self,
+        name: String,
+        value: Bound<'_, PyAny>,
+    ) -> Result<(), ExperimentError> {
+        self.log_parameter(name, value)
+    }
+
     /// Logs multiple parameters
     /// Accepts either a dictionary of parameters or a list of parameters.
     /// # Arguments
@@ -643,6 +660,11 @@ impl Experiment {
         Ok(())
     }
 
+    #[pyo3(name = "log_params")]
+    pub fn log_params_alias(&self, parameters: &Bound<'_, PyAny>) -> Result<(), ExperimentError> {
+        self.log_parameters(parameters)
+    }
+
     /// Logs an artifact from a path
     /// # Arguments
     /// * `lpath` - local path to load artifact from
@@ -776,7 +798,7 @@ impl Experiment {
         Ok(())
     }
 
-    fn log_artifacts(&self, path: PathBuf) -> Result<(), ExperimentError> {
+    pub fn log_artifacts(&self, path: PathBuf) -> Result<(), ExperimentError> {
         let encryption_key = self.artifact_key.get_crypt_key()?;
 
         for entry in WalkDir::new(&path) {
@@ -825,6 +847,16 @@ impl Experiment {
         Ok(self.experiment.bind(py).clone())
     }
 
+    pub fn set_tag(&mut self, py: Python<'_>, tag: String) -> Result<(), ExperimentError> {
+        self.experiment.bind(py).call_method1("add_tag", (tag,))?;
+        Ok(())
+    }
+
+    pub fn set_tags(&mut self, py: Python<'_>, tags: Vec<String>) -> Result<(), ExperimentError> {
+        self.experiment.bind(py).call_method1("set_tags", (tags,))?;
+        Ok(())
+    }
+
     #[pyo3(signature = (card, version_type = VersionType::Minor, pre_tag = None, build_tag = None, save_kwargs = None))]
     pub fn register_card(
         &mut self,
diff --git a/crates/opsml_experiment/src/fluent.rs b/crates/opsml_experiment/src/fluent.rs
new file mode 100644
index 0000000000..debc4cdfa7
--- /dev/null
+++ b/crates/opsml_experiment/src/fluent.rs
@@ -0,0 +1,135 @@
+use crate::active;
+use crate::error::ExperimentError;
+use crate::experiment::Experiment;
+use opsml_types::cards::experiment::Metric;
+use pyo3::prelude::*;
+use std::path::PathBuf;
+
+/// Log a metric on the active experiment created by `with start_experiment(...)`.
+/// Raises `NoActiveExperiment` when no experiment is active. Active state is
+/// process-global and single-threaded; concurrent code should call Experiment methods directly.
+#[pyfunction]
+#[pyo3(signature = (name, value, step=None, timestamp=None, created_at=None))]
+pub fn log_metric(
+    py: Python<'_>,
+    name: String,
+    value: f64,
+    step: Option<i32>,
+    timestamp: Option<i64>,
+    created_at: Option<chrono::DateTime<chrono::Utc>>,
+) -> Result<(), ExperimentError> {
+    let exp = active::current(py)?;
+    exp.borrow(py)
+        .log_metric(name, value, step, timestamp, created_at)
+}
+
+/// Log multiple metrics on the active experiment created by `with start_experiment(...)`.
+/// Raises `NoActiveExperiment` when no experiment is active. Active state is
+/// process-global and single-threaded; concurrent code should call Experiment methods directly.
+#[pyfunction]
+pub fn log_metrics(py: Python<'_>, metrics: Vec<Metric>) -> Result<(), ExperimentError> {
+    let exp = active::current(py)?;
+    exp.borrow(py).log_metrics(metrics)
+}
+
+/// Log a parameter on the active experiment created by `with start_experiment(...)`.
+/// Raises `NoActiveExperiment` when no experiment is active. Active state is
+/// process-global and single-threaded; concurrent code should call Experiment methods directly.
+#[pyfunction]
+#[pyo3(signature = (name, value))]
+pub fn log_param(
+    py: Python<'_>,
+    name: String,
+    value: Bound<'_, PyAny>,
+) -> Result<(), ExperimentError> {
+    let exp = active::current(py)?;
+    exp.borrow(py).log_parameter(name, value)
+}
+
+/// Log multiple parameters on the active experiment created by `with start_experiment(...)`.
+/// Raises `NoActiveExperiment` when no experiment is active. Active state is
+/// process-global and single-threaded; concurrent code should call Experiment methods directly.
+#[pyfunction]
+pub fn log_params(py: Python<'_>, params: Bound<'_, PyAny>) -> Result<(), ExperimentError> {
+    let exp = active::current(py)?;
+    exp.borrow(py).log_parameters(&params)
+}
+
+/// Log a file artifact on the active experiment created by `with start_experiment(...)`.
+/// Raises `NoActiveExperiment` when no experiment is active. Active state is
+/// process-global and single-threaded; concurrent code should call Experiment methods directly.
+#[pyfunction]
+#[pyo3(signature = (lpath, rpath=None))]
+pub fn log_artifact(
+    py: Python<'_>,
+    lpath: PathBuf,
+    rpath: Option<String>,
+) -> Result<(), ExperimentError> {
+    let exp = active::current(py)?;
+    exp.borrow(py).log_artifact(lpath, rpath)
+}
+
+/// Log a directory of artifacts on the active experiment created by `with start_experiment(...)`.
+/// Raises `NoActiveExperiment` when no experiment is active. Active state is
+/// process-global and single-threaded; concurrent code should call Experiment methods directly.
+#[pyfunction]
+pub fn log_artifacts(py: Python<'_>, path: PathBuf) -> Result<(), ExperimentError> {
+    let exp = active::current(py)?;
+    exp.borrow(py).log_artifacts(path)
+}
+
+/// Log a Python figure on the active experiment created by `with start_experiment(...)`.
+/// Raises `NoActiveExperiment` when no experiment is active. Active state is
+/// process-global and single-threaded; concurrent code should call Experiment methods directly.
+#[pyfunction]
+#[pyo3(signature = (name, figure, kwargs=None))]
+pub fn log_figure(
+    py: Python<'_>,
+    name: String,
+    figure: Bound<'_, PyAny>,
+    kwargs: Option<Bound<'_, pyo3::types::PyDict>>,
+) -> Result<(), ExperimentError> {
+    let exp = active::current(py)?;
+    exp.borrow(py)
+        .log_figure(py, name, &figure, kwargs.as_ref())
+}
+
+/// Log a saved figure file on the active experiment created by `with start_experiment(...)`.
+/// Raises `NoActiveExperiment` when no experiment is active. Active state is
+/// process-global and single-threaded; concurrent code should call Experiment methods directly.
+#[pyfunction]
+#[pyo3(signature = (lpath, rpath=None))]
+pub fn log_figure_from_path(
+    py: Python<'_>,
+    lpath: PathBuf,
+    rpath: Option<String>,
+) -> Result<(), ExperimentError> {
+    let exp = active::current(py)?;
+    exp.borrow(py).log_figure_from_path(lpath, rpath)
+}
+
+/// Add one tag to the active experiment created by `with start_experiment(...)`.
+/// Raises `NoActiveExperiment` when no experiment is active. Active state is
+/// process-global and single-threaded; concurrent code should call Experiment methods directly.
+#[pyfunction]
+pub fn set_tag(py: Python<'_>, tag: String) -> Result<(), ExperimentError> {
+    let exp = active::current(py)?;
+    exp.borrow_mut(py).set_tag(py, tag)
+}
+
+/// Replace tags on the active experiment created by `with start_experiment(...)`.
+/// Raises `NoActiveExperiment` when no experiment is active. Active state is
+/// process-global and single-threaded; concurrent code should call Experiment methods directly.
+#[pyfunction]
+pub fn set_tags(py: Python<'_>, tags: Vec<String>) -> Result<(), ExperimentError> {
+    let exp = active::current(py)?;
+    exp.borrow_mut(py).set_tags(py, tags)
+}
+
+/// Return the active experiment created by `with start_experiment(...)`.
+/// Raises `NoActiveExperiment` when no experiment is active. Active state is
+/// process-global and single-threaded; concurrent code should pass Experiment explicitly.
+#[pyfunction]
+pub fn active_experiment(py: Python<'_>) -> Result<Py<Experiment>, ExperimentError> {
+    active::current(py)
+}
diff --git a/crates/opsml_experiment/src/lib.rs b/crates/opsml_experiment/src/lib.rs
index 09e92a9dd7..76f94b320c 100644
--- a/crates/opsml_experiment/src/lib.rs
+++ b/crates/opsml_experiment/src/lib.rs
@@ -1,5 +1,7 @@
+pub mod active;
 pub mod error;
 pub mod experiment;
+pub mod fluent;
 pub mod hardware_queue;
 
 pub use experiment::*;
diff --git a/crates/opsml_experiment/tests/active_stack.rs b/crates/opsml_experiment/tests/active_stack.rs
new file mode 100644
index 0000000000..4a60dbca84
--- /dev/null
+++ b/crates/opsml_experiment/tests/active_stack.rs
@@ -0,0 +1,35 @@
+use opsml_experiment::active::ActiveStack;
+
+#[test]
+fn active_stack_push_then_top_returns_value() {
+    let s = ActiveStack::<String>::new();
+    s.push("a".into()).unwrap();
+    let got = s.with_top(|v| v.clone()).unwrap();
+    assert_eq!(got, Some("a".to_string()));
+}
+
+#[test]
+fn active_stack_push_two_pop_returns_last() {
+    let s = ActiveStack::<String>::new();
+    s.push("a".into()).unwrap();
+    s.push("b".into()).unwrap();
+    assert_eq!(s.pop().unwrap(), Some("b".into()));
+    assert_eq!(s.pop().unwrap(), Some("a".into()));
+}
+
+#[test]
+fn active_stack_pop_empty_returns_none() {
+    let s = ActiveStack::<String>::new();
+    assert_eq!(s.pop().unwrap(), None);
+}
+
+#[test]
+fn active_stack_depth_reflects_push_pop() {
+    let s = ActiveStack::<String>::new();
+    assert_eq!(s.depth().unwrap(), 0);
+    s.push("a".into()).unwrap();
+    s.push("b".into()).unwrap();
+    assert_eq!(s.depth().unwrap(), 2);
+    s.pop().unwrap();
+    assert_eq!(s.depth().unwrap(), 1);
+}
diff --git a/crates/opsml_interfaces/src/error.rs b/crates/opsml_interfaces/src/error.rs
index bedb623be7..ee3760892e 100644
--- a/crates/opsml_interfaces/src/error.rs
+++ b/crates/opsml_interfaces/src/error.rs
@@ -166,6 +166,9 @@ pub enum ModelInterfaceError {
     #[error("{0}")]
     Error(String),
 
+    #[error("Unexpected ModelInterface.__init__ keyword argument(s): {0}")]
+    UnexpectedKwargs(String),
+
     #[error("No ONNX session detected in interface for loading")]
     OnnxSessionMissing,
 
diff --git a/crates/opsml_interfaces/src/model/base/interface.rs b/crates/opsml_interfaces/src/model/base/interface.rs
index 24076e1e27..a4dcab1a64 100644
--- a/crates/opsml_interfaces/src/model/base/interface.rs
+++ b/crates/opsml_interfaces/src/model/base/interface.rs
@@ -22,7 +22,7 @@ use opsml_types::{
 };
 use pyo3::IntoPyObjectExt;
 use pyo3::prelude::*;
-use pyo3::types::PyDict;
+use pyo3::types::{PyDict, PyTuple};
 use scouter_client::{DataType as DriftDataType, drifter::PyDrifter};
 use std::collections::HashMap;
 use std::fs;
@@ -63,11 +63,8 @@ pub struct ModelInterface {
     pub version: String,
 }
 
-#[pymethods]
 impl ModelInterface {
-    #[new]
     #[allow(clippy::too_many_arguments)]
-    #[pyo3(signature = (model=None, sample_data=None, task_type=None, drift_profile=None, version=None))]
     pub fn new<'py>(
         py: Python,
         model: Option<&Bound<'py, PyAny>>,
@@ -117,6 +114,74 @@ impl ModelInterface {
             version: version.unwrap_or(CommonKwargs::Undefined.to_string()),
         })
     }
+}
+
+impl Default for ModelInterface {
+    fn default() -> Self {
+        Self {
+            model: None,
+            data_type: DataType::NotProvided,
+            task_type: TaskType::Undefined,
+            schema: FeatureSchema::default(),
+            model_type: ModelType::Unknown,
+            interface_type: ModelInterfaceType::Base,
+            onnx_session: None,
+            drift_profile: DriftProfileMap::new(),
+            sample_data: SampleData::default(),
+            version: CommonKwargs::Undefined.to_string(),
+        }
+    }
+}
+
+#[pymethods]
+impl ModelInterface {
+    #[new]
+    #[pyo3(signature = (*_args, **_kwargs))]
+    pub fn __new__(_args: &Bound<'_, PyTuple>, _kwargs: Option<&Bound<'_, PyDict>>) -> Self {
+        Self::default()
+    }
+
+    /// Initialize a ModelInterface.
+    ///
+    /// Extra keyword arguments are accepted in the Python signature only for
+    /// PyO3 subclass initialization compatibility. Direct base construction
+    /// rejects unknown keyword arguments.
+    #[allow(clippy::too_many_arguments)]
+    #[pyo3(signature = (model=None, sample_data=None, task_type=None, drift_profile=None, version=None, **_kwargs))]
+    pub fn __init__<'py>(
+        &mut self,
+        py: Python<'py>,
+        model: Option<&Bound<'py, PyAny>>,
+        sample_data: Option<&Bound<'py, PyAny>>,
+        task_type: Option<TaskType>,
+        drift_profile: Option<&Bound<'py, PyAny>>,
+        version: Option<String>,
+        _kwargs: Option<&Bound<'py, PyDict>>,
+    ) -> Result<(), ModelInterfaceError> {
+        let already_initialized = self.model.is_some()
+            || self.data_type != DataType::NotProvided
+            || self.task_type != TaskType::Undefined
+            || !self.drift_profile.profiles.is_empty()
+            || self.version != CommonKwargs::Undefined.to_string();
+
+        if already_initialized {
+            return Ok(());
+        }
+
+        if let Some(kwargs) = _kwargs
+            && !kwargs.is_empty()
+        {
+            let unexpected = kwargs
+                .iter()
+                .map(|(key, _)| key.to_string())
+                .collect::<Vec<_>>()
+                .join(", ");
+            return Err(ModelInterfaceError::UnexpectedKwargs(unexpected));
+        }
+
+        *self = Self::new(py, model, sample_data, task_type, drift_profile, version)?;
+        Ok(())
+    }
 
     #[getter]
     pub fn get_onnx_session<'py>(
diff --git a/crates/opsml_mocks/src/mock.rs b/crates/opsml_mocks/src/mock.rs
index 64e65ca0ab..d6de86fef7 100644
--- a/crates/opsml_mocks/src/mock.rs
+++ b/crates/opsml_mocks/src/mock.rs
@@ -387,6 +387,16 @@ impl OpsmlTestServer {
         // unset env vars
         self.remove_env_vars_for_client()?;
 
+        #[cfg(feature = "server")]
+        {
+            app_state().reset_app_state().map_err(|e| {
+                TestServerError::CustomError(format!("Failed to reset app state: {e}"))
+            })?;
+            reset_storage_client().map_err(|e| {
+                TestServerError::CustomError(format!("Failed to reset storage client: {e}"))
+            })?;
+        }
+
         if self.root_dir.exists() {
             let max_attempts = 5;
             let mut attempt = 0;
diff --git a/crates/opsml_registry/src/registries/server/helper.rs b/crates/opsml_registry/src/registries/server/helper.rs
index bc551591f8..2350b2930e 100644
--- a/crates/opsml_registry/src/registries/server/helper.rs
+++ b/crates/opsml_registry/src/registries/server/helper.rs
@@ -4,6 +4,9 @@ use opsml_settings::config::DatabaseSettings;
 #[cfg(feature = "server")]
 use opsml_sql::{enums::client::SqlClientEnum, traits::CardLogicTrait};
 
+#[cfg(feature = "server")]
+use opsml_state::app_state;
+
 #[cfg(feature = "server")]
 use opsml_storage::reset_storage_client;
 
@@ -110,6 +113,8 @@ impl RegistryTestHelper {
             std::env::set_var("OPSML_TRACKING_URI", config.connection_uri);
             std::env::set_var("OPSML_STORAGE_URI", storage_uri);
         }
+
+        let _ = app_state().reset_app_state();
     }
 
     #[cfg(not(feature = "server"))]
@@ -138,6 +143,7 @@ impl RegistryTestHelper {
             std::env::remove_var("OPSML_STORAGE_URI");
         }
 
+        let _ = app_state().reset_app_state();
         let _ = reset_storage_client();
     }
 }
diff --git a/crates/opsml_server/opsml_ui/src/lib/components/scouter/dashboard/utils.agent-pagination.test.ts b/crates/opsml_server/opsml_ui/src/lib/components/scouter/dashboard/utils.agent-pagination.test.ts
new file mode 100644
index 0000000000..f73b0808c9
--- /dev/null
+++ b/crates/opsml_server/opsml_ui/src/lib/components/scouter/dashboard/utils.agent-pagination.test.ts
@@ -0,0 +1,115 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  type AgentMonitoringPageData,
+  refreshAgentMonitoringData,
+} from "./utils";
+import type {
+  AgentEvalWorkflowPaginationResponse,
+  EvalRecordPaginationResponse,
+} from "$lib/components/scouter/agent/types";
+
+const agentPageCalls = vi.hoisted(() => ({
+  records: [] as unknown[],
+  workflows: [] as unknown[],
+}));
+
+vi.mock("$lib/components/scouter/agent/utils", async () => {
+  const actual = await vi.importActual<typeof import("$lib/components/scouter/agent/utils")>(
+    "$lib/components/scouter/agent/utils",
+  );
+  return {
+    ...actual,
+    getServerEvalRecordPage: vi.fn(async (_fetch, request) => {
+      agentPageCalls.records.push(request);
+      return makeRecordPage("record-next");
+    }),
+    getServerAgentEvalWorkflowPage: vi.fn(async (_fetch, request) => {
+      agentPageCalls.workflows.push(request);
+      return makeWorkflowPage("workflow-next");
+    }),
+  };
+});
+
+/** Builds the small pagination shape required by the dashboard refresh helper. */
+function makeRecordPage(label: string): EvalRecordPaginationResponse {
+  return {
+    items: [{ record_id: label, id: 1, created_at: "2026-01-01T00:00:00Z" }],
+    has_next: false,
+    has_previous: false,
+  } as unknown as EvalRecordPaginationResponse;
+}
+
+/** Builds the small workflow pagination shape required by the dashboard refresh helper. */
+function makeWorkflowPage(label: string): AgentEvalWorkflowPaginationResponse {
+  return {
+    items: [{ workflow_id: label }],
+    has_next: false,
+    has_previous: false,
+  } as unknown as AgentEvalWorkflowPaginationResponse;
+}
+
+/** Builds a successful agent monitoring payload with distinct record and workflow pages. */
+function makeMonitoringData(): Extract<AgentMonitoringPageData, { status: "success" }> {
+  return {
+    status: "success",
+    uid: "agent-card-uid",
+    registryType: "agent",
+    profile: {
+      config: { uid: "eval-uid", space: "prod" },
+    },
+    selectedTimeRange: {
+      label: "15m",
+      value: "15min",
+      startTime: "2026-01-01T00:00:00Z",
+      endTime: "2026-01-01T00:15:00Z",
+      bucketInterval: "1 minutes",
+    },
+    selectedData: {
+      metrics: { task: {}, workflow: {} },
+      driftAlerts: { items: [], has_next: false, has_previous: false },
+      records: makeRecordPage("record-current"),
+      workflows: makeWorkflowPage("workflow-current"),
+    },
+  } as unknown as Extract<AgentMonitoringPageData, { status: "success" }>;
+}
+
+describe("refreshAgentMonitoringData pagination", () => {
+  beforeEach(() => {
+    agentPageCalls.records.length = 0;
+    agentPageCalls.workflows.length = 0;
+    Object.defineProperty(window, "innerWidth", { configurable: true, value: 1280 });
+  });
+
+  it("preserves workflows when paging records, then preserves records when paging workflows", async () => {
+    const monitoringData = makeMonitoringData();
+    const originalWorkflows = monitoringData.selectedData.workflows;
+
+    await refreshAgentMonitoringData(vi.fn() as unknown as typeof fetch, monitoringData, {
+      recordCursor: {
+        cursor: { id: 7, created_at: "2026-01-01T00:01:00Z" },
+        direction: "next",
+      },
+    });
+
+    expect(agentPageCalls.records).toHaveLength(1);
+    expect(agentPageCalls.workflows).toHaveLength(0);
+    expect(monitoringData.selectedData.records.items[0].record_id).toBe("record-next");
+    expect(monitoringData.selectedData.workflows).toBe(originalWorkflows);
+
+    const pagedRecords = monitoringData.selectedData.records;
+
+    await refreshAgentMonitoringData(vi.fn() as unknown as typeof fetch, monitoringData, {
+      workflowCursor: {
+        cursor: { id: 11, created_at: "2026-01-01T00:02:00Z" },
+        direction: "previous",
+      },
+    });
+
+    expect(agentPageCalls.records).toHaveLength(1);
+    expect(agentPageCalls.workflows).toHaveLength(1);
+    expect(monitoringData.selectedData.records).toBe(pagedRecords);
+    expect(monitoringData.selectedData.workflows.items[0]).toMatchObject({
+      workflow_id: "workflow-next",
+    });
+  });
+});
diff --git a/crates/opsml_server/opsml_ui/src/lib/components/scouter/dashboard/utils.ts b/crates/opsml_server/opsml_ui/src/lib/components/scouter/dashboard/utils.ts
index 29a565d6f2..43238723bf 100644
--- a/crates/opsml_server/opsml_ui/src/lib/components/scouter/dashboard/utils.ts
+++ b/crates/opsml_server/opsml_ui/src/lib/components/scouter/dashboard/utils.ts
@@ -264,6 +264,55 @@ async function loadAgentRecordsAndWorkflows(
   return { records, workflows };
 }
 
+/** Loads agent eval pages while preserving the sibling table during single-table pagination. */
+async function loadAgentEvaluationPages(
+  fetch: typeof globalThis.fetch,
+  uid: string,
+  space: string,
+  timeRange: TimeRange,
+  selectedData: SelectedAgentData,
+  recordCursor?: { cursor: RecordCursor; direction: string },
+  workflowCursor?: { cursor: RecordCursor; direction: string },
+): Promise<{
+  records: EvalRecordPaginationResponse;
+  workflows: AgentEvalWorkflowPaginationResponse;
+}> {
+  if (recordCursor && !workflowCursor) {
+    const records = await getServerEvalRecordPage(fetch, {
+      service_info: { uid, space },
+      cursor_id: recordCursor.cursor.id,
+      cursor_created_at: recordCursor.cursor.created_at,
+      direction: recordCursor.direction,
+      start_datetime: timeRange.startTime,
+      end_datetime: timeRange.endTime,
+    });
+
+    return { records, workflows: selectedData.workflows };
+  }
+
+  if (workflowCursor && !recordCursor) {
+    const workflows = await getServerAgentEvalWorkflowPage(fetch, {
+      service_info: { uid, space },
+      cursor_id: workflowCursor.cursor.id,
+      cursor_created_at: workflowCursor.cursor.created_at,
+      direction: workflowCursor.direction,
+      start_datetime: timeRange.startTime,
+      end_datetime: timeRange.endTime,
+    });
+
+    return { records: selectedData.records, workflows };
+  }
+
+  return loadAgentRecordsAndWorkflows(
+    fetch,
+    uid,
+    space,
+    timeRange,
+    recordCursor,
+    workflowCursor,
+  );
+}
+
 /** Loads all data for the agent evaluation dashboard (metrics, alerts, records, workflows) */
 export async function loadAgentData(
   fetch: typeof globalThis.fetch,
@@ -449,7 +498,19 @@ export async function refreshAgentMonitoringData(
       timeRange,
     );
     if (fresh.status === "success") {
-      monitoringData.selectedData = fresh.selectedData;
+      if (options.recordCursor && !options.workflowCursor) {
+        monitoringData.selectedData = {
+          ...fresh.selectedData,
+          workflows: monitoringData.selectedData.workflows,
+        };
+      } else if (options.workflowCursor && !options.recordCursor) {
+        monitoringData.selectedData = {
+          ...fresh.selectedData,
+          records: monitoringData.selectedData.records,
+        };
+      } else {
+        monitoringData.selectedData = fresh.selectedData;
+      }
     }
     return;
   }
@@ -481,11 +542,12 @@ export async function refreshAgentMonitoringData(
   const [metrics, driftAlerts, { records, workflows }] = await Promise.all([
     metricsPromise,
     alertsPromise,
-    loadAgentRecordsAndWorkflows(
+    loadAgentEvaluationPages(
       fetch,
       uid,
       space,
       timeRange,
+      monitoringData.selectedData,
       options.recordCursor,
       options.workflowCursor,
     ),
diff --git a/crates/opsml_server/opsml_ui/src/lib/components/trace/__tests__/mockData.test.ts b/crates/opsml_server/opsml_ui/src/lib/components/trace/__tests__/mockData.test.ts
index f51f9ecc6f..f313ab063a 100644
--- a/crates/opsml_server/opsml_ui/src/lib/components/trace/__tests__/mockData.test.ts
+++ b/crates/opsml_server/opsml_ui/src/lib/components/trace/__tests__/mockData.test.ts
@@ -11,7 +11,7 @@ import {
   serviceNamespaceClause,
   statusCodeClause,
 } from "../clause";
-import { getMockTracePage } from "../mockData";
+import { getMockTraceFacets, getMockTracePage } from "../mockData";
 
 describe("trace mock FilterClause evaluation", () => {
   it("filters by AND of service and status code", () => {
@@ -81,4 +81,21 @@ describe("trace mock FilterClause evaluation", () => {
     expect(withoutClause.items.length).toBeGreaterThan(withImpossibleClause.items.length);
     expect(withImpossibleClause.items).toHaveLength(0);
   });
+
+  it("applies time and entity filters consistently to page and facet mocks", () => {
+    const filters = {
+      start_time: "2099-01-01T00:00:00Z",
+      end_time: "2099-01-01T00:15:00Z",
+      entity_uid: "missing-entity",
+      limit: 100,
+    };
+
+    const page = getMockTracePage(filters);
+    const facets = getMockTraceFacets(filters);
+
+    expect(page.items).toHaveLength(0);
+    expect(facets.total_count).toBe(0);
+    expect(facets.services).toHaveLength(0);
+    expect(facets.status_codes).toHaveLength(0);
+  });
 });
diff --git a/crates/opsml_server/opsml_ui/src/lib/components/trace/mockData.ts b/crates/opsml_server/opsml_ui/src/lib/components/trace/mockData.ts
index 8726e39a49..4d0a5c1e72 100644
--- a/crates/opsml_server/opsml_ui/src/lib/components/trace/mockData.ts
+++ b/crates/opsml_server/opsml_ui/src/lib/components/trace/mockData.ts
@@ -32,6 +32,40 @@ function ts(baseMs: number, offsetMs: number = 0): string {
   return new Date(baseMs + offsetMs).toISOString();
 }
 
+/** Returns true when a mock trace carries the requested entity UID in resource attributes. */
+function matchesEntityUid(item: TraceListItem, entityUid: string): boolean {
+  return item.resource_attributes.some((attr) => String(attr.value) === entityUid);
+}
+
+/** Applies the same mock trace filters to pages, metrics, and facets. */
+function applyTraceFilters(
+  items: TraceListItem[],
+  filters: Pick<TraceFilters, "clause" | "start_time" | "end_time" | "trace_ids" | "entity_uid">,
+): TraceListItem[] {
+  let filtered = items;
+
+  if (filters.clause) {
+    filtered = filtered.filter((item) => evaluateClause(item, filters.clause!));
+  }
+  if (filters.start_time) {
+    const start = new Date(filters.start_time).getTime();
+    filtered = filtered.filter((item) => new Date(item.start_time).getTime() >= start);
+  }
+  if (filters.end_time) {
+    const end = new Date(filters.end_time).getTime();
+    filtered = filtered.filter((item) => new Date(item.start_time).getTime() <= end);
+  }
+  if (filters.trace_ids && filters.trace_ids.length > 0) {
+    const traceIds = new Set(filters.trace_ids);
+    filtered = filtered.filter((item) => traceIds.has(item.trace_id));
+  }
+  if (filters.entity_uid) {
+    filtered = filtered.filter((item) => matchesEntityUid(item, filters.entity_uid!));
+  }
+
+  return filtered;
+}
+
 function span(
   overrides: Partial<TraceSpan> & Pick<TraceSpan, "trace_id" | "span_id" | "span_name" | "start_time" | "service_name" | "root_span_id">,
 ): TraceSpan {
@@ -457,19 +491,26 @@ const ALL_BUILDERS = [
 ];
 
 // Service/scope metadata for each trace (used for TraceListItem)
-const TRACE_META: { service: string; scope: string; namespace: string; version: string; instance: string }[] = [
-  { service: "inference-api", scope: "http", namespace: "models", version: "3.2.1", instance: "pod-a" },
-  { service: "inference-api", scope: "http", namespace: "models", version: "3.2.1", instance: "pod-b" },
-  { service: "llm-gateway", scope: "genai", namespace: "agents", version: "1.0.0", instance: "pod-c" },
-  { service: "data-pipeline", scope: "batch", namespace: "features", version: "2.4.0", instance: "worker-a" },
-  { service: "llm-gateway", scope: "genai", namespace: "agents", version: "1.0.0", instance: "pod-d" },
-  { service: "inference-api", scope: "http", namespace: "models", version: "2.1.0", instance: "pod-e" },
-  { service: "monitoring-agent", scope: "drift", namespace: "monitoring", version: "0.9.0", instance: "pod-f" },
-  { service: "inference-api", scope: "http", namespace: "models", version: "3.2.1", instance: "pod-g" },
-  { service: "llm-gateway", scope: "genai", namespace: "agents", version: "1.0.0", instance: "pod-h" },
-  { service: "data-pipeline", scope: "batch", namespace: "features", version: "2.4.0", instance: "worker-b" },
-  { service: "inference-api", scope: "http", namespace: "models", version: "1.5.0", instance: "pod-i" },
-  { service: "monitoring-agent", scope: "drift", namespace: "monitoring", version: "0.9.0", instance: "pod-j" },
+const TRACE_META: {
+  service: string;
+  scope: string;
+  namespace: string;
+  version: string;
+  instance: string;
+  entityUid: string;
+}[] = [
+  { service: "inference-api", scope: "http", namespace: "models", version: "3.2.1", instance: "pod-a", entityUid: "service-uid-1" },
+  { service: "inference-api", scope: "http", namespace: "models", version: "3.2.1", instance: "pod-b", entityUid: "service-uid-1" },
+  { service: "llm-gateway", scope: "genai", namespace: "agents", version: "1.0.0", instance: "pod-c", entityUid: "eval-uid-abc" },
+  { service: "data-pipeline", scope: "batch", namespace: "features", version: "2.4.0", instance: "worker-a", entityUid: "data-eval-1" },
+  { service: "llm-gateway", scope: "genai", namespace: "agents", version: "1.0.0", instance: "pod-d", entityUid: "eval-uid-abc" },
+  { service: "inference-api", scope: "http", namespace: "models", version: "2.1.0", instance: "pod-e", entityUid: "model-eval-1" },
+  { service: "monitoring-agent", scope: "drift", namespace: "monitoring", version: "0.9.0", instance: "pod-f", entityUid: "monitor-eval-1" },
+  { service: "inference-api", scope: "http", namespace: "models", version: "3.2.1", instance: "pod-g", entityUid: "model-eval-2" },
+  { service: "llm-gateway", scope: "genai", namespace: "agents", version: "1.0.0", instance: "pod-h", entityUid: "eval-uid-abc" },
+  { service: "data-pipeline", scope: "batch", namespace: "features", version: "2.4.0", instance: "worker-b", entityUid: "data-eval-2" },
+  { service: "inference-api", scope: "http", namespace: "models", version: "1.5.0", instance: "pod-i", entityUid: "model-eval-3" },
+  { service: "monitoring-agent", scope: "drift", namespace: "monitoring", version: "0.9.0", instance: "pod-j", entityUid: "monitor-eval-2" },
 ];
 
 // Build all spans once at module load
@@ -504,6 +545,7 @@ function buildTraceListItems(): TraceListItem[] {
         { key: "service.namespace", value: TRACE_META[i].namespace },
         { key: "service.version", value: TRACE_META[i].version },
         { key: "service.instance.id", value: TRACE_META[i].instance },
+        { key: "scouter.entity.uid", value: TRACE_META[i].entityUid },
       ],
     };
   });
@@ -565,17 +607,7 @@ function buildMetricBuckets(
 // ── Public API ───────────────────────────────────────────────────────────
 
 export function getMockTracePage(filters: TraceFilters): TracePaginationResponse {
-  let items = buildTraceListItems();
-
-  if (filters.clause) items = items.filter((item) => evaluateClause(item, filters.clause!));
-  if (filters.start_time) {
-    const start = new Date(filters.start_time).getTime();
-    items = items.filter((item) => new Date(item.start_time).getTime() >= start);
-  }
-  if (filters.end_time) {
-    const end = new Date(filters.end_time).getTime();
-    items = items.filter((item) => new Date(item.start_time).getTime() <= end);
-  }
+  const items = applyTraceFilters(buildTraceListItems(), filters);
 
   const limit = filters.limit || 50;
 
@@ -607,9 +639,12 @@ export function getMockTraceMetrics(
   const startTime = request.start_time || new Date(Date.now() - 15 * 60_000).toISOString();
   const endTime = request.end_time || new Date().toISOString();
   const bucketInterval = request.bucket_interval || "1 minutes";
-  const matchingItems = request.clause
-    ? buildTraceListItems().filter((item) => evaluateClause(item, request.clause!))
-    : buildTraceListItems();
+  const matchingItems = applyTraceFilters(buildTraceListItems(), {
+    clause: request.clause,
+    start_time: startTime,
+    end_time: endTime,
+    entity_uid: request.entity_uid,
+  });
   const buckets = buildMetricBuckets(startTime, endTime, bucketInterval);
 
   return {
@@ -624,17 +659,16 @@ export function getMockTraceFacets(filters: TraceFilters) {
   const items = buildTraceListItems();
   const filterItems = (dimension: "service" | "status_code") => {
     const clause = removeClauseDimension(filters.clause, dimension);
-    return clause ? items.filter((item) => evaluateClause(item, clause)) : items;
+    return applyTraceFilters(items, { ...filters, clause });
   };
   const serviceItems = filterItems("service");
   const statusItems = filterItems("status_code");
+  const totalItems = applyTraceFilters(items, filters);
 
   return {
     services: toFacetDimensions(serviceItems.map((item) => item.service_name)),
     status_codes: toFacetDimensions(statusItems.map((item) => String(item.status_code))),
-    total_count: filters.clause
-      ? items.filter((item) => evaluateClause(item, filters.clause!)).length
-      : items.length,
+    total_count: totalItems.length,
   };
 }
 
diff --git a/crates/opsml_server/opsml_ui/src/lib/components/trace/validation.test.ts b/crates/opsml_server/opsml_ui/src/lib/components/trace/validation.test.ts
index 556459f952..5e709b8bf0 100644
--- a/crates/opsml_server/opsml_ui/src/lib/components/trace/validation.test.ts
+++ b/crates/opsml_server/opsml_ui/src/lib/components/trace/validation.test.ts
@@ -48,6 +48,69 @@ describe("trace request validation", () => {
     });
   });
 
+  it("rejects clause depth greater than 8", () => {
+    const clause = Array.from({ length: 8 }).reduce(
+      (child) => ({ op: "not", value: child }),
+      serviceClause("checkout") as unknown,
+    );
+
+    expect(validateTraceFilters({ clause })).toEqual({
+      ok: false,
+      error: "clause is too deeply nested",
+    });
+  });
+
+  it("rejects clauses with more than 64 leaves", () => {
+    const clause = {
+      op: "or",
+      value: Array.from({ length: 65 }, (_, index) =>
+        serviceClause(`svc-${index}`),
+      ),
+    };
+
+    expect(validateTraceFilters({ clause })).toEqual({
+      ok: false,
+      error: "clause has too many leaves",
+    });
+  });
+
+  it("rejects more than 100 trace IDs", () => {
+    expect(
+      validateTraceFilters({
+        trace_ids: Array.from({ length: 101 }, (_, index) => `trace-${index}`),
+      }),
+    ).toEqual({
+      ok: false,
+      error: "trace_ids has too many values",
+    });
+  });
+
+  it("rejects time ranges over 90 days", () => {
+    expect(
+      validateTraceFilters({
+        start_time: "2026-01-01T00:00:00Z",
+        end_time: "2026-04-02T00:00:00Z",
+      }),
+    ).toEqual({
+      ok: false,
+      error: "time range is too large",
+    });
+  });
+
+  it("rejects attr keys longer than 256 characters", () => {
+    expect(
+      validateTraceFilters({
+        clause: {
+          op: "attr",
+          value: { key: "x".repeat(257), value: "checkout" },
+        },
+      }),
+    ).toEqual({
+      ok: false,
+      error: "attr.key is too long",
+    });
+  });
+
   it("requires metrics start and end times", () => {
     expect(validateTraceMetricsRequest({ end_time: "2026-01-02T00:00:00Z" })).toEqual({
       ok: false,
diff --git a/crates/opsml_server/opsml_ui/src/routes/opsml/[registry]/card/[space]/[name]/[version]/observability/+page.ts b/crates/opsml_server/opsml_ui/src/routes/opsml/[registry]/card/[space]/[name]/[version]/observability/+page.ts
index 144b525821..80b5ad56d8 100644
--- a/crates/opsml_server/opsml_ui/src/routes/opsml/[registry]/card/[space]/[name]/[version]/observability/+page.ts
+++ b/crates/opsml_server/opsml_ui/src/routes/opsml/[registry]/card/[space]/[name]/[version]/observability/+page.ts
@@ -77,6 +77,15 @@ export const load: PageLoad = async ({ fetch, depends, parent, url }) => {
 
     const card = metadata as PromptCard | ServiceCard;
     const entity_uid = getEvalProfileOrUid(card);
+    if (registryTypeLower === RegistryType.Prompt && !entity_uid) {
+      return {
+        status: "not_found" as const,
+        errorMessage: "Prompt observability requires an attached evaluation profile.",
+        initialFilters: fallbackFilters,
+        trace_facets: { services: [], status_codes: [], total_count: 0 },
+        mockMode: useMockFallback,
+      };
+    }
 
     let initialTrace: TraceListItem | undefined;
     let initialTraceSpans: TraceSpansResponse | undefined;
diff --git a/crates/opsml_server/opsml_ui/src/routes/opsml/[registry]/card/[space]/[name]/[version]/observability/__tests__/page.test.ts b/crates/opsml_server/opsml_ui/src/routes/opsml/[registry]/card/[space]/[name]/[version]/observability/__tests__/page.test.ts
index 499a1aad3f..adb5dbdd13 100644
--- a/crates/opsml_server/opsml_ui/src/routes/opsml/[registry]/card/[space]/[name]/[version]/observability/__tests__/page.test.ts
+++ b/crates/opsml_server/opsml_ui/src/routes/opsml/[registry]/card/[space]/[name]/[version]/observability/__tests__/page.test.ts
@@ -201,6 +201,27 @@ describe('observability +page.ts load() — scouter disabled', () => {
   });
 });
 
+describe('observability +page.ts load() — prompt eval profile guard', () => {
+  it('returns not_found for prompt cards without an eval profile UID', async () => {
+    const mockFetch = vi.fn();
+    const ctx = makeLoadCtx(
+      {
+        metadata: { ...PROMPT_METADATA, eval_profile: undefined },
+        devMockEnabled: false,
+        settings: { scouter_enabled: true },
+      },
+      {},
+      mockFetch as unknown as typeof fetch,
+    );
+
+    const result = (await load(ctx)) as Record<string, unknown>;
+
+    expect(result.status).toBe('not_found');
+    expect((result as { errorMessage?: string }).errorMessage).toMatch(/evaluation profile/i);
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+});
+
 describe('observability +page.ts load() — mock mode', () => {
   // In mock mode, getMockTraceMetrics / getMockTracePage are used instead of
   // real fetch calls. However getServerTraceFacets is NOT guarded by the mock
diff --git a/crates/opsml_server/opsml_ui/src/routes/opsml/agent/[registry]/card/[space]/[name]/[version]/observability/+page.ts b/crates/opsml_server/opsml_ui/src/routes/opsml/agent/[registry]/card/[space]/[name]/[version]/observability/+page.ts
index df3294bee6..70713cad94 100644
--- a/crates/opsml_server/opsml_ui/src/routes/opsml/agent/[registry]/card/[space]/[name]/[version]/observability/+page.ts
+++ b/crates/opsml_server/opsml_ui/src/routes/opsml/agent/[registry]/card/[space]/[name]/[version]/observability/+page.ts
@@ -40,6 +40,14 @@ export const load: PageLoad = async ({ fetch, depends, parent, url }) => {
   const useMockFallback = Boolean(parentData.devMockEnabled);
 
   const initialTraceId = url.searchParams.get("trace_id") ?? undefined;
+  const fallbackFilters: TracePageFilter = {
+    filters: {
+      start_time: new Date(Date.now() - 15 * 60 * 1000).toISOString(),
+      end_time: new Date().toISOString(),
+    },
+    bucket_interval: "1 minutes",
+    selected_range: "15min",
+  };
 
   try {
     depends("trace:data");
@@ -57,6 +65,23 @@ export const load: PageLoad = async ({ fetch, depends, parent, url }) => {
     const entity_uid = isPrompt
       ? ((metadata as PromptCard).eval_profile?.config.uid ?? "")
       : undefined;
+    if (isPrompt && !entity_uid) {
+      return {
+        status: "not_found" as const,
+        errorMessage: "Prompt observability requires an attached evaluation profile.",
+        initialFilters: fallbackFilters,
+        trace_facets: {
+          services: [],
+          namespaces: [],
+          versions: [],
+          instance_ids: [],
+          status_codes: [],
+          total_count: 0,
+        },
+        mockMode: useMockFallback,
+      };
+    }
+
     const serviceName = isPrompt ? undefined : metadata.name;
     const serviceNamespace = isPrompt ? undefined : metadata.space;
     const serviceVersion = isPrompt ? undefined : metadata.version;
@@ -223,18 +248,10 @@ export const load: PageLoad = async ({ fetch, depends, parent, url }) => {
       }
     }
 
-    const initialFilters: TracePageFilter = {
-      filters: {
-        start_time: new Date(Date.now() - 15 * 60 * 1000).toISOString(),
-        end_time: new Date().toISOString(),
-      },
-      bucket_interval: "1 minutes",
-      selected_range: "15min",
-    };
     return {
       status: "error" as const,
       errorMessage,
-      initialFilters,
+      initialFilters: fallbackFilters,
       trace_facets: {
         services: [],
         namespaces: [],
diff --git a/crates/opsml_server/opsml_ui/src/routes/opsml/agent/[registry]/card/[space]/[name]/[version]/observability/__tests__/page.test.ts b/crates/opsml_server/opsml_ui/src/routes/opsml/agent/[registry]/card/[space]/[name]/[version]/observability/__tests__/page.test.ts
index 5a5151c48a..fe7ad70e4c 100644
--- a/crates/opsml_server/opsml_ui/src/routes/opsml/agent/[registry]/card/[space]/[name]/[version]/observability/__tests__/page.test.ts
+++ b/crates/opsml_server/opsml_ui/src/routes/opsml/agent/[registry]/card/[space]/[name]/[version]/observability/__tests__/page.test.ts
@@ -112,4 +112,20 @@ describe("agent observability page load", () => {
     expect(traceCalls.facets[0]).toMatchObject({ entity_uid: "eval-profile-1" });
     expect(traceCalls.metrics[0]).not.toHaveProperty("clause");
   });
+
+  it("returns not_found for prompt cards without an eval profile UID", async () => {
+    const result = (await load(makeLoadCtx({
+      registry_type: RegistryType.Prompt,
+      name: "triage-prompt",
+      space: "prod",
+      version: "1.2.3",
+      eval_profile: undefined,
+    }))) as Record<string, unknown>;
+
+    expect(result.status).toBe("not_found");
+    expect((result as { errorMessage?: string }).errorMessage).toMatch(/evaluation profile/i);
+    expect(traceCalls.metrics).toHaveLength(0);
+    expect(traceCalls.page).toHaveLength(0);
+    expect(traceCalls.facets).toHaveLength(0);
+  });
 });
diff --git a/py-opsml/docs/docs/cards/experiment/fluent.md b/py-opsml/docs/docs/cards/experiment/fluent.md
new file mode 100644
index 0000000000..c99d9bccd6
--- /dev/null
+++ b/py-opsml/docs/docs/cards/experiment/fluent.md
@@ -0,0 +1,37 @@
+# Fluent Experiment API
+
+The fluent API is an MLflow-style layer over the existing `Experiment` methods.
+It only works inside an active `with start_experiment(...)` block. OpsML does
+not silently create an experiment when none is active.
+
+```python
+import opsml
+from opsml import start_experiment
+
+with start_experiment(space="examples", name="run"):
+    opsml.log_metric("accuracy", 0.91)
+    opsml.log_params({"n_estimators": 100, "criterion": "gini"})
+    opsml.set_tag("source:mlflow-migration")
+```
+
+Available functions:
+
+- `opsml.log_metric`
+- `opsml.log_metrics`
+- `opsml.log_param`
+- `opsml.log_params`
+- `opsml.log_artifact`
+- `opsml.log_artifacts`
+- `opsml.log_figure`
+- `opsml.log_figure_from_path`
+- `opsml.set_tag`
+- `opsml.set_tags`
+- `opsml.active_experiment`
+
+The active experiment stack is process-global in this release. Concurrent
+threads or asyncio tasks should use the explicit `exp.log_metric(...)` form on
+a captured experiment object.
+
+Framework model logging lives in typed flavor packages such as
+`opsml.sklearn.log_model(...)`, `opsml.xgboost.log_model(...)`, and
+`opsml.huggingface.log_model(...)`.
diff --git a/py-opsml/docs/docs/cards/experiment/usage.md b/py-opsml/docs/docs/cards/experiment/usage.md
index fd773bce2f..24930c3422 100644
--- a/py-opsml/docs/docs/cards/experiment/usage.md
+++ b/py-opsml/docs/docs/cards/experiment/usage.md
@@ -40,6 +40,7 @@ Every experiment can log parameters, metrics, artifacts and figures. This is don
 - **Figures** are visualizations that you want to track. This could include things like confusion matrices, ROC curves, or any other plots that help you understand your experiment.
 
 ```python
+import opsml
 from opsml import start_experiment
 
 with start_experiment("opsml") as exp:
@@ -47,8 +48,22 @@ with start_experiment("opsml") as exp:
     exp.log_metric("accuracy", 0.95)
     exp.log_figure("confusion_matrix.png", confusion_matrix)
     exp.log_artifact("my_local_artifact.txt")
+
+with start_experiment("opsml"):
+    opsml.log_param("learning_rate", 0.001)
+    opsml.log_metric("accuracy", 0.95)
+    opsml.log_figure("confusion_matrix.png", confusion_matrix)
+    opsml.log_artifact("my_local_artifact.txt")
 ```
 
+Both forms call the same Rust methods. Pick whichever reads better for the
+workflow.
+
+!!! note
+    `opsml.set_tag(tag)` accepts one string label. OpsML tags are free-form
+    labels, not key/value metadata. Use `opsml.log_param(key, value)` for
+    key/value experiment metadata.
+
 ### Artifacts
 
 You can log artifacts from your local filesystem via the `log_artifact` or `log_artifacts` methods. **Note** - artifacts must already be saved to disk before they can be logged. More information can be found [here](/opsml/docs/api/opsml/#opsml._opsml.Experiment.log_artifact)
diff --git a/py-opsml/docs/docs/cards/frameworks/catboost.md b/py-opsml/docs/docs/cards/frameworks/catboost.md
new file mode 100644
index 0000000000..6cba74faff
--- /dev/null
+++ b/py-opsml/docs/docs/cards/frameworks/catboost.md
@@ -0,0 +1,9 @@
+# Logging a CatBoost Model
+
+OpsML registers CatBoost models through `opsml.catboost.log_model`.
+
+```python
+--8<-- "examples/model/catboost_model.py"
+```
+
+See also: [ModelCards](../modelcard.md) and [Fluent API](../experiment/fluent.md).
diff --git a/py-opsml/docs/docs/cards/frameworks/huggingface.md b/py-opsml/docs/docs/cards/frameworks/huggingface.md
new file mode 100644
index 0000000000..77178e038e
--- /dev/null
+++ b/py-opsml/docs/docs/cards/frameworks/huggingface.md
@@ -0,0 +1,10 @@
+# Logging a HuggingFace Transformers Model
+
+OpsML registers HuggingFace Transformers models through
+`opsml.huggingface.log_model`.
+
+```python
+--8<-- "examples/model/hf_model.py"
+```
+
+See also: [ModelCards](../modelcard.md) and [Fluent API](../experiment/fluent.md).
diff --git a/py-opsml/docs/docs/cards/frameworks/lightgbm.md b/py-opsml/docs/docs/cards/frameworks/lightgbm.md
new file mode 100644
index 0000000000..7f555f77ed
--- /dev/null
+++ b/py-opsml/docs/docs/cards/frameworks/lightgbm.md
@@ -0,0 +1,10 @@
+# Logging a LightGBM Model
+
+OpsML registers native LightGBM `Booster` models through
+`opsml.lightgbm.log_model`.
+
+```python
+--8<-- "examples/model/lightgbm_booster.py"
+```
+
+See also: [ModelCards](../modelcard.md) and [Fluent API](../experiment/fluent.md).
diff --git a/py-opsml/docs/docs/cards/frameworks/lightning.md b/py-opsml/docs/docs/cards/frameworks/lightning.md
new file mode 100644
index 0000000000..5f1a7d3c67
--- /dev/null
+++ b/py-opsml/docs/docs/cards/frameworks/lightning.md
@@ -0,0 +1,10 @@
+# Logging a PyTorch Lightning Model
+
+OpsML registers PyTorch Lightning trainers through
+`opsml.lightning.log_model`.
+
+```python
+--8<-- "examples/model/lightning_model.py"
+```
+
+See also: [ModelCards](../modelcard.md) and [Fluent API](../experiment/fluent.md).
diff --git a/py-opsml/docs/docs/cards/frameworks/onnx.md b/py-opsml/docs/docs/cards/frameworks/onnx.md
new file mode 100644
index 0000000000..b1eef20cb9
--- /dev/null
+++ b/py-opsml/docs/docs/cards/frameworks/onnx.md
@@ -0,0 +1,9 @@
+# Logging an ONNX Model
+
+OpsML registers ONNX models through `opsml.onnx.log_model`.
+
+```python
+--8<-- "examples/model/onnx_model.py"
+```
+
+See also: [ModelCards](../modelcard.md) and [Fluent API](../experiment/fluent.md).
diff --git a/py-opsml/docs/docs/cards/frameworks/sklearn.md b/py-opsml/docs/docs/cards/frameworks/sklearn.md
new file mode 100644
index 0000000000..b1017924d8
--- /dev/null
+++ b/py-opsml/docs/docs/cards/frameworks/sklearn.md
@@ -0,0 +1,10 @@
+# Logging a Scikit-learn Model
+
+OpsML registers scikit-learn estimators and pipelines through
+`opsml.sklearn.log_model`.
+
+```python
+--8<-- "examples/model/sklearn_model.py"
+```
+
+See also: [ModelCards](../modelcard.md) and [Fluent API](../experiment/fluent.md).
diff --git a/py-opsml/docs/docs/cards/frameworks/tensorflow.md b/py-opsml/docs/docs/cards/frameworks/tensorflow.md
new file mode 100644
index 0000000000..d3639657fb
--- /dev/null
+++ b/py-opsml/docs/docs/cards/frameworks/tensorflow.md
@@ -0,0 +1,9 @@
+# Logging a TensorFlow Model
+
+OpsML registers TensorFlow Keras models through `opsml.tensorflow.log_model`.
+
+```python
+--8<-- "examples/model/tensorflow_model.py"
+```
+
+See also: [ModelCards](../modelcard.md) and [Fluent API](../experiment/fluent.md).
diff --git a/py-opsml/docs/docs/cards/frameworks/torch.md b/py-opsml/docs/docs/cards/frameworks/torch.md
new file mode 100644
index 0000000000..6c94f71bc8
--- /dev/null
+++ b/py-opsml/docs/docs/cards/frameworks/torch.md
@@ -0,0 +1,9 @@
+# Logging a PyTorch Model
+
+OpsML registers PyTorch modules through `opsml.torch.log_model`.
+
+```python
+--8<-- "examples/model/torch_model.py"
+```
+
+See also: [ModelCards](../modelcard.md) and [Fluent API](../experiment/fluent.md).
diff --git a/py-opsml/docs/docs/cards/frameworks/xgboost.md b/py-opsml/docs/docs/cards/frameworks/xgboost.md
new file mode 100644
index 0000000000..001f58b4c9
--- /dev/null
+++ b/py-opsml/docs/docs/cards/frameworks/xgboost.md
@@ -0,0 +1,10 @@
+# Logging an XGBoost Model
+
+OpsML registers native XGBoost `Booster` models through
+`opsml.xgboost.log_model`.
+
+```python
+--8<-- "examples/model/xgb_booster.py"
+```
+
+See also: [ModelCards](../modelcard.md) and [Fluent API](../experiment/fluent.md).
diff --git a/py-opsml/docs/docs/cards/modelcard.md b/py-opsml/docs/docs/cards/modelcard.md
index be78cda9f7..e7d17d2a08 100644
--- a/py-opsml/docs/docs/cards/modelcard.md
+++ b/py-opsml/docs/docs/cards/modelcard.md
@@ -1,6 +1,23 @@
 
 ModelCards help you store, version, and track model objects.
 
+OpsML works with any ML framework. The same registration pattern applies whether
+you train with scikit-learn, XGBoost, LightGBM, CatBoost, PyTorch, PyTorch
+Lightning, TensorFlow, HuggingFace Transformers, or ONNX. Pick your framework
+below to see a runnable example.
+
+## Supported frameworks
+
+- [Scikit-learn](frameworks/sklearn.md)
+- [XGBoost](frameworks/xgboost.md)
+- [LightGBM](frameworks/lightgbm.md)
+- [CatBoost](frameworks/catboost.md)
+- [PyTorch](frameworks/torch.md)
+- [PyTorch Lightning](frameworks/lightning.md)
+- [TensorFlow](frameworks/tensorflow.md)
+- [HuggingFace Transformers](frameworks/huggingface.md)
+- [ONNX](frameworks/onnx.md)
+
 ## Features
 - **shareable**: All cards including ModelCards are shareable and searchable.
 - **auto-schema**: Auto-infer data schema.
@@ -1785,34 +1802,18 @@ class CustomInterface(ModelInterface):
 
 ### Changing Init Arguments
 
-If you find in your custom interface that you are changing class/self attributes during instantiation, you will also need to include two extra methods called `from_metadata` (staticmethod) as well as a `__new__` method. The reason for this is (1), pyo3 does not currently support custom `__init__` methods (2) `from_metadata` is called on all interfaces when loading a card from the registry and is used to initialize the class with metadata attributes.
+If you find in your custom interface that you are changing class/self attributes during instantiation, implement a normal Python `__init__` and call `super().__init__(**kwargs)`. `from_metadata` is still useful when loading a card from the registry because it initializes the class from stored metadata.
 
 The below example shows an example of how you can implement this. In the example, we are adding the `preprocessor` attribute
 
 ```python
 class CustomModel(ModelInterface):
-    def __new__( #(1)
-        cls,
-        preprocessor=None, #(2)
-        model: None | Any = None,
-        sample_data: None | Any = None,
-        task_type: None | TaskType = None,
-    ):
-        instance = super(CustomModel, cls).__new__(
-            cls,
-            model=model,
-            sample_data=sample_data,
-            task_type=task_type,
-        )
-
-        return instance
-
-    def __init__(self, preprocessor, model, sample_data, task_type):
+    def __init__(self, preprocessor=None, **kwargs):
         """Init method for the custom model interface."""
 
-        super().__init__()
+        super().__init__(**kwargs) #(1)
 
-        self.preprocessor = preprocessor #(3)
+        self.preprocessor = preprocessor #(2)
 
     def save(self, path, save_kwargs=None):
         ...
@@ -1832,11 +1833,10 @@ class CustomModel(ModelInterface):
         )
 ```
 
-1. Custom __new__ method
-2. Adding preprocessor as a class argument
-3. Assigning preprocessor to the class attribute
+1. Forward base model/sample/task arguments to `ModelInterface`
+2. Assigning preprocessor to the class attribute
 
-**Note**: If you are not changing the default class attributes, you do not need to to implement `__new__` or `from_metadata`.
+**Note**: If you are not changing the default class attributes, you do not need to implement `from_metadata`.
 
 
 ### Method Overriding Checklist
@@ -1844,7 +1844,7 @@ class CustomModel(ModelInterface):
 | Changing Class Attributes? | Methods to Implement |
 | -------------------------- | -------------------- |
 | <span class="text-alert">**No**</span> | `save`, `load`       |
-| <span class="text-alert">**Yes**</span> | `save`, `load`, `__new__`, `from_metadata` |
+| <span class="text-alert">**Yes**</span> | `save`, `load`, `__init__`, `from_metadata` |
 
 ### Loading from a Registry
 
@@ -1858,4 +1858,4 @@ class MyCustomInterface(ModelInterface):
 registry.load_card(uid="{{model uid}}", interface=MyCustomInterface) #(1)
 ```
 
-1. The interface class is passed to the `load_card` method. This is required for custom interfaces
\ No newline at end of file
+1. The interface class is passed to the `load_card` method. This is required for custom interfaces
diff --git a/py-opsml/docs/docs/cards/overview.md b/py-opsml/docs/docs/cards/overview.md
index eb4819b4c9..43bd8b7b64 100644
--- a/py-opsml/docs/docs/cards/overview.md
+++ b/py-opsml/docs/docs/cards/overview.md
@@ -40,6 +40,35 @@ Cards are one of the primary data structures of opsml. All cards store specific
   - Includes built-in UI: playground, evaluation dashboard, and trace waterfall
   - Registered in the `AgentRegistry`
 
+## Three Ways to Register a Model
+
+Use the explicit interface path when you need full control over interfaces,
+metadata, drift profiles, or save kwargs:
+
+```python
+iface = SklearnModel(model=clf, sample_data=X[:10], task_type=TaskType.Classification)
+card = ModelCard(space="examples", name="rf", interface=iface)
+exp.register_card(card)
+```
+
+Use typed flavor sugar for the common path:
+
+```python
+import opsml.sklearn
+
+with start_experiment(space="examples", name="run"):
+    card = opsml.sklearn.log_model(clf, name="rf", sample_data=X[:10])
+```
+
+Use stateless fluent logging inside an active experiment when you prefer an
+MLflow-style shape:
+
+```python
+with start_experiment(space="examples", name="run"):
+    opsml.log_metric("accuracy", 0.91)
+    opsml.log_param("n_estimators", 100)
+```
+
 ### Card Arguments
 
 All cards require a set of arguments in order to be registered. This is to ensure the card is properly assigned ownership and can be tracked. The arguments are:
@@ -267,4 +296,3 @@ model_registry.delete_card(card)
 - [PromptCard](/opsml/docs/cards/promptcard/)
 - [ServiceCard](/opsml/docs/cards/servicecard/)
 - [AgentCard](/opsml/docs/cards/agentcard/)
-
diff --git a/py-opsml/examples/getting_started.py b/py-opsml/examples/getting_started.py
index 3176e1edb4..4c8423e38f 100644
--- a/py-opsml/examples/getting_started.py
+++ b/py-opsml/examples/getting_started.py
@@ -13,7 +13,9 @@
 
 from pathlib import Path
 
-from opsml import DataCard, ModelCard, SklearnModel, TaskType
+import opsml
+import opsml.sklearn
+from opsml import DataCard, TaskType
 from opsml.data import PandasData
 from opsml.experiment import start_experiment
 from opsml.helpers.data import create_fake_data
@@ -40,25 +42,21 @@
     classifier = ensemble.RandomForestClassifier(n_estimators=10, random_state=42)
     classifier.fit(X.to_numpy(), y.to_numpy().ravel())
 
-    model_card = ModelCard(
-        space=SPACE,
+    model_card = opsml.sklearn.log_model(
+        classifier,
         name="classifier",
-        interface=SklearnModel(
-            model=classifier,
-            sample_data=X[:10],
-            task_type=TaskType.Classification,
-        ),
+        sample_data=X[:10],
+        task_type=TaskType.Classification,
     )
-    exp.register_card(model_card)
     print(f"ModelCard:     v{model_card.version}  uid={model_card.uid}")
 
     # Log metrics and parameters
-    exp.log_metric("accuracy", 0.91, step=0)
-    exp.log_parameter("n_estimators", 10)
+    opsml.log_metric("accuracy", 0.91, step=0)
+    opsml.log_param("n_estimators", 10)
 
     artifact_path = _PARENT_DIR / "genai"
     print(f"Logging artifact: {artifact_path}")
 
-    exp.log_artifacts(artifact_path)  # log all files in the genai directory as artifacts
+    opsml.log_artifacts(artifact_path)  # log all files in the genai directory as artifacts
 
 print("\nOpen http://localhost:3000 to browse registered cards.")
diff --git a/py-opsml/examples/model/catboost_model.py b/py-opsml/examples/model/catboost_model.py
index 6a521694d2..32ebaa8bfe 100644
--- a/py-opsml/examples/model/catboost_model.py
+++ b/py-opsml/examples/model/catboost_model.py
@@ -1,34 +1,35 @@
+"""CatBoost model registration with OpsML."""
+
 from typing import Tuple, cast
 
+import catboost  # type: ignore
+import opsml
+import opsml.catboost
 import pandas as pd
-from catboost import CatBoostRegressor  # type: ignore
-from opsml import CardRegistries, CatBoostModel, ModelCard, TaskType
+from opsml import TaskType, start_experiment
 from opsml.helpers.data import create_fake_data
 
-# start registries
-registry = CardRegistries()
-
-# create data
-X_train, y_train = cast(Tuple[pd.DataFrame, pd.DataFrame], create_fake_data(n_samples=1200))
-
-model = CatBoostRegressor(n_estimators=5, max_depth=3)
-model.fit(X_train.to_numpy(), y_train)
-
-model_interface = CatBoostModel(
-    model=model,
-    sample_data=X_train[0:10],
-    task_type=TaskType.Regression,
-)
-
-model_interface.create_drift_profile("drift", X_train)
-modelcard = ModelCard(interface=model_interface, space="opsml", name="my_model")
-
-# register model
-registry.model.register_card(modelcard)
-
-
-# load model
-loaded_modelcard: ModelCard = registry.model.load_card(uid=modelcard.uid)
-loaded_modelcard.load()
-
-assert loaded_modelcard.model is not None
+X, y = cast(Tuple[pd.DataFrame, pd.DataFrame], create_fake_data(n_samples=1000))
+model = catboost.CatBoostClassifier(iterations=5, verbose=False).fit(X.to_numpy(), y.to_numpy().ravel())
+
+with start_experiment(space="examples", name="catboost-quickstart"):
+    card = opsml.catboost.log_model(
+        model,
+        name="catboost-classifier",
+        sample_data=X[:10],
+        task_type=TaskType.Classification,
+    )
+    opsml.log_metric("accuracy", 0.9)
+    opsml.log_param("iterations", 5)
+
+print(f"Registered ModelCard v{card.version} uid={card.uid}")
+
+# --- equivalent explicit form (full control) ---
+# from opsml import CatBoostModel, ModelCard
+# with start_experiment(space="examples", name="catboost-quickstart") as exp:
+#     card = ModelCard(
+#         space="examples",
+#         name="catboost-classifier",
+#         interface=CatBoostModel(model=model, sample_data=X[:10], task_type=TaskType.Classification),
+#     )
+#     exp.register_card(card)
diff --git a/py-opsml/examples/model/custom_model.py b/py-opsml/examples/model/custom_model.py
index 67aac0c67b..c95998d2df 100644
--- a/py-opsml/examples/model/custom_model.py
+++ b/py-opsml/examples/model/custom_model.py
@@ -37,29 +37,16 @@ def predict(self, X):
 
 
 class CustomSklearnInterface(ModelInterface):
-    def __new__(
-        cls,
-        model: Optional[ConstantOffsetRegressor] = None,
-        binarizer: Optional[Binarizer] = None,
-        task_type: Optional[TaskType] = None,
-    ):
-        instance = super(CustomSklearnInterface, cls).__new__(
-            cls,
-            model=model,
-            task_type=task_type,
-        )
-
-        return instance
-
     def __init__(
         self,
         model: Optional[ConstantOffsetRegressor] = None,
         binarizer: Optional[Binarizer] = None,
         task_type: Optional[TaskType] = None,
+        **kwargs,
     ):
         """Init method for the custom model interface."""
 
-        super().__init__()
+        super().__init__(model=model, task_type=task_type, **kwargs)
 
         # adding new attribute to interface
         self.binarizer = binarizer
diff --git a/py-opsml/examples/model/hf_model.py b/py-opsml/examples/model/hf_model.py
index f62ebd3d46..ca9e697fba 100644
--- a/py-opsml/examples/model/hf_model.py
+++ b/py-opsml/examples/model/hf_model.py
@@ -1,37 +1,41 @@
-from opsml.card import CardRegistry, ModelCard, RegistryType
-from opsml.logging import LoggingConfig, LogLevel, RustyLogger
-from opsml.model import HuggingFaceModel, HuggingFaceTask, TaskType
-from transformers import (  # type: ignore
-    DistilBertForSequenceClassification,
-    DistilBertTokenizerFast,
+"""HuggingFace Transformers model registration with OpsML."""
+
+import opsml
+import opsml.huggingface
+from opsml import HuggingFaceTask, TaskType, start_experiment
+from transformers import BertConfig, BertForSequenceClassification  # type: ignore
+
+config = BertConfig(
+    vocab_size=32,
+    hidden_size=8,
+    num_hidden_layers=1,
+    num_attention_heads=1,
+    intermediate_size=16,
 )
-
-logger = RustyLogger.get_logger(
-    config=LoggingConfig(log_level=LogLevel.Info),
-)
-
-logger.info("Starting the model card example...")
-tokenizer = DistilBertTokenizerFast.from_pretrained("distilbert-base-uncased")
-model = DistilBertForSequenceClassification.from_pretrained("distilbert-base-uncased")
-
-# ... custom training code would go here...
-
-model_registry = CardRegistry(registry_type=RegistryType.Model)
-
-interface = HuggingFaceModel(
-    model=model,
-    tokenizer=tokenizer,
-    hf_task=HuggingFaceTask.TextClassification,
-    task_type=TaskType.Classification,
-)
-
-modelcard = ModelCard(interface=interface, space="opsml", name="my_model")
-
-logger.info("Registering the model card...")
-model_registry.register_card(modelcard)
-
-logger.info("Listing the model card...")
-cards = model_registry.list_cards(uid=modelcard.uid).as_table()
-
-logger.info("Loading the model card...")
-loaded_modelcard = model_registry.load_card(uid=modelcard.uid)
+model = BertForSequenceClassification(config)
+
+with start_experiment(space="examples", name="huggingface-quickstart"):
+    card = opsml.huggingface.log_model(
+        model,
+        name="bert-sequence-classifier",
+        hf_task=HuggingFaceTask.TextClassification,
+        task_type=TaskType.Classification,
+    )
+    opsml.log_metric("accuracy", 0.88)
+    opsml.log_param("hidden_size", 8)
+
+print(f"Registered ModelCard v{card.version} uid={card.uid}")
+
+# --- equivalent explicit form (full control) ---
+# from opsml import HuggingFaceModel, ModelCard
+# with start_experiment(space="examples", name="huggingface-quickstart") as exp:
+#     card = ModelCard(
+#         space="examples",
+#         name="bert-sequence-classifier",
+#         interface=HuggingFaceModel(
+#             model=model,
+#             hf_task=HuggingFaceTask.TextClassification,
+#             task_type=TaskType.Classification,
+#         ),
+#     )
+#     exp.register_card(card)
diff --git a/py-opsml/examples/model/lightgbm_booster.py b/py-opsml/examples/model/lightgbm_booster.py
index 7b88b4a583..51b0296054 100644
--- a/py-opsml/examples/model/lightgbm_booster.py
+++ b/py-opsml/examples/model/lightgbm_booster.py
@@ -1,74 +1,40 @@
+"""LightGBM model registration with OpsML."""
+
 from typing import Tuple, cast
 
-import lightgbm as lgb
+import lightgbm as lgb  # type: ignore
+import opsml
+import opsml.lightgbm
 import pandas as pd
-from opsml import CardRegistry, LightGBMModel, ModelCard, RegistryType, TaskType
+from opsml import TaskType, start_experiment
 from opsml.helpers.data import create_fake_data
-from opsml.logging import LoggingConfig, LogLevel, RustyLogger
 
-logger = RustyLogger.get_logger(
-    config=LoggingConfig(log_level=LogLevel.Info),
+X, y = cast(Tuple[pd.DataFrame, pd.DataFrame], create_fake_data(n_samples=1000))
+dataset = lgb.Dataset(X.to_numpy(), y.to_numpy().ravel())
+model = lgb.train(
+    {"objective": "binary", "verbosity": -1},
+    dataset,
+    num_boost_round=5,
 )
 
-logger.info("Starting the model card example...")
-model_registry = CardRegistry(registry_type=RegistryType.Model)
-
-
-# create data
-X_train, y_train = cast(Tuple[pd.DataFrame, pd.DataFrame], create_fake_data(n_samples=1200))
-
-
-# create dataset for lightgbm
-lgb_train = lgb.Dataset(X_train, y_train)
-lgb_eval = lgb.Dataset(X_train[0:10], y_train[0:10], reference=lgb_train)
-# specify your configurations as a dict
-
-params = {
-    "boosting_type": "gbdt",
-    "objective": "regression",
-    "metric": {"l2", "l1"},
-    "num_leaves": 31,
-    "learning_rate": 0.05,
-    "feature_fraction": 0.9,
-    "bagging_fraction": 0.8,
-    "bagging_freq": 5,
-    "verbose": 0,
-}
-# train
-gbm = lgb.train(
-    params,
-    lgb_train,
-    num_boost_round=20,
-    valid_sets=[lgb_eval],
-    callbacks=[
-        lgb.early_stopping(stopping_rounds=5),
-    ],
-)
-
-interface = LightGBMModel(
-    model=gbm,
-    sample_data=X_train[0:10],
-    task_type=TaskType.Regression,
-)
-
-# create ModelCard
-modelcard = ModelCard(
-    interface=interface,
-    space="opsml",
-    name="my_model",
-)
-
-logger.info("Registering the model card...")
-model_registry.register_card(modelcard)
-
-
-logger.info("Listing the model card...")
-model_registry.list_cards(uid=modelcard.uid).as_table()
-
-logger.info("Loading the model card...")
-loaded_modelcard: ModelCard = model_registry.load_card(uid=modelcard.uid)
-
-# load card artifacts
-loaded_modelcard.load()
-
-assert loaded_modelcard.model is not None
+with start_experiment(space="examples", name="lightgbm-quickstart"):
+    card = opsml.lightgbm.log_model(
+        model,
+        name="lgb-classifier",
+        sample_data=dataset,
+        task_type=TaskType.Classification,
+    )
+    opsml.log_metric("accuracy", 0.9)
+    opsml.log_param("n_estimators", 5)
+
+print(f"Registered ModelCard v{card.version} uid={card.uid}")
+
+# --- equivalent explicit form (full control) ---
+# from opsml import LightGBMModel, ModelCard
+# with start_experiment(space="examples", name="lightgbm-quickstart") as exp:
+#     card = ModelCard(
+#         space="examples",
+#         name="lgb-classifier",
+#         interface=LightGBMModel(model=model, sample_data=dataset, task_type=TaskType.Classification),
+#     )
+#     exp.register_card(card)
diff --git a/py-opsml/examples/model/lightning_model.py b/py-opsml/examples/model/lightning_model.py
index 73ce30c0d9..3af1ff67aa 100644
--- a/py-opsml/examples/model/lightning_model.py
+++ b/py-opsml/examples/model/lightning_model.py
@@ -1,38 +1,30 @@
+"""PyTorch Lightning model registration with OpsML."""
+
 from typing import Any
 
 import lightning as L  # type: ignore
 import numpy as np
-import torch
-from opsml import (
-    CardRegistry,
-    LightningModel,
-    ModelCard,
-    ModelLoadKwargs,
-    ModelSaveKwargs,
-    RegistryType,
-)
+import opsml
+import opsml.lightning
+import torch  # type: ignore
+from opsml import TaskType, start_experiment
 from torch import nn
 from torch.nn import MSELoss
 from torch.optim import Adam
 from torch.utils.data import DataLoader, Dataset
 
-registry = CardRegistry(RegistryType.Model)
-
 
 class SimpleDataset(Dataset):  # type: ignore
     def __init__(self) -> None:
-        X = np.arange(10000)
-        y = X * 2
-        X = [[_] for _ in X]  # type: ignore
-        y = [[_] for _ in y]  # type: ignore
-        self.X = torch.Tensor(X)
-        self.y = torch.Tensor(y)
+        x = np.arange(1000)
+        self.x = torch.Tensor([[value] for value in x])
+        self.y = torch.Tensor([[value * 2] for value in x])
 
     def __len__(self) -> int:
         return len(self.y)
 
     def __getitem__(self, idx: Any) -> Any:
-        return {"X": self.X[idx], "y": self.y[idx]}
+        return {"x": self.x[idx], "y": self.y[idx]}
 
 
 class MyModel(L.LightningModule):
@@ -41,63 +33,43 @@ def __init__(self) -> None:
         self.fc = nn.Linear(1, 1)
         self.criterion = MSELoss()
 
-    def forward(self, inputs_id, labels=None) -> Any:
-        outputs = self.fc(inputs_id)
-        return outputs
+    def forward(self, x, labels=None) -> Any:
+        return self.fc(x)
 
     def train_dataloader(self) -> Any:
-        dataset = SimpleDataset()
-        return DataLoader(dataset, batch_size=1000)
+        return DataLoader(SimpleDataset(), batch_size=100)
 
     def training_step(self, batch, batch_idx) -> Any:
-        input_ids = batch["X"]
-        labels = batch["y"]
-        outputs = self(input_ids, labels)
-        loss = 0
-        if labels is not None:
-            loss = self.criterion(outputs, labels)
-        return {"loss": loss}
+        outputs = self(batch["x"])
+        return {"loss": self.criterion(outputs, batch["y"])}
 
     def configure_optimizers(self) -> Any:
-        optimizer = Adam(self.parameters())
-        return optimizer
+        return Adam(self.parameters())
 
 
 model = MyModel()
-trainer = L.Trainer(max_epochs=1)
+trainer = L.Trainer(max_epochs=1, logger=False)
 trainer.fit(model)
-
-X = torch.Tensor([[1.0], [51.0], [89.0]])
-
-interface = LightningModel(trainer=trainer, sample_data=X)
-
-modelcard = ModelCard(
-    interface=interface,
-    space="opsml",
-    name="my_model",
-)
-
-# Register the model card
-registry.register_card(
-    modelcard,
-    save_kwargs=ModelSaveKwargs(save_onnx=True),  # convert to onnx
-)
-
-# List the model card
-modelcard_list = registry.list_cards(uid=modelcard.uid).as_table()
-
-
-# Load the model card
-loaded_modelcard: ModelCard = registry.load_card(modelcard.uid)
-
-# Load the model card artifacts
-loaded_modelcard.load(
-    None,
-    load_kwargs=ModelLoadKwargs(
-        model={"model": MyModel},
-        load_onnx=True,
-    ),
-)
-
-assert loaded_modelcard.model is not None
-assert loaded_modelcard.onnx_session is not None
+sample = torch.Tensor([[1.0], [51.0], [89.0]])
+
+with start_experiment(space="examples", name="lightning-quickstart"):
+    card = opsml.lightning.log_model(
+        trainer,
+        name="lightning-regressor",
+        sample_data=sample,
+        task_type=TaskType.Regression,
+    )
+    opsml.log_metric("loss", 0.11)
+    opsml.log_param("max_epochs", 1)
+
+print(f"Registered ModelCard v{card.version} uid={card.uid}")
+
+# --- equivalent explicit form (full control) ---
+# from opsml import LightningModel, ModelCard
+# with start_experiment(space="examples", name="lightning-quickstart") as exp:
+#     card = ModelCard(
+#         space="examples",
+#         name="lightning-regressor",
+#         interface=LightningModel(trainer=trainer, sample_data=sample, task_type=TaskType.Regression),
+#     )
+#     exp.register_card(card)
diff --git a/py-opsml/examples/model/onnx_model.py b/py-opsml/examples/model/onnx_model.py
index 6822ba38dc..dede72ffe0 100644
--- a/py-opsml/examples/model/onnx_model.py
+++ b/py-opsml/examples/model/onnx_model.py
@@ -1,64 +1,42 @@
+"""ONNX model registration with OpsML."""
+
 from typing import Tuple, cast
 
 import numpy as np
+import opsml
+import opsml.onnx
 import pandas as pd
-from opsml import CardRegistry, ModelCard, OnnxModel, RegistryType, TaskType
+from opsml import TaskType, start_experiment
 from opsml.helpers.data import create_fake_data
 from skl2onnx import to_onnx  # type: ignore
 from sklearn.ensemble import RandomForestClassifier  # type: ignore
 
-model_registry = CardRegistry(registry_type=RegistryType.Model)
-
-
-# create data
-X_train, y_train = cast(Tuple[pd.DataFrame, pd.DataFrame], create_fake_data(n_samples=1200))
-
-clr = RandomForestClassifier()
-clr.fit(X_train.to_numpy(), y_train.to_numpy().ravel())
-
-# Converting the model to ONNX
-converted_model = to_onnx(clr, X_train.to_numpy()[:1])
-
-
-interface = OnnxModel(
-    model=converted_model,
-    sample_data=X_train.to_numpy()[:1],
-    task_type=TaskType.Classification,
-)
-
-# create ModelCard
-modelcard = ModelCard(
-    interface=interface,
-    space="opsml",
-    name="my_model",
-)
-
-# register ModelCard
-model_registry.register_card(modelcard)
-
-
-# list card
-model_registry.list_cards(uid=modelcard.uid).as_table()
-
-
-## load card
-loaded_modelcard: ModelCard = model_registry.load_card(uid=modelcard.uid)
-
-## load card artifacts
-loaded_modelcard.load()
-
-assert loaded_modelcard.onnx_session is not None
-assert loaded_modelcard.onnx_session.session is not None
-
-
-# make predictions
-input_name = loaded_modelcard.onnx_session.session.get_inputs()[0].name
-label_name = loaded_modelcard.onnx_session.session.get_outputs()[0].name
-
-
-pred_onx = loaded_modelcard.onnx_session.run(
-    input_feed={input_name: X_train[0:10].to_numpy().astype(np.float64)},
-    output_names=[label_name],
-)[0]
-
-print("Predictions: ", pred_onx)
+X, y = cast(Tuple[pd.DataFrame, pd.DataFrame], create_fake_data(n_samples=1000))
+classifier = RandomForestClassifier(n_estimators=5).fit(X.to_numpy(), y.to_numpy().ravel())
+converted_model = to_onnx(classifier, X.to_numpy()[:1].astype(np.float32))
+
+with start_experiment(space="examples", name="onnx-quickstart"):
+    card = opsml.onnx.log_model(
+        converted_model,
+        name="onnx-rf",
+        sample_data=X.to_numpy()[:5].astype(np.float32),
+        task_type=TaskType.Classification,
+    )
+    opsml.log_metric("accuracy", 0.89)
+    opsml.log_param("n_estimators", 5)
+
+print(f"Registered ModelCard v{card.version} uid={card.uid}")
+
+# --- equivalent explicit form (full control) ---
+# from opsml import ModelCard, OnnxModel
+# with start_experiment(space="examples", name="onnx-quickstart") as exp:
+#     card = ModelCard(
+#         space="examples",
+#         name="onnx-rf",
+#         interface=OnnxModel(
+#             model=converted_model,
+#             sample_data=X.to_numpy()[:5].astype(np.float32),
+#             task_type=TaskType.Classification,
+#         ),
+#     )
+#     exp.register_card(card)
diff --git a/py-opsml/examples/model/sklearn_model.py b/py-opsml/examples/model/sklearn_model.py
index ebe918ced6..bf3e8f22ad 100644
--- a/py-opsml/examples/model/sklearn_model.py
+++ b/py-opsml/examples/model/sklearn_model.py
@@ -1,95 +1,47 @@
+"""
+Sklearn model registration with OpsML.
+
+Runs in CI via `mise run py:test:examples-model`.
+Mirrored in docs/cards/frameworks/sklearn.md via mkdocs snippets.
+"""
+
 from typing import Tuple, cast
 
+import opsml
+import opsml.sklearn
 import pandas as pd
-from opsml import (
-    CardRegistries,
-    DataCard,
-    ModelCard,
-    ModelLoadKwargs,
-    ModelSaveKwargs,
-    PandasData,
-    SklearnModel,
-    TaskType,
-)
-from opsml.data import DataSplit, StartStopSplit
+from opsml import TaskType, start_experiment
 from opsml.helpers.data import create_fake_data
 from sklearn import ensemble  # type: ignore
 
-# start registries
-reg = CardRegistries()
-
-# create data
-X, y = cast(Tuple[pd.DataFrame, pd.DataFrame], create_fake_data(n_samples=1200))
-X["target"] = y
-
-# create data splits to store with the model
-data_splits = [
-    DataSplit(
-        label="train",
-        start_stop_split=StartStopSplit(
-            start=0,
-            stop=1000,
-        ),
-    ),
-    DataSplit(
-        label="test",
-        start_stop_split=StartStopSplit(
-            start=1000,
-            stop=1200,
-        ),
-    ),
-]
-
-# create DataCard
-datacard = DataCard(
-    interface=PandasData(
-        data=X,
-        data_splits=data_splits,
-        dependent_vars=["target"],
-    ),
-    space="opsml",
-    name="my_data",
-    tags=["foo:bar", "baz:qux"],
-)
-
-# register DataCard
-reg.data.register_card(datacard)
-
-splits = datacard.interface.split_data()
-
-# Create and train model
-classifier = ensemble.RandomForestClassifier(n_estimators=5)
-classifier.fit(
-    splits["train"].x.to_numpy(),
-    splits["train"].y.to_numpy().ravel(),
+X, y = cast(Tuple[pd.DataFrame, pd.DataFrame], create_fake_data(n_samples=1000))
+classifier = ensemble.RandomForestClassifier(n_estimators=10, random_state=42).fit(
+    X.to_numpy(),
+    y.to_numpy().ravel(),
 )
 
-model_interface = SklearnModel(
-    model=classifier,
-    sample_data=X[0:10],
-    task_type=TaskType.Classification,
-)
-
-model_interface.create_drift_profile("drift", X)
-
-modelcard = ModelCard(
-    interface=model_interface,
-    space="opsml",
-    name="my_model",
-    tags=["foo:bar", "baz:qux"],
-    datacard_uid=datacard.uid,
-)
-
-# register model
-reg.model.register_card(
-    card=modelcard,
-    save_kwargs=ModelSaveKwargs(save_onnx=True),
-)
-
-
-# load model
-loaded_modelcard = reg.model.load_card(uid=modelcard.uid)
-loaded_modelcard.load(load_kwargs=ModelLoadKwargs(load_onnx=True))
-
-assert loaded_modelcard.model is not None
-assert loaded_modelcard.onnx_session is not None
+with start_experiment(space="examples", name="sklearn-quickstart"):
+    card = opsml.sklearn.log_model(
+        classifier,
+        name="rf-classifier",
+        sample_data=X[:10],
+        task_type=TaskType.Classification,
+    )
+    opsml.log_metric("accuracy", 0.91)
+    opsml.log_param("n_estimators", 10)
+
+print(f"Registered ModelCard v{card.version} uid={card.uid}")
+
+# --- equivalent explicit form (full control) ---
+# from opsml import ModelCard, SklearnModel
+# with start_experiment(space="examples", name="sklearn-quickstart") as exp:
+#     card = ModelCard(
+#         space="examples",
+#         name="rf-classifier",
+#         interface=SklearnModel(
+#             model=classifier,
+#             sample_data=X[:10],
+#             task_type=TaskType.Classification,
+#         ),
+#     )
+#     exp.register_card(card)
diff --git a/py-opsml/examples/model/tensorflow_model.py b/py-opsml/examples/model/tensorflow_model.py
index 16b4bd1b9c..8f26b6442b 100644
--- a/py-opsml/examples/model/tensorflow_model.py
+++ b/py-opsml/examples/model/tensorflow_model.py
@@ -1,93 +1,37 @@
+"""TensorFlow model registration with OpsML."""
+
 import numpy as np
-from opsml import (
-    CardRegistry,
-    ModelCard,
-    RegistryType,
-    TensorFlowModel,
+import opsml
+import opsml.tensorflow
+import tensorflow as tf  # type: ignore
+from opsml import TaskType, start_experiment
+
+model = tf.keras.Sequential(
+    [
+        tf.keras.layers.Input(shape=(4,)),
+        tf.keras.layers.Dense(1),
+    ]
 )
-from tensorflow.keras import Input, Model  # type: ignore
-from tensorflow.keras.layers import Concatenate, Dense  # type: ignore
-
-registry = CardRegistry(RegistryType.Model)
-
-
-def multi_input_model():
-    """Creates a multi-input model with numeric and categorical data."""
-    num_samples = 100
-    numeric_data = np.random.rand(num_samples, 10)
-    categorical_data = np.random.randint(0, 5, size=(num_samples, 5))
-    y = np.random.randint(0, 2, size=(num_samples, 1))
-
-    # Define inputs
-    numeric_input = Input(shape=(10,), name="numeric_input")
-    categorical_input = Input(shape=(5,), name="categorical_input")
-
-    # Process numeric branch
-    numeric_branch = Dense(4, activation="relu", name="numeric_dense1")(numeric_input)
-    numeric_branch = Dense(4, activation="relu", name="numeric_dense2")(numeric_branch)
-
-    # Process categorical branch
-    categorical_branch = Dense(4, activation="relu", name="categorical_dense1")(categorical_input)
-    categorical_branch = Dense(4, activation="relu", name="categorical_dense2")(categorical_branch)
-
-    # Combine branches
-    combined = Concatenate(name="concat")([numeric_branch, categorical_branch])
-
-    # Shared layers
-    x = Dense(4, activation="relu", name="shared_dense")(combined)
-    outputs = Dense(1, activation="sigmoid", name="output")(x)
-
-    # Create model
-    model = Model(
-        inputs=[numeric_input, categorical_input],
-        outputs=outputs,
-        name="multi_input_model",
-    )
-
-    model.compile(optimizer="adam", loss="binary_crossentropy", metrics=["accuracy"])
-
-    model.fit(
-        [numeric_data, categorical_data],
-        y,
-        epochs=1,
-        batch_size=32,
-        validation_split=0.2,
-        verbose=1,
+sample = np.random.rand(10, 4)
+
+with start_experiment(space="examples", name="tensorflow-quickstart"):
+    card = opsml.tensorflow.log_model(
+        model,
+        name="tf-dense",
+        sample_data=sample,
+        task_type=TaskType.Regression,
     )
-
-    # Theres an issue with tf2onnx and numpy casting - remove for now
-    # input_signature = [
-    #    tf.TensorSpec(shape=(None, 10), dtype=tf.float32, name="numeric_input"),
-    #    tf.TensorSpec(shape=(None, 5), dtype=tf.float32, name="categorical_input"),
-    # ]
-    # save_kwargs = ModelSaveKwargs(
-    #    onnx={"input_signature": input_signature},
-    #    save_onnx=True,
-    # )
-
-    return model, [numeric_data, categorical_data]
-
-
-model, data = multi_input_model()
-interface = TensorFlowModel(model=model, sample_data=data)
-
-modelcard = ModelCard(
-    interface=interface,
-    space="opsml",
-    name="my_model",
-)
-
-# Register the model card
-registry.register_card(modelcard)
-
-# List the model card
-modelcard_list = registry.list_cards(uid=modelcard.uid).as_table()
-
-
-# Load the model card
-loaded_modelcard: ModelCard = registry.load_card(modelcard.uid)
-
-# Load the model card artifacts
-loaded_modelcard.load()
-
-assert loaded_modelcard.model is not None
+    opsml.log_metric("loss", 0.14)
+    opsml.log_param("layers", 1)
+
+print(f"Registered ModelCard v{card.version} uid={card.uid}")
+
+# --- equivalent explicit form (full control) ---
+# from opsml import ModelCard, TensorFlowModel
+# with start_experiment(space="examples", name="tensorflow-quickstart") as exp:
+#     card = ModelCard(
+#         space="examples",
+#         name="tf-dense",
+#         interface=TensorFlowModel(model=model, sample_data=sample, task_type=TaskType.Regression),
+#     )
+#     exp.register_card(card)
diff --git a/py-opsml/examples/model/torch_model.py b/py-opsml/examples/model/torch_model.py
index 3136093133..e6918ec1fa 100644
--- a/py-opsml/examples/model/torch_model.py
+++ b/py-opsml/examples/model/torch_model.py
@@ -1,67 +1,31 @@
-import torch
-from opsml import (
-    CardRegistry,
-    ModelCard,
-    ModelLoadKwargs,
-    ModelSaveKwargs,
-    RegistryType,
-    TorchModel,
-)
-
-registry = CardRegistry(RegistryType.Model)
-
-
-class Polynomial3(torch.nn.Module):
-    def __init__(self):
-        """
-        In the constructor we instantiate four parameters and assign them as
-        member parameters.
-        """
-        super().__init__()
-        self.x1 = torch.nn.Parameter(torch.randn(()))
-        self.x2 = torch.nn.Parameter(torch.randn(()))
-
-    def forward(self, x1: torch.Tensor, x2: torch.Tensor):
-        """
-        In the forward function we accept a Tensor of input data and we must return
-        a Tensor of output data. We can use Modules defined in the constructor as
-        well as arbitrary operators on Tensors.
-        """
-        return self.x1 + self.x2 * x1 * x2
-
-
-model = Polynomial3()
-inputs = {"x1": torch.randn((1, 1)), "x2": torch.randn((1, 1))}
-
-interface = TorchModel(model=model, sample_data=inputs)
-
-modelcard = ModelCard(
-    interface=interface,
-    space="opsml",
-    name="my_model",
-)
-
-# Register the model card
-registry.register_card(
-    card=modelcard,
-    save_kwargs=ModelSaveKwargs(save_onnx=True),
-)
-
-# List the model card
-modelcard_list = registry.list_cards(uid=modelcard.uid).as_table()
-
-
-# Load the model card
-loaded_modelcard: ModelCard = registry.load_card(modelcard.uid)
-
-# Load the model card artifacts
-loaded_modelcard.load(
-    None,
-    load_kwargs=ModelLoadKwargs(
-        model={"model": model},
-        load_onnx=True,
-    ),
-)
-
-assert loaded_modelcard.model is not None
-assert loaded_modelcard.onnx_session is not None
+"""PyTorch model registration with OpsML."""
+
+import opsml
+import opsml.torch
+import torch  # type: ignore
+from opsml import TaskType, start_experiment
+
+model = torch.nn.Linear(4, 1)
+sample = torch.rand(10, 4)
+
+with start_experiment(space="examples", name="torch-quickstart"):
+    card = opsml.torch.log_model(
+        model,
+        name="torch-linear",
+        sample_data=sample,
+        task_type=TaskType.Regression,
+    )
+    opsml.log_metric("loss", 0.12)
+    opsml.log_param("in_features", 4)
+
+print(f"Registered ModelCard v{card.version} uid={card.uid}")
+
+# --- equivalent explicit form (full control) ---
+# from opsml import ModelCard, TorchModel
+# with start_experiment(space="examples", name="torch-quickstart") as exp:
+#     card = ModelCard(
+#         space="examples",
+#         name="torch-linear",
+#         interface=TorchModel(model=model, sample_data=sample, task_type=TaskType.Regression),
+#     )
+#     exp.register_card(card)
diff --git a/py-opsml/examples/model/xgb_booster.py b/py-opsml/examples/model/xgb_booster.py
index 128a37cb0b..16705d99b0 100644
--- a/py-opsml/examples/model/xgb_booster.py
+++ b/py-opsml/examples/model/xgb_booster.py
@@ -1,53 +1,36 @@
+"""XGBoost model registration with OpsML."""
+
 from typing import Tuple, cast
 
+import opsml
+import opsml.xgboost
 import pandas as pd
-import xgboost as xgb
-from opsml import CardRegistry, ModelCard, RegistryType, TaskType, XGBoostModel
+import xgboost as xgb  # type: ignore
+from opsml import TaskType, start_experiment
 from opsml.helpers.data import create_fake_data
 
-model_registry = CardRegistry(registry_type=RegistryType.Model)
-
-
-# create data
-X_train, y_train = cast(Tuple[pd.DataFrame, pd.DataFrame], create_fake_data(n_samples=1200))
-
-dtrain = xgb.DMatrix(X_train.to_numpy(), y_train.to_numpy())
-dtest = xgb.DMatrix(X_train[0:10].to_numpy(), y_train[0:10].to_numpy())
-
-param = {"max_depth": 2, "eta": 1, "objective": "reg:tweedie"}
-# specify validations set to watch performance
-watchlist = [(dtest, "eval"), (dtrain, "train")]
-
-# number of boosting rounds
-num_round = 2
-bst = xgb.train(param, dtrain, num_boost_round=num_round, evals=watchlist)
-
-
-interface = XGBoostModel(
-    model=bst,
-    sample_data=dtrain,
-    task_type=TaskType.Regression,
-)
-
-# create ModelCard
-modelcard = ModelCard(
-    interface=interface,
-    space="opsml",
-    name="my_model",
-)
-
-# register ModelCard
-model_registry.register_card(modelcard)
-
-
-# list card
-model_registry.list_cards(uid=modelcard.uid).as_table()
-
-
-# load card
-loaded_modelcard: ModelCard = model_registry.load_card(uid=modelcard.uid)
-
-# load card artifacts
-loaded_modelcard.load()
-
-assert loaded_modelcard.model is not None
+X, y = cast(Tuple[pd.DataFrame, pd.DataFrame], create_fake_data(n_samples=1000))
+dtrain = xgb.DMatrix(X.to_numpy(), y.to_numpy())
+model = xgb.train({"max_depth": 2, "eta": 1, "objective": "reg:squarederror"}, dtrain, num_boost_round=2)
+
+with start_experiment(space="examples", name="xgboost-quickstart"):
+    card = opsml.xgboost.log_model(
+        model,
+        name="xgb-regressor",
+        sample_data=dtrain,
+        task_type=TaskType.Regression,
+    )
+    opsml.log_metric("rmse", 0.31)
+    opsml.log_param("num_boost_round", 2)
+
+print(f"Registered ModelCard v{card.version} uid={card.uid}")
+
+# --- equivalent explicit form (full control) ---
+# from opsml import ModelCard, XGBoostModel
+# with start_experiment(space="examples", name="xgboost-quickstart") as exp:
+#     card = ModelCard(
+#         space="examples",
+#         name="xgb-regressor",
+#         interface=XGBoostModel(model=model, sample_data=dtrain, task_type=TaskType.Regression),
+#     )
+#     exp.register_card(card)
diff --git a/py-opsml/mkdocs.yml b/py-opsml/mkdocs.yml
index 501dcedc78..c1f7bb83b9 100644
--- a/py-opsml/mkdocs.yml
+++ b/py-opsml/mkdocs.yml
@@ -68,6 +68,17 @@ nav:
       - Experiment:
           - Card: "docs/cards/experiment/experimentcard.md"
           - Usage: "docs/cards/experiment/usage.md"
+          - Fluent API: "docs/cards/experiment/fluent.md"
+      - Frameworks:
+          - Scikit-learn: "docs/cards/frameworks/sklearn.md"
+          - XGBoost: "docs/cards/frameworks/xgboost.md"
+          - LightGBM: "docs/cards/frameworks/lightgbm.md"
+          - CatBoost: "docs/cards/frameworks/catboost.md"
+          - PyTorch: "docs/cards/frameworks/torch.md"
+          - PyTorch Lightning: "docs/cards/frameworks/lightning.md"
+          - TensorFlow: "docs/cards/frameworks/tensorflow.md"
+          - HuggingFace: "docs/cards/frameworks/huggingface.md"
+          - ONNX: "docs/cards/frameworks/onnx.md"
       - "docs/cards/promptcard.md"
       - "docs/cards/servicecard.md"
       - "docs/cards/agentcard.md"
diff --git a/py-opsml/python/opsml/__init__.py b/py-opsml/python/opsml/__init__.py
index b132ddc122..4e0512ef59 100644
--- a/py-opsml/python/opsml/__init__.py
+++ b/py-opsml/python/opsml/__init__.py
@@ -46,7 +46,18 @@
     XGBoostModel,
     _get_log_level,  # type: ignore
     _log_json,  # type: ignore
+    active_experiment,
     get_opsml_version,  # type: ignore
+    log_artifact,
+    log_artifacts,
+    log_figure,
+    log_figure_from_path,
+    log_metric,
+    log_metrics,
+    log_param,
+    log_params,
+    set_tag,
+    set_tags,
     start_experiment,
 )
 
@@ -99,6 +110,17 @@
     "ArrowData",
     # Experiment
     "start_experiment",
+    "log_metric",
+    "log_metrics",
+    "log_param",
+    "log_params",
+    "log_artifact",
+    "log_artifacts",
+    "log_figure",
+    "log_figure_from_path",
+    "set_tag",
+    "set_tags",
+    "active_experiment",
     "Experiment",
     ## model
     "ModelInterface",
diff --git a/py-opsml/python/opsml/_opsml.pyi b/py-opsml/python/opsml/_opsml.pyi
index 9404e62184..f0f578a626 100644
--- a/py-opsml/python/opsml/_opsml.pyi
+++ b/py-opsml/python/opsml/_opsml.pyi
@@ -20974,6 +20974,8 @@ class ExperimentCard:
                 The experiment card uid to add
         """
 
+    def add_tag(self, tag: str) -> None: ...
+    def set_tags(self, val: List[str]) -> None: ...
     def list_artifacts(self, path: Optional[Path | str] = None) -> List[str]:
         """List the artifacts associated with the experiment card
 
@@ -22564,6 +22566,17 @@ class Experiment:
                 Value of the parameter
         """
 
+    def log_param(
+        self,
+        name: str,
+        value: Union[int, float, str],
+    ) -> None:
+        """
+        Log a parameter.
+
+        Alias for log_parameter.
+        """
+
     def log_parameters(self, parameters: list[Parameter] | Dict[str, Union[int, float, str]]) -> None:
         """
         Log multiple parameters
@@ -22573,6 +22586,13 @@ class Experiment:
                 Parameters to log
         """
 
+    def log_params(self, parameters: list[Parameter] | Dict[str, Union[int, float, str]]) -> None:
+        """
+        Log multiple parameters.
+
+        Alias for log_parameters.
+        """
+
     def log_artifact(
         self,
         lpath: Path,
@@ -22635,6 +22655,16 @@ class Experiment:
                 All files in the directory will be logged.
         """
 
+    def set_tag(self, tag: str) -> None:
+        """
+        Append one tag to the experiment.
+        """
+
+    def set_tags(self, tags: list[str]) -> None:
+        """
+        Replace the experiment tags.
+        """
+
     @property
     def card(self) -> "ExperimentCard":
         """
@@ -22692,6 +22722,24 @@ def start_experiment(
         Experiment
     """
 
+def log_metric(
+    name: str,
+    value: float,
+    step: Optional[int] = None,
+    timestamp: Optional[int] = None,
+    created_at: Optional[datetime.datetime] = None,
+) -> None: ...
+def log_metrics(metrics: list[ExperimentMetric]) -> None: ...
+def log_param(name: str, value: Any) -> None: ...
+def log_params(params: dict[str, Any] | list[Parameter]) -> None: ...
+def log_artifact(lpath: str, rpath: str | None = None) -> None: ...
+def log_artifacts(path: str) -> None: ...
+def log_figure(name: str, figure: Any, kwargs: dict[str, Any] | None = None) -> None: ...
+def log_figure_from_path(lpath: str, rpath: str | None = None) -> None: ...
+def set_tag(tag: str) -> None: ...
+def set_tags(tags: list[str]) -> None: ...
+def active_experiment() -> Experiment: ...
+
 class ExperimentEvalMetrics:
     """
     Map of metrics used that can be used to evaluate a model.
@@ -24682,12 +24730,15 @@ class ModelInterfaceMetadata:
         """Validate the model interface metadata json"""
 
 class ModelInterface:
+    def __new__(cls, *args: Any, **kwargs: Any) -> "ModelInterface": ...
     def __init__(
         self,
         model: Any = None,
         sample_data: Any = None,
         task_type: Optional[TaskType] = None,
         drift_profile: Optional[DriftProfileType] = None,
+        version: Optional[str] = None,
+        **kwargs: Any,
     ) -> None:
         """Base class for ModelInterface
 
@@ -24701,6 +24752,13 @@ class ModelInterface:
             drift_profile:
                 Drift profile(s) to associate with the model. Must be a dictionary of
                 alias and drift profile.
+            version:
+                Package version of the model being used.
+
+        Note:
+            ``**kwargs`` is present for PyO3 subclass initialization
+            compatibility. Direct ``ModelInterface(...)`` construction rejects
+            unknown keyword arguments.
         """
 
     @property
@@ -25429,6 +25487,108 @@ class OnnxModel(ModelInterface):
     def session(self) -> OnnxSession:
         """Returns the onnx session. This will error if the OnnxSession is not set"""
 
+def sklearn_log_model(
+    model: Any,
+    *,
+    name: str,
+    space: Optional[str] = None,
+    sample_data: Any = None,
+    preprocessor: Any = None,
+    task_type: Optional[TaskType] = None,
+    drift_profile: Any = None,
+    save_kwargs: Optional[ModelSaveKwargs] = None,
+) -> ModelCard: ...
+def xgboost_log_model(
+    model: Any,
+    *,
+    name: str,
+    space: Optional[str] = None,
+    sample_data: Any = None,
+    preprocessor: Any = None,
+    task_type: Optional[TaskType] = None,
+    drift_profile: Any = None,
+    save_kwargs: Optional[ModelSaveKwargs] = None,
+) -> ModelCard: ...
+def lightgbm_log_model(
+    model: Any,
+    *,
+    name: str,
+    space: Optional[str] = None,
+    sample_data: Any = None,
+    preprocessor: Any = None,
+    task_type: Optional[TaskType] = None,
+    drift_profile: Any = None,
+    save_kwargs: Optional[ModelSaveKwargs] = None,
+) -> ModelCard: ...
+def catboost_log_model(
+    model: Any,
+    *,
+    name: str,
+    space: Optional[str] = None,
+    sample_data: Any = None,
+    preprocessor: Any = None,
+    task_type: Optional[TaskType] = None,
+    drift_profile: Any = None,
+    save_kwargs: Optional[ModelSaveKwargs] = None,
+) -> ModelCard: ...
+def torch_log_model(
+    model: Any,
+    *,
+    name: str,
+    space: Optional[str] = None,
+    sample_data: Any = None,
+    preprocessor: Any = None,
+    task_type: Optional[TaskType] = None,
+    drift_profile: Any = None,
+    save_kwargs: Optional[ModelSaveKwargs] = None,
+) -> ModelCard: ...
+def lightning_log_model(
+    trainer: Any,
+    *,
+    name: str,
+    space: Optional[str] = None,
+    sample_data: Any = None,
+    preprocessor: Any = None,
+    task_type: Optional[TaskType] = None,
+    drift_profile: Any = None,
+    save_kwargs: Optional[ModelSaveKwargs] = None,
+) -> ModelCard: ...
+def tensorflow_log_model(
+    model: Any,
+    *,
+    name: str,
+    space: Optional[str] = None,
+    sample_data: Any = None,
+    preprocessor: Any = None,
+    task_type: Optional[TaskType] = None,
+    drift_profile: Any = None,
+    save_kwargs: Optional[ModelSaveKwargs] = None,
+) -> ModelCard: ...
+def huggingface_log_model(
+    model: Any,
+    *,
+    name: str,
+    space: Optional[str] = None,
+    sample_data: Any = None,
+    tokenizer: Any = None,
+    feature_extractor: Any = None,
+    image_processor: Any = None,
+    hf_task: Optional[HuggingFaceTask] = None,
+    task_type: Optional[TaskType] = None,
+    drift_profile: Any = None,
+    save_kwargs: Optional[ModelSaveKwargs] = None,
+) -> ModelCard: ...
+def onnx_log_model(
+    model: Any,
+    *,
+    name: str,
+    space: Optional[str] = None,
+    sample_data: Any = None,
+    task_type: Optional[TaskType] = None,
+    drift_profile: Any = None,
+    save_kwargs: Optional[ModelSaveKwargs] = None,
+) -> ModelCard: ...
+
 ########################################################################################
 #  This section contains the type definitions for opsml.app module
 # __opsml.app__
@@ -26583,6 +26743,8 @@ __all__ = [
     "WriteConfig",
     "WriteLevel",
     "XGBoostModel",
+    "active_experiment",
+    "catboost_log_model",
     "configure_tracing",
     "download_artifact",
     "download_service",
@@ -26594,9 +26756,27 @@ __all__ = [
     "get_experiment_metrics",
     "get_experiment_parameters",
     "get_tracer",
+    "huggingface_log_model",
     "infer_schema",
+    "lightgbm_log_model",
+    "lightning_log_model",
+    "log_artifact",
+    "log_artifacts",
+    "log_figure",
+    "log_figure_from_path",
+    "log_metric",
+    "log_metrics",
+    "log_param",
+    "log_params",
     "normalize_endpoint",
+    "onnx_log_model",
     "reset_tracer_provider",
+    "set_tag",
+    "set_tags",
     "shutdown_tracer",
+    "sklearn_log_model",
     "start_experiment",
+    "tensorflow_log_model",
+    "torch_log_model",
+    "xgboost_log_model",
 ]
diff --git a/py-opsml/python/opsml/catboost/__init__.py b/py-opsml/python/opsml/catboost/__init__.py
new file mode 100644
index 0000000000..f7279daae7
--- /dev/null
+++ b/py-opsml/python/opsml/catboost/__init__.py
@@ -0,0 +1,3 @@
+from opsml._opsml import catboost_log_model as log_model
+
+__all__ = ["log_model"]
diff --git a/py-opsml/python/opsml/catboost/__init__.pyi b/py-opsml/python/opsml/catboost/__init__.pyi
new file mode 100644
index 0000000000..f6d2ac6300
--- /dev/null
+++ b/py-opsml/python/opsml/catboost/__init__.pyi
@@ -0,0 +1,20 @@
+from typing import TYPE_CHECKING, Any
+
+from opsml._opsml import ModelCard, ModelSaveKwargs, TaskType
+
+if TYPE_CHECKING:
+    from catboost import CatBoost  # type: ignore[import-not-found]
+
+def log_model(
+    model: "CatBoost",
+    *,
+    name: str,
+    space: str | None = None,
+    sample_data: Any | None = None,
+    preprocessor: Any | None = None,
+    task_type: TaskType | None = None,
+    drift_profile: Any | None = None,
+    save_kwargs: ModelSaveKwargs | None = None,
+) -> ModelCard: ...
+
+__all__ = ["log_model"]
diff --git a/py-opsml/python/opsml/huggingface/__init__.py b/py-opsml/python/opsml/huggingface/__init__.py
new file mode 100644
index 0000000000..7be33d3e74
--- /dev/null
+++ b/py-opsml/python/opsml/huggingface/__init__.py
@@ -0,0 +1,3 @@
+from opsml._opsml import huggingface_log_model as log_model
+
+__all__ = ["log_model"]
diff --git a/py-opsml/python/opsml/huggingface/__init__.pyi b/py-opsml/python/opsml/huggingface/__init__.pyi
new file mode 100644
index 0000000000..090a725814
--- /dev/null
+++ b/py-opsml/python/opsml/huggingface/__init__.pyi
@@ -0,0 +1,23 @@
+from typing import TYPE_CHECKING, Any
+
+from opsml._opsml import HuggingFaceTask, ModelCard, ModelSaveKwargs, TaskType
+
+if TYPE_CHECKING:
+    from transformers import PreTrainedModel  # type: ignore[import-not-found]
+
+def log_model(
+    model: "PreTrainedModel",
+    *,
+    name: str,
+    space: str | None = None,
+    sample_data: Any | None = None,
+    tokenizer: Any | None = None,
+    feature_extractor: Any | None = None,
+    image_processor: Any | None = None,
+    hf_task: HuggingFaceTask | None = None,
+    task_type: TaskType | None = None,
+    drift_profile: Any | None = None,
+    save_kwargs: ModelSaveKwargs | None = None,
+) -> ModelCard: ...
+
+__all__ = ["log_model"]
diff --git a/py-opsml/python/opsml/lightgbm/__init__.py b/py-opsml/python/opsml/lightgbm/__init__.py
new file mode 100644
index 0000000000..a1bc5dd9d4
--- /dev/null
+++ b/py-opsml/python/opsml/lightgbm/__init__.py
@@ -0,0 +1,3 @@
+from opsml._opsml import lightgbm_log_model as log_model
+
+__all__ = ["log_model"]
diff --git a/py-opsml/python/opsml/lightgbm/__init__.pyi b/py-opsml/python/opsml/lightgbm/__init__.pyi
new file mode 100644
index 0000000000..c4c583dd25
--- /dev/null
+++ b/py-opsml/python/opsml/lightgbm/__init__.pyi
@@ -0,0 +1,20 @@
+from typing import TYPE_CHECKING, Any
+
+from opsml._opsml import ModelCard, ModelSaveKwargs, TaskType
+
+if TYPE_CHECKING:
+    import lightgbm as lgb  # type: ignore[import-not-found]
+
+def log_model(
+    model: "lgb.Booster",
+    *,
+    name: str,
+    space: str | None = None,
+    sample_data: Any | None = None,
+    preprocessor: Any | None = None,
+    task_type: TaskType | None = None,
+    drift_profile: Any | None = None,
+    save_kwargs: ModelSaveKwargs | None = None,
+) -> ModelCard: ...
+
+__all__ = ["log_model"]
diff --git a/py-opsml/python/opsml/lightning/__init__.py b/py-opsml/python/opsml/lightning/__init__.py
new file mode 100644
index 0000000000..eca4821cf2
--- /dev/null
+++ b/py-opsml/python/opsml/lightning/__init__.py
@@ -0,0 +1,3 @@
+from opsml._opsml import lightning_log_model as log_model
+
+__all__ = ["log_model"]
diff --git a/py-opsml/python/opsml/lightning/__init__.pyi b/py-opsml/python/opsml/lightning/__init__.pyi
new file mode 100644
index 0000000000..8a619f05f0
--- /dev/null
+++ b/py-opsml/python/opsml/lightning/__init__.pyi
@@ -0,0 +1,20 @@
+from typing import TYPE_CHECKING, Any
+
+from opsml._opsml import ModelCard, ModelSaveKwargs, TaskType
+
+if TYPE_CHECKING:
+    from pytorch_lightning import Trainer  # type: ignore[import-not-found]
+
+def log_model(
+    trainer: "Trainer",
+    *,
+    name: str,
+    space: str | None = None,
+    sample_data: Any | None = None,
+    preprocessor: Any | None = None,
+    task_type: TaskType | None = None,
+    drift_profile: Any | None = None,
+    save_kwargs: ModelSaveKwargs | None = None,
+) -> ModelCard: ...
+
+__all__ = ["log_model"]
diff --git a/py-opsml/python/opsml/onnx/__init__.py b/py-opsml/python/opsml/onnx/__init__.py
new file mode 100644
index 0000000000..b0e8ec4111
--- /dev/null
+++ b/py-opsml/python/opsml/onnx/__init__.py
@@ -0,0 +1,3 @@
+from opsml._opsml import onnx_log_model as log_model
+
+__all__ = ["log_model"]
diff --git a/py-opsml/python/opsml/onnx/__init__.pyi b/py-opsml/python/opsml/onnx/__init__.pyi
new file mode 100644
index 0000000000..0c846ef03a
--- /dev/null
+++ b/py-opsml/python/opsml/onnx/__init__.pyi
@@ -0,0 +1,19 @@
+from typing import TYPE_CHECKING, Any
+
+from opsml._opsml import ModelCard, ModelSaveKwargs, TaskType
+
+if TYPE_CHECKING:
+    import onnx  # type: ignore[import-not-found]
+
+def log_model(
+    model: "onnx.ModelProto",
+    *,
+    name: str,
+    space: str | None = None,
+    sample_data: Any | None = None,
+    task_type: TaskType | None = None,
+    drift_profile: Any | None = None,
+    save_kwargs: ModelSaveKwargs | None = None,
+) -> ModelCard: ...
+
+__all__ = ["log_model"]
diff --git a/py-opsml/python/opsml/sklearn/__init__.py b/py-opsml/python/opsml/sklearn/__init__.py
new file mode 100644
index 0000000000..29da2a89cf
--- /dev/null
+++ b/py-opsml/python/opsml/sklearn/__init__.py
@@ -0,0 +1,3 @@
+from opsml._opsml import sklearn_log_model as log_model
+
+__all__ = ["log_model"]
diff --git a/py-opsml/python/opsml/sklearn/__init__.pyi b/py-opsml/python/opsml/sklearn/__init__.pyi
new file mode 100644
index 0000000000..1abce13f89
--- /dev/null
+++ b/py-opsml/python/opsml/sklearn/__init__.pyi
@@ -0,0 +1,21 @@
+from typing import TYPE_CHECKING, Any
+
+from opsml._opsml import ModelCard, ModelSaveKwargs, TaskType
+
+if TYPE_CHECKING:
+    from sklearn.base import BaseEstimator  # type: ignore[import-not-found]
+    from sklearn.pipeline import Pipeline  # type: ignore[import-not-found]
+
+def log_model(
+    model: "BaseEstimator | Pipeline",
+    *,
+    name: str,
+    space: str | None = None,
+    sample_data: Any | None = None,
+    preprocessor: Any | None = None,
+    task_type: TaskType | None = None,
+    drift_profile: Any | None = None,
+    save_kwargs: ModelSaveKwargs | None = None,
+) -> ModelCard: ...
+
+__all__ = ["log_model"]
diff --git a/py-opsml/python/opsml/stubs/card.pyi b/py-opsml/python/opsml/stubs/card.pyi
index 97ac0267c2..9a9e93cc76 100644
--- a/py-opsml/python/opsml/stubs/card.pyi
+++ b/py-opsml/python/opsml/stubs/card.pyi
@@ -904,6 +904,9 @@ class ExperimentCard:
                 The experiment card uid to add
         """
 
+    def add_tag(self, tag: str) -> None: ...
+    def set_tags(self, val: List[str]) -> None: ...
+
     def list_artifacts(self, path: Optional[Path | str] = None) -> List[str]:
         """List the artifacts associated with the experiment card
 
@@ -2494,6 +2497,17 @@ class Experiment:
                 Value of the parameter
         """
 
+    def log_param(
+        self,
+        name: str,
+        value: Union[int, float, str],
+    ) -> None:
+        """
+        Log a parameter.
+
+        Alias for log_parameter.
+        """
+
     def log_parameters(self, parameters: list[Parameter] | Dict[str, Union[int, float, str]]) -> None:
         """
         Log multiple parameters
@@ -2503,6 +2517,13 @@ class Experiment:
                 Parameters to log
         """
 
+    def log_params(self, parameters: list[Parameter] | Dict[str, Union[int, float, str]]) -> None:
+        """
+        Log multiple parameters.
+
+        Alias for log_parameters.
+        """
+
     def log_artifact(
         self,
         lpath: Path,
@@ -2565,6 +2586,16 @@ class Experiment:
                 All files in the directory will be logged.
         """
 
+    def set_tag(self, tag: str) -> None:
+        """
+        Append one tag to the experiment.
+        """
+
+    def set_tags(self, tags: list[str]) -> None:
+        """
+        Replace the experiment tags.
+        """
+
     @property
     def card(self) -> "ExperimentCard":
         """
@@ -2622,6 +2653,24 @@ def start_experiment(
         Experiment
     """
 
+def log_metric(
+    name: str,
+    value: float,
+    step: Optional[int] = None,
+    timestamp: Optional[int] = None,
+    created_at: Optional[datetime.datetime] = None,
+) -> None: ...
+def log_metrics(metrics: list[ExperimentMetric]) -> None: ...
+def log_param(name: str, value: Any) -> None: ...
+def log_params(params: dict[str, Any] | list[Parameter]) -> None: ...
+def log_artifact(lpath: str, rpath: str | None = None) -> None: ...
+def log_artifacts(path: str) -> None: ...
+def log_figure(name: str, figure: Any, kwargs: dict[str, Any] | None = None) -> None: ...
+def log_figure_from_path(lpath: str, rpath: str | None = None) -> None: ...
+def set_tag(tag: str) -> None: ...
+def set_tags(tags: list[str]) -> None: ...
+def active_experiment() -> Experiment: ...
+
 class ExperimentEvalMetrics:
     """
     Map of metrics used that can be used to evaluate a model.
@@ -2722,6 +2771,17 @@ __all__ = [
     "Parameters",
     "Experiment",
     "start_experiment",
+    "log_metric",
+    "log_metrics",
+    "log_param",
+    "log_params",
+    "log_artifact",
+    "log_artifacts",
+    "log_figure",
+    "log_figure_from_path",
+    "set_tag",
+    "set_tags",
+    "active_experiment",
     "ExperimentEvalMetrics",
     "get_experiment_metrics",
     "get_experiment_parameters",
diff --git a/py-opsml/python/opsml/stubs/opsml.pyi b/py-opsml/python/opsml/stubs/opsml.pyi
index 0c8a6745a1..b59bac82e0 100644
--- a/py-opsml/python/opsml/stubs/opsml.pyi
+++ b/py-opsml/python/opsml/stubs/opsml.pyi
@@ -1957,12 +1957,16 @@ class ModelInterfaceMetadata:
         """Validate the model interface metadata json"""
 
 class ModelInterface:
+    def __new__(cls, *args: Any, **kwargs: Any) -> "ModelInterface": ...
+
     def __init__(
         self,
         model: Any = None,
         sample_data: Any = None,
         task_type: Optional[TaskType] = None,
         drift_profile: Optional[DriftProfileType] = None,
+        version: Optional[str] = None,
+        **kwargs: Any,
     ) -> None:
         """Base class for ModelInterface
 
@@ -1976,6 +1980,8 @@ class ModelInterface:
             drift_profile:
                 Drift profile(s) to associate with the model. Must be a dictionary of
                 alias and drift profile.
+            version:
+                Package version of the model being used.
         """
 
     @property
@@ -2704,6 +2710,108 @@ class OnnxModel(ModelInterface):
     def session(self) -> OnnxSession:
         """Returns the onnx session. This will error if the OnnxSession is not set"""
 
+def sklearn_log_model(
+    model: Any,
+    *,
+    name: str,
+    space: Optional[str] = None,
+    sample_data: Any = None,
+    preprocessor: Any = None,
+    task_type: Optional[TaskType] = None,
+    drift_profile: Any = None,
+    save_kwargs: Optional[ModelSaveKwargs] = None,
+) -> ModelCard: ...
+def xgboost_log_model(
+    model: Any,
+    *,
+    name: str,
+    space: Optional[str] = None,
+    sample_data: Any = None,
+    preprocessor: Any = None,
+    task_type: Optional[TaskType] = None,
+    drift_profile: Any = None,
+    save_kwargs: Optional[ModelSaveKwargs] = None,
+) -> ModelCard: ...
+def lightgbm_log_model(
+    model: Any,
+    *,
+    name: str,
+    space: Optional[str] = None,
+    sample_data: Any = None,
+    preprocessor: Any = None,
+    task_type: Optional[TaskType] = None,
+    drift_profile: Any = None,
+    save_kwargs: Optional[ModelSaveKwargs] = None,
+) -> ModelCard: ...
+def catboost_log_model(
+    model: Any,
+    *,
+    name: str,
+    space: Optional[str] = None,
+    sample_data: Any = None,
+    preprocessor: Any = None,
+    task_type: Optional[TaskType] = None,
+    drift_profile: Any = None,
+    save_kwargs: Optional[ModelSaveKwargs] = None,
+) -> ModelCard: ...
+def torch_log_model(
+    model: Any,
+    *,
+    name: str,
+    space: Optional[str] = None,
+    sample_data: Any = None,
+    preprocessor: Any = None,
+    task_type: Optional[TaskType] = None,
+    drift_profile: Any = None,
+    save_kwargs: Optional[ModelSaveKwargs] = None,
+) -> ModelCard: ...
+def lightning_log_model(
+    trainer: Any,
+    *,
+    name: str,
+    space: Optional[str] = None,
+    sample_data: Any = None,
+    preprocessor: Any = None,
+    task_type: Optional[TaskType] = None,
+    drift_profile: Any = None,
+    save_kwargs: Optional[ModelSaveKwargs] = None,
+) -> ModelCard: ...
+def tensorflow_log_model(
+    model: Any,
+    *,
+    name: str,
+    space: Optional[str] = None,
+    sample_data: Any = None,
+    preprocessor: Any = None,
+    task_type: Optional[TaskType] = None,
+    drift_profile: Any = None,
+    save_kwargs: Optional[ModelSaveKwargs] = None,
+) -> ModelCard: ...
+def huggingface_log_model(
+    model: Any,
+    *,
+    name: str,
+    space: Optional[str] = None,
+    sample_data: Any = None,
+    tokenizer: Any = None,
+    feature_extractor: Any = None,
+    image_processor: Any = None,
+    hf_task: Optional[HuggingFaceTask] = None,
+    task_type: Optional[TaskType] = None,
+    drift_profile: Any = None,
+    save_kwargs: Optional[ModelSaveKwargs] = None,
+) -> ModelCard: ...
+def onnx_log_model(
+    model: Any,
+    *,
+    name: str,
+    space: Optional[str] = None,
+    sample_data: Any = None,
+    task_type: Optional[TaskType] = None,
+    drift_profile: Any = None,
+    save_kwargs: Optional[ModelSaveKwargs] = None,
+) -> ModelCard: ...
+
 ########################################################################################
 #  This section contains the type definitions for opsml.app module
 # __opsml.app__
@@ -3385,6 +3493,15 @@ __all__ = [
     "CatBoostModel",
     "OnnxSession",
     "TensorFlowModel",
+    "sklearn_log_model",
+    "xgboost_log_model",
+    "lightgbm_log_model",
+    "catboost_log_model",
+    "torch_log_model",
+    "lightning_log_model",
+    "tensorflow_log_model",
+    "huggingface_log_model",
+    "onnx_log_model",
     "PromptSaveKwargs",
     "ModelLoadKwargs",
     "ModelSaveKwargs",
diff --git a/py-opsml/python/opsml/tensorflow/__init__.py b/py-opsml/python/opsml/tensorflow/__init__.py
new file mode 100644
index 0000000000..a1dca6c36d
--- /dev/null
+++ b/py-opsml/python/opsml/tensorflow/__init__.py
@@ -0,0 +1,3 @@
+from opsml._opsml import tensorflow_log_model as log_model
+
+__all__ = ["log_model"]
diff --git a/py-opsml/python/opsml/tensorflow/__init__.pyi b/py-opsml/python/opsml/tensorflow/__init__.pyi
new file mode 100644
index 0000000000..88be9ec631
--- /dev/null
+++ b/py-opsml/python/opsml/tensorflow/__init__.pyi
@@ -0,0 +1,20 @@
+from typing import TYPE_CHECKING, Any
+
+from opsml._opsml import ModelCard, ModelSaveKwargs, TaskType
+
+if TYPE_CHECKING:
+    from keras import Model as KerasModel  # type: ignore[import-not-found]
+
+def log_model(
+    model: "KerasModel",
+    *,
+    name: str,
+    space: str | None = None,
+    sample_data: Any | None = None,
+    preprocessor: Any | None = None,
+    task_type: TaskType | None = None,
+    drift_profile: Any | None = None,
+    save_kwargs: ModelSaveKwargs | None = None,
+) -> ModelCard: ...
+
+__all__ = ["log_model"]
diff --git a/py-opsml/python/opsml/torch/__init__.py b/py-opsml/python/opsml/torch/__init__.py
new file mode 100644
index 0000000000..73bf381d6d
--- /dev/null
+++ b/py-opsml/python/opsml/torch/__init__.py
@@ -0,0 +1,3 @@
+from opsml._opsml import torch_log_model as log_model
+
+__all__ = ["log_model"]
diff --git a/py-opsml/python/opsml/torch/__init__.pyi b/py-opsml/python/opsml/torch/__init__.pyi
new file mode 100644
index 0000000000..24177dadcb
--- /dev/null
+++ b/py-opsml/python/opsml/torch/__init__.pyi
@@ -0,0 +1,20 @@
+from typing import TYPE_CHECKING, Any
+
+from opsml._opsml import ModelCard, ModelSaveKwargs, TaskType
+
+if TYPE_CHECKING:
+    import torch.nn  # type: ignore[import-not-found]
+
+def log_model(
+    model: "torch.nn.Module",
+    *,
+    name: str,
+    space: str | None = None,
+    sample_data: Any | None = None,
+    preprocessor: Any | None = None,
+    task_type: TaskType | None = None,
+    drift_profile: Any | None = None,
+    save_kwargs: ModelSaveKwargs | None = None,
+) -> ModelCard: ...
+
+__all__ = ["log_model"]
diff --git a/py-opsml/python/opsml/xgboost/__init__.py b/py-opsml/python/opsml/xgboost/__init__.py
new file mode 100644
index 0000000000..9336f26244
--- /dev/null
+++ b/py-opsml/python/opsml/xgboost/__init__.py
@@ -0,0 +1,3 @@
+from opsml._opsml import xgboost_log_model as log_model
+
+__all__ = ["log_model"]
diff --git a/py-opsml/python/opsml/xgboost/__init__.pyi b/py-opsml/python/opsml/xgboost/__init__.pyi
new file mode 100644
index 0000000000..52ed5c5be2
--- /dev/null
+++ b/py-opsml/python/opsml/xgboost/__init__.pyi
@@ -0,0 +1,20 @@
+from typing import TYPE_CHECKING, Any
+
+from opsml._opsml import ModelCard, ModelSaveKwargs, TaskType
+
+if TYPE_CHECKING:
+    import xgboost as xgb  # type: ignore[import-not-found]
+
+def log_model(
+    model: "xgb.Booster",
+    *,
+    name: str,
+    space: str | None = None,
+    sample_data: Any | None = None,
+    preprocessor: Any | None = None,
+    task_type: TaskType | None = None,
+    drift_profile: Any | None = None,
+    save_kwargs: ModelSaveKwargs | None = None,
+) -> ModelCard: ...
+
+__all__ = ["log_model"]
diff --git a/py-opsml/src/experiment.rs b/py-opsml/src/experiment.rs
index d4f660c0a8..64fd223c0b 100644
--- a/py-opsml/src/experiment.rs
+++ b/py-opsml/src/experiment.rs
@@ -1,5 +1,5 @@
 use opsml_experiment::{
-    download_artifact, get_experiment_metrics, get_experiment_parameters, start_experiment,
+    download_artifact, fluent, get_experiment_metrics, get_experiment_parameters, start_experiment,
     Experiment,
 };
 use opsml_types::cards::experiment::{
@@ -18,5 +18,16 @@ pub fn add_experiment_module(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(get_experiment_parameters, m)?)?;
     m.add_function(wrap_pyfunction!(download_artifact, m)?)?;
     m.add_function(wrap_pyfunction!(start_experiment, m)?)?;
+    m.add_function(wrap_pyfunction!(fluent::log_metric, m)?)?;
+    m.add_function(wrap_pyfunction!(fluent::log_metrics, m)?)?;
+    m.add_function(wrap_pyfunction!(fluent::log_param, m)?)?;
+    m.add_function(wrap_pyfunction!(fluent::log_params, m)?)?;
+    m.add_function(wrap_pyfunction!(fluent::log_artifact, m)?)?;
+    m.add_function(wrap_pyfunction!(fluent::log_artifacts, m)?)?;
+    m.add_function(wrap_pyfunction!(fluent::log_figure, m)?)?;
+    m.add_function(wrap_pyfunction!(fluent::log_figure_from_path, m)?)?;
+    m.add_function(wrap_pyfunction!(fluent::set_tag, m)?)?;
+    m.add_function(wrap_pyfunction!(fluent::set_tags, m)?)?;
+    m.add_function(wrap_pyfunction!(fluent::active_experiment, m)?)?;
     Ok(())
 }
diff --git a/py-opsml/src/flavors.rs b/py-opsml/src/flavors.rs
new file mode 100644
index 0000000000..cc6de5aeda
--- /dev/null
+++ b/py-opsml/src/flavors.rs
@@ -0,0 +1,211 @@
+use opsml_cards::ModelCard;
+use opsml_experiment::active;
+use opsml_interfaces::{
+    CatBoostModel, HuggingFaceModel, HuggingFaceTask, LightGBMModel, LightningModel, OnnxModel,
+    SklearnModel, TensorFlowModel, TorchModel, XGBoostModel,
+};
+use opsml_semver::VersionType;
+use opsml_types::TaskType;
+use pyo3::prelude::*;
+
+fn resolve_space(py: Python<'_>, explicit: Option<String>) -> PyResult<String> {
+    if let Some(space) = explicit {
+        return Ok(space);
+    }
+
+    let exp = active::current(py)?;
+    let exp_ref = exp.borrow(py);
+    exp_ref
+        .experiment
+        .bind(py)
+        .getattr("space")?
+        .extract::<String>()
+}
+
+fn register_built_interface<'py>(
+    py: Python<'py>,
+    interface: Bound<'py, PyAny>,
+    space: String,
+    name: String,
+    save_kwargs: Option<&Bound<'py, PyAny>>,
+) -> PyResult<Py<ModelCard>> {
+    let card = ModelCard::new(
+        py,
+        &interface,
+        Some(&space),
+        Some(&name),
+        None,
+        None,
+        None,
+        None,
+        None,
+    )?;
+    let card_py = Py::new(py, card)?;
+    let card_bound = card_py.bind(py).clone().into_any();
+
+    let exp = active::current(py)?;
+    exp.borrow_mut(py)
+        .register_card(&card_bound, VersionType::Minor, None, None, save_kwargs)?;
+
+    Ok(card_py)
+}
+
+macro_rules! impl_simple_log_model {
+    ($fn_name:ident, $iface_ty:ty) => {
+        #[pyfunction]
+        #[pyo3(signature = (
+                                    model, *, name, space=None, sample_data=None, preprocessor=None,
+                                    task_type=None, drift_profile=None, save_kwargs=None
+                                ))]
+        #[allow(clippy::too_many_arguments)]
+        pub fn $fn_name<'py>(
+            py: Python<'py>,
+            model: Bound<'py, PyAny>,
+            name: String,
+            space: Option<String>,
+            sample_data: Option<Bound<'py, PyAny>>,
+            preprocessor: Option<Bound<'py, PyAny>>,
+            task_type: Option<TaskType>,
+            drift_profile: Option<Bound<'py, PyAny>>,
+            save_kwargs: Option<Bound<'py, PyAny>>,
+        ) -> PyResult<Py<ModelCard>> {
+            let space = resolve_space(py, space)?;
+            let (sub, base) = <$iface_ty>::new(
+                py,
+                Some(&model),
+                preprocessor.as_ref(),
+                sample_data.as_ref(),
+                task_type,
+                drift_profile.as_ref(),
+            )?;
+
+            let init = pyo3::PyClassInitializer::from(base).add_subclass(sub);
+            let iface_py: Py<$iface_ty> = Py::new(py, init)?;
+            let iface_bound = iface_py.bind(py).clone().into_any();
+            register_built_interface(py, iface_bound, space, name, save_kwargs.as_ref())
+        }
+    };
+}
+
+impl_simple_log_model!(sklearn_log_model, SklearnModel);
+impl_simple_log_model!(xgboost_log_model, XGBoostModel);
+impl_simple_log_model!(lightgbm_log_model, LightGBMModel);
+impl_simple_log_model!(catboost_log_model, CatBoostModel);
+impl_simple_log_model!(torch_log_model, TorchModel);
+impl_simple_log_model!(tensorflow_log_model, TensorFlowModel);
+
+#[pyfunction]
+#[pyo3(signature = (
+    trainer, *, name, space=None, sample_data=None, preprocessor=None,
+    task_type=None, drift_profile=None, save_kwargs=None
+))]
+#[allow(clippy::too_many_arguments)]
+pub fn lightning_log_model<'py>(
+    py: Python<'py>,
+    trainer: Bound<'py, PyAny>,
+    name: String,
+    space: Option<String>,
+    sample_data: Option<Bound<'py, PyAny>>,
+    preprocessor: Option<Bound<'py, PyAny>>,
+    task_type: Option<TaskType>,
+    drift_profile: Option<Bound<'py, PyAny>>,
+    save_kwargs: Option<Bound<'py, PyAny>>,
+) -> PyResult<Py<ModelCard>> {
+    let space = resolve_space(py, space)?;
+    let (sub, base) = LightningModel::new(
+        py,
+        Some(&trainer),
+        preprocessor.as_ref(),
+        sample_data.as_ref(),
+        task_type,
+        drift_profile.as_ref(),
+    )?;
+    let init = pyo3::PyClassInitializer::from(base).add_subclass(sub);
+    let iface_py: Py<LightningModel> = Py::new(py, init)?;
+    register_built_interface(
+        py,
+        iface_py.bind(py).clone().into_any(),
+        space,
+        name,
+        save_kwargs.as_ref(),
+    )
+}
+
+#[pyfunction]
+#[pyo3(signature = (
+    model, *, name, space=None, sample_data=None,
+    tokenizer=None, feature_extractor=None, image_processor=None,
+    hf_task=None, task_type=None, drift_profile=None, save_kwargs=None
+))]
+#[allow(clippy::too_many_arguments)]
+pub fn huggingface_log_model<'py>(
+    py: Python<'py>,
+    model: Bound<'py, PyAny>,
+    name: String,
+    space: Option<String>,
+    sample_data: Option<Bound<'py, PyAny>>,
+    tokenizer: Option<Bound<'py, PyAny>>,
+    feature_extractor: Option<Bound<'py, PyAny>>,
+    image_processor: Option<Bound<'py, PyAny>>,
+    hf_task: Option<HuggingFaceTask>,
+    task_type: Option<TaskType>,
+    drift_profile: Option<Bound<'py, PyAny>>,
+    save_kwargs: Option<Bound<'py, PyAny>>,
+) -> PyResult<Py<ModelCard>> {
+    let space = resolve_space(py, space)?;
+    let (sub, base) = HuggingFaceModel::new(
+        py,
+        Some(&model),
+        tokenizer.as_ref(),
+        feature_extractor.as_ref(),
+        image_processor.as_ref(),
+        sample_data.as_ref(),
+        hf_task,
+        task_type,
+        drift_profile.as_ref(),
+    )?;
+    let init = pyo3::PyClassInitializer::from(base).add_subclass(sub);
+    let iface_py: Py<HuggingFaceModel> = Py::new(py, init)?;
+    register_built_interface(
+        py,
+        iface_py.bind(py).clone().into_any(),
+        space,
+        name,
+        save_kwargs.as_ref(),
+    )
+}
+
+#[pyfunction]
+#[pyo3(signature = (
+    model, *, name, space=None, sample_data=None,
+    task_type=None, drift_profile=None, save_kwargs=None
+))]
+#[allow(clippy::too_many_arguments)]
+pub fn onnx_log_model<'py>(
+    py: Python<'py>,
+    model: Bound<'py, PyAny>,
+    name: String,
+    space: Option<String>,
+    sample_data: Option<Bound<'py, PyAny>>,
+    task_type: Option<TaskType>,
+    drift_profile: Option<Bound<'py, PyAny>>,
+    save_kwargs: Option<Bound<'py, PyAny>>,
+) -> PyResult<Py<ModelCard>> {
+    let space = resolve_space(py, space)?;
+    let (sub, base) = OnnxModel::new(
+        py,
+        Some(&model),
+        sample_data.as_ref(),
+        task_type,
+        drift_profile.as_ref(),
+    )?;
+    let init = pyo3::PyClassInitializer::from(base).add_subclass(sub);
+    let iface_py: Py<OnnxModel> = Py::new(py, init)?;
+    register_built_interface(
+        py,
+        iface_py.bind(py).clone().into_any(),
+        space,
+        name,
+        save_kwargs.as_ref(),
+    )
+}
diff --git a/py-opsml/src/lib.rs b/py-opsml/src/lib.rs
index 42b36c5418..ff88c2b0a3 100644
--- a/py-opsml/src/lib.rs
+++ b/py-opsml/src/lib.rs
@@ -4,6 +4,7 @@ pub mod card;
 pub mod cli;
 pub mod data;
 pub mod experiment;
+pub mod flavors;
 pub mod logging;
 pub mod mocks;
 pub mod model;
@@ -37,5 +38,15 @@ fn _opsml(m: &Bound<'_, PyModule>) -> PyResult<()> {
     mocks::add_mocks_module(m)?;
     service::add_service_module(m)?;
 
+    m.add_function(wrap_pyfunction!(flavors::sklearn_log_model, m)?)?;
+    m.add_function(wrap_pyfunction!(flavors::xgboost_log_model, m)?)?;
+    m.add_function(wrap_pyfunction!(flavors::lightgbm_log_model, m)?)?;
+    m.add_function(wrap_pyfunction!(flavors::catboost_log_model, m)?)?;
+    m.add_function(wrap_pyfunction!(flavors::torch_log_model, m)?)?;
+    m.add_function(wrap_pyfunction!(flavors::lightning_log_model, m)?)?;
+    m.add_function(wrap_pyfunction!(flavors::tensorflow_log_model, m)?)?;
+    m.add_function(wrap_pyfunction!(flavors::huggingface_log_model, m)?)?;
+    m.add_function(wrap_pyfunction!(flavors::onnx_log_model, m)?)?;
+
     Ok(())
 }
diff --git a/py-opsml/tests/conftest.py b/py-opsml/tests/conftest.py
index 36965882eb..6dcbc29d83 100644
--- a/py-opsml/tests/conftest.py
+++ b/py-opsml/tests/conftest.py
@@ -40,19 +40,10 @@ class MockInterface(BaseModel):
 
 
 class CustomModel(ModelInterface):
-    def __new__(cls, preprocessor=None, **kwargs):
-        instance = super(CustomModel, cls).__new__(
-            cls,
-            **kwargs,
-        )
-
-        return instance
-
     def __init__(self, preprocessor, **kwargs):
         """Init method for the custom model interface."""
 
-        super().__init__()
-
+        super().__init__(**kwargs)
         self.preprocessor = preprocessor
 
     def save(self, path, save_kwargs=None):
diff --git a/py-opsml/tests/interfaces/model/test_custom.py b/py-opsml/tests/interfaces/model/test_custom.py
index 8b88e8ed91..f6ff680424 100644
--- a/py-opsml/tests/interfaces/model/test_custom.py
+++ b/py-opsml/tests/interfaces/model/test_custom.py
@@ -1,24 +1,20 @@
+from pathlib import Path
+
+import pytest
 from opsml.model import (
     ModelInterface,
-    TaskType,
     ModelInterfaceMetadata,
     ModelInterfaceSaveMetadata,
-    ModelSaveKwargs,
     ModelLoadKwargs,
+    ModelSaveKwargs,
+    TaskType,
 )
 from sklearn import linear_model  # type: ignore
-from pathlib import Path
 
 
 class CustomInterface(ModelInterface):
-    # must be defined if you want to pass args to ModelInterface
-    def __new__(cls, foo=None, **kwargs):
-        instance = super(CustomInterface, cls).__new__(cls, **kwargs)
-        return instance
-
-    def __init__(self, foo, **kwargs):
-        super().__init__()
-
+    def __init__(self, foo: int, **kwargs):
+        super().__init__(**kwargs)
         self.foo = foo
 
     def save(
@@ -59,4 +55,32 @@ def test_custom_interface(tmp_path: Path, regression_data):
     kwargs = {"model": reg, "task_type": TaskType.Regression, "sample_data": X}
     interface = CustomInterface(foo=2, **kwargs)
 
+    assert interface.foo == 2
+    assert interface.task_type == TaskType.Regression
     interface.save(tmp_path)
+
+
+def test_model_interface_direct_init(regression_data):
+    X, y = regression_data
+    reg = linear_model.LinearRegression().fit(X, y)
+
+    interface = ModelInterface(
+        model=reg,
+        sample_data=X,
+        task_type=TaskType.Regression,
+    )
+
+    assert interface.task_type == TaskType.Regression
+
+
+def test_model_interface_direct_init_rejects_unknown_kwargs(regression_data):
+    X, y = regression_data
+    reg = linear_model.LinearRegression().fit(X, y)
+
+    with pytest.raises(RuntimeError, match="Unexpected ModelInterface.__init__.*typo"):
+        ModelInterface(
+            model=reg,
+            sample_data=X,
+            task_type=TaskType.Regression,
+            typo=True,
+        )
diff --git a/py-opsml/tests/test_fluent.py b/py-opsml/tests/test_fluent.py
new file mode 100644
index 0000000000..2703a070c7
--- /dev/null
+++ b/py-opsml/tests/test_fluent.py
@@ -0,0 +1,228 @@
+from pathlib import Path
+
+import matplotlib.pyplot as plt
+import numpy as np
+import opsml
+import opsml.sklearn
+import pytest
+from opsml import CardRegistries, start_experiment
+from opsml.experiment import Metric, Parameter, get_experiment_metrics, get_experiment_parameters
+from opsml.mock import OpsmlTestServer
+from sklearn.linear_model import LogisticRegression  # type: ignore
+from tests.conftest import WINDOWS_EXCLUDE
+
+
+def _assert_no_active_experiment() -> None:
+    with pytest.raises(RuntimeError, match="no active experiment"):
+        opsml.active_experiment()
+
+
+@pytest.mark.skipif(WINDOWS_EXCLUDE, reason="skipping")
+def test_log_metric_no_active_raises():
+    with pytest.raises(RuntimeError, match="no active experiment"):
+        opsml.log_metric("accuracy", 0.9)
+
+
+@pytest.mark.skipif(WINDOWS_EXCLUDE, reason="skipping")
+def test_exception_inside_with_pops_active():
+    with OpsmlTestServer(cleanup=True):
+        with pytest.raises(ValueError, match="boom"):
+            with start_experiment(space="fluent", name="raises"):
+                raise ValueError("boom")
+
+        _assert_no_active_experiment()
+
+
+@pytest.mark.skipif(WINDOWS_EXCLUDE, reason="skipping")
+def test_two_sequential_experiments_isolate():
+    with OpsmlTestServer(cleanup=True):
+        with start_experiment(space="fluent", name="one") as exp1:
+            opsml.log_metric("metric_one", 1.0)
+
+        with start_experiment(space="fluent", name="two") as exp2:
+            opsml.log_metric("metric_two", 2.0)
+
+        metric_names_1 = {metric.name for metric in get_experiment_metrics(exp1.card.uid)}
+        metric_names_2 = {metric.name for metric in get_experiment_metrics(exp2.card.uid)}
+
+        assert "metric_one" in metric_names_1
+        assert "metric_two" not in metric_names_1
+        assert "metric_two" in metric_names_2
+        assert "metric_one" not in metric_names_2
+
+
+@pytest.mark.skipif(WINDOWS_EXCLUDE, reason="skipping")
+def test_active_stack_depth_zero_after_with():
+    with OpsmlTestServer(cleanup=True):
+        with start_experiment(space="fluent", name="normal"):
+            assert opsml.active_experiment() is not None
+
+        _assert_no_active_experiment()
+
+
+@pytest.mark.skipif(WINDOWS_EXCLUDE, reason="skipping")
+def test_log_metric_uses_active():
+    with OpsmlTestServer(cleanup=True):
+        with start_experiment(space="fluent", name="metric") as exp:
+            opsml.log_metric("accuracy", 0.91)
+
+        metrics = get_experiment_metrics(exp.card.uid)
+        assert any(metric.name == "accuracy" and metric.value == 0.91 for metric in metrics)
+
+
+@pytest.mark.skipif(WINDOWS_EXCLUDE, reason="skipping")
+def test_log_metrics_uses_active():
+    with OpsmlTestServer(cleanup=True):
+        with start_experiment(space="fluent", name="metrics") as exp:
+            opsml.log_metrics([Metric(name="loss", value=0.1), Metric(name="loss", value=0.2)])
+
+        metrics = get_experiment_metrics(exp.card.uid)
+        assert len(metrics) == 2
+
+
+@pytest.mark.skipif(WINDOWS_EXCLUDE, reason="skipping")
+def test_log_param_uses_active():
+    with OpsmlTestServer(cleanup=True):
+        with start_experiment(space="fluent", name="param") as exp:
+            opsml.log_param("n_estimators", 10)
+
+        params = get_experiment_parameters(exp.card.uid)
+        assert any(param.name == "n_estimators" for param in params)
+
+
+@pytest.mark.skipif(WINDOWS_EXCLUDE, reason="skipping")
+def test_log_params_dict_form():
+    with OpsmlTestServer(cleanup=True):
+        with start_experiment(space="fluent", name="params-dict") as exp:
+            opsml.log_params({"alpha": 0.1, "solver": "lbfgs"})
+
+        names = {param.name for param in get_experiment_parameters(exp.card.uid)}
+        assert {"alpha", "solver"}.issubset(names)
+
+
+@pytest.mark.skipif(WINDOWS_EXCLUDE, reason="skipping")
+def test_log_params_list_form():
+    with OpsmlTestServer(cleanup=True):
+        with start_experiment(space="fluent", name="params-list") as exp:
+            opsml.log_params([Parameter(name="alpha", value=0.1)])
+
+        params = get_experiment_parameters(exp.card.uid)
+        assert any(param.name == "alpha" for param in params)
+
+
+@pytest.mark.skipif(WINDOWS_EXCLUDE, reason="skipping")
+def test_log_artifact_uses_active(tmp_path: Path):
+    path = tmp_path / "artifact.txt"
+    path.write_text("hello")
+
+    with OpsmlTestServer(cleanup=True):
+        with start_experiment(space="fluent", name="artifact") as exp:
+            opsml.log_artifact(str(path))
+
+        assert any(path.endswith("artifact.txt") for path in exp.card.list_artifacts())
+
+
+@pytest.mark.skipif(WINDOWS_EXCLUDE, reason="skipping")
+def test_log_artifacts_directory(tmp_path: Path):
+    artifact_dir = tmp_path / "artifacts"
+    artifact_dir.mkdir()
+    (artifact_dir / "one.txt").write_text("one")
+    (artifact_dir / "two.txt").write_text("two")
+
+    with OpsmlTestServer(cleanup=True):
+        with start_experiment(space="fluent", name="artifacts") as exp:
+            opsml.log_artifacts(str(artifact_dir))
+
+        files = set(exp.card.list_artifacts())
+        assert any(path.endswith("one.txt") for path in files)
+        assert any(path.endswith("two.txt") for path in files)
+
+
+@pytest.mark.skipif(WINDOWS_EXCLUDE, reason="skipping")
+def test_log_figure_matplotlib():
+    with OpsmlTestServer(cleanup=True):
+        with start_experiment(space="fluent", name="figure") as exp:
+            fig, ax = plt.subplots()
+            ax.plot([1, 2], [3, 4])
+            opsml.log_figure("line.png", fig)
+            plt.close(fig)
+
+        assert any(path.endswith("line.png") for path in exp.card.list_artifacts())
+
+
+@pytest.mark.skipif(WINDOWS_EXCLUDE, reason="skipping")
+def test_set_tag_persists_on_exit():
+    with OpsmlTestServer(cleanup=True):
+        with start_experiment(space="fluent", name="tag") as exp:
+            opsml.set_tag("source:mlflow-migration")
+
+        loaded = CardRegistries().experiment.load_card(uid=exp.card.uid)
+        assert "source:mlflow-migration" in loaded.tags
+
+
+@pytest.mark.skipif(WINDOWS_EXCLUDE, reason="skipping")
+def test_set_tags_replaces():
+    with OpsmlTestServer(cleanup=True):
+        with start_experiment(space="fluent", name="tags") as exp:
+            opsml.set_tags(["a", "b"])
+            opsml.set_tags(["c"])
+
+        loaded = CardRegistries().experiment.load_card(uid=exp.card.uid)
+        assert loaded.tags == ["c"]
+
+
+@pytest.mark.skipif(WINDOWS_EXCLUDE, reason="skipping")
+def test_set_tag_then_set_tags_replaces():
+    with OpsmlTestServer(cleanup=True):
+        with start_experiment(space="fluent", name="tags-replace") as exp:
+            opsml.set_tag("a")
+            opsml.set_tags(["b", "c"])
+
+        loaded = CardRegistries().experiment.load_card(uid=exp.card.uid)
+        assert loaded.tags == ["b", "c"]
+
+
+@pytest.mark.skipif(WINDOWS_EXCLUDE, reason="skipping")
+def test_nested_experiment_stack():
+    with OpsmlTestServer(cleanup=True):
+        with start_experiment(space="fluent", name="outer") as outer:
+            opsml.log_metric("outer_before", 1.0)
+            with outer.start_experiment(space="fluent", name="inner") as inner:
+                opsml.log_metric("inner_only", 2.0)
+            opsml.log_metric("outer_after", 3.0)
+
+        outer_names = {metric.name for metric in get_experiment_metrics(outer.card.uid)}
+        inner_names = {metric.name for metric in get_experiment_metrics(inner.card.uid)}
+
+        assert {"outer_before", "outer_after"}.issubset(outer_names)
+        assert "inner_only" not in outer_names
+        assert "inner_only" in inner_names
+
+
+@pytest.mark.skipif(WINDOWS_EXCLUDE, reason="skipping")
+def test_active_experiment_returns_current():
+    with OpsmlTestServer(cleanup=True):
+        with start_experiment(space="fluent", name="active") as exp:
+            assert opsml.active_experiment().card.uid == exp.card.uid
+
+
+@pytest.mark.skipif(WINDOWS_EXCLUDE, reason="skipping")
+def test_active_experiment_outside_raises():
+    _assert_no_active_experiment()
+
+
+@pytest.mark.skipif(WINDOWS_EXCLUDE, reason="skipping")
+def test_full_mlflow_parity_smoke():
+    X = np.random.rand(50, 4)
+    y = (X.sum(axis=1) > 2).astype(int)
+    clf = LogisticRegression().fit(X, y)
+
+    with OpsmlTestServer(cleanup=True):
+        with start_experiment(space="parity", name="rust-fluent") as exp:
+            card = opsml.sklearn.log_model(clf, name="lr", sample_data=X[:5])
+            opsml.log_metric("accuracy", 0.97)
+            opsml.log_params({"penalty": "l2", "C": 1.0})
+            opsml.set_tag("source:mlflow-migration")
+            assert opsml.active_experiment().card.uid == exp.card.uid
+
+        assert card.version is not None
diff --git a/py-opsml/tests/test_fluent_flavors.py b/py-opsml/tests/test_fluent_flavors.py
new file mode 100644
index 0000000000..b9c1ee937f
--- /dev/null
+++ b/py-opsml/tests/test_fluent_flavors.py
@@ -0,0 +1,272 @@
+import numpy as np
+import pytest
+from opsml import CardRegistry, RegistryType, TaskType, start_experiment
+from opsml.mock import OpsmlTestServer
+
+from tests.conftest import WINDOWS_EXCLUDE
+
+
+def _assert_registered(card):
+    assert card.uid is not None
+    assert card.version is not None
+    loaded = CardRegistry(registry_type=RegistryType.Model).load_card(uid=card.uid)
+    assert loaded.uid == card.uid
+    assert loaded.version == card.version
+    assert loaded.name == card.name
+    return loaded
+
+
+@pytest.mark.skipif(WINDOWS_EXCLUDE, reason="skipping")
+def test_sklearn_log_model_round_trip():
+    opsml_sklearn = pytest.importorskip("opsml.sklearn")
+    linear_model = pytest.importorskip("sklearn.linear_model")
+
+    X = np.random.rand(40, 4)
+    y = (X.sum(axis=1) > 2).astype(int)
+    model = linear_model.LogisticRegression().fit(X, y)
+
+    with OpsmlTestServer(cleanup=True):
+        with start_experiment(space="flavors", name="sklearn") as exp:
+            card = opsml_sklearn.log_model(
+                model,
+                name="sklearn-lr",
+                sample_data=X[:5],
+                task_type=TaskType.Classification,
+            )
+
+        loaded_model = _assert_registered(card)
+        loaded_exp = CardRegistry(registry_type=RegistryType.Experiment).load_card(uid=exp.card.uid)
+        assert loaded_model.experimentcard_uid == exp.card.uid
+        assert card.uid in loaded_exp.uids.modelcard_uids
+
+
+@pytest.mark.skipif(WINDOWS_EXCLUDE, reason="skipping")
+def test_sklearn_log_model_requires_active_experiment():
+    opsml_sklearn = pytest.importorskip("opsml.sklearn")
+    linear_model = pytest.importorskip("sklearn.linear_model")
+
+    X = np.random.rand(40, 4)
+    y = (X.sum(axis=1) > 2).astype(int)
+    model = linear_model.LogisticRegression().fit(X, y)
+
+    with OpsmlTestServer(cleanup=True):
+        with pytest.raises(RuntimeError, match="no active experiment"):
+            opsml_sklearn.log_model(
+                model,
+                name="sklearn-lr",
+                space="flavors",
+                sample_data=X[:5],
+                task_type=TaskType.Classification,
+            )
+
+
+@pytest.mark.skipif(WINDOWS_EXCLUDE, reason="skipping")
+def test_xgboost_log_model_round_trip():
+    opsml_xgboost = pytest.importorskip("opsml.xgboost")
+    xgb = pytest.importorskip("xgboost")
+
+    X = np.random.rand(20, 4)
+    y = (X.sum(axis=1) > 2).astype(int)
+    dtrain = xgb.DMatrix(X, y)
+    model = xgb.train(
+        {"max_depth": 2, "eta": 1, "objective": "binary:logistic"},
+        dtrain,
+        num_boost_round=2,
+    )
+
+    with OpsmlTestServer(cleanup=True):
+        with start_experiment(space="flavors", name="xgboost"):
+            card = opsml_xgboost.log_model(
+                model,
+                name="xgb",
+                sample_data=dtrain,
+                task_type=TaskType.Classification,
+            )
+
+        _assert_registered(card)
+
+
+@pytest.mark.skipif(WINDOWS_EXCLUDE, reason="skipping")
+def test_lightgbm_log_model_round_trip():
+    opsml_lightgbm = pytest.importorskip("opsml.lightgbm")
+    lgb = pytest.importorskip("lightgbm")
+
+    X = np.random.rand(20, 4)
+    y = (X.sum(axis=1) > 2).astype(int)
+    dataset = lgb.Dataset(X, y)
+    model = lgb.train(
+        {"objective": "binary", "verbosity": -1},
+        dataset,
+        num_boost_round=2,
+    )
+
+    with OpsmlTestServer(cleanup=True):
+        with start_experiment(space="flavors", name="lightgbm"):
+            card = opsml_lightgbm.log_model(
+                model,
+                name="lgb",
+                sample_data=dataset,
+                task_type=TaskType.Classification,
+            )
+
+        _assert_registered(card)
+
+
+@pytest.mark.skipif(WINDOWS_EXCLUDE, reason="skipping")
+def test_catboost_log_model_round_trip():
+    opsml_catboost = pytest.importorskip("opsml.catboost")
+    catboost = pytest.importorskip("catboost")
+
+    X = np.random.rand(20, 4)
+    y = (X.sum(axis=1) > 2).astype(int)
+    model = catboost.CatBoostClassifier(iterations=2, verbose=False).fit(X, y)
+
+    with OpsmlTestServer(cleanup=True):
+        with start_experiment(space="flavors", name="catboost"):
+            card = opsml_catboost.log_model(
+                model,
+                name="catboost",
+                sample_data=X[:5],
+                task_type=TaskType.Classification,
+            )
+
+        _assert_registered(card)
+
+
+@pytest.mark.skipif(WINDOWS_EXCLUDE, reason="skipping")
+def test_torch_log_model_round_trip():
+    opsml_torch = pytest.importorskip("opsml.torch")
+    torch = pytest.importorskip("torch")
+
+    model = torch.nn.Linear(4, 1)
+    sample = torch.rand(5, 4)
+
+    with OpsmlTestServer(cleanup=True):
+        with start_experiment(space="flavors", name="torch"):
+            card = opsml_torch.log_model(
+                model,
+                name="torch-linear",
+                sample_data=sample,
+                task_type=TaskType.Regression,
+            )
+
+        _assert_registered(card)
+
+
+@pytest.mark.skipif(WINDOWS_EXCLUDE, reason="skipping")
+def test_lightning_log_model_with_trainer():
+    opsml_lightning = pytest.importorskip("opsml.lightning")
+    lightning = pytest.importorskip("lightning")
+    torch = pytest.importorskip("torch")
+
+    class LightningModule(lightning.LightningModule):
+        def __init__(self):
+            super().__init__()
+            self.layer = torch.nn.Linear(1, 1)
+
+        def forward(self, x):
+            return self.layer(x)
+
+        def training_step(self, batch, batch_idx):
+            x, y = batch
+            return torch.nn.functional.mse_loss(self(x), y)
+
+        def configure_optimizers(self):
+            return torch.optim.SGD(self.parameters(), lr=0.01)
+
+    data = torch.utils.data.TensorDataset(torch.rand(8, 1), torch.rand(8, 1))
+    trainer = lightning.Trainer(
+        max_epochs=1,
+        logger=False,
+        enable_checkpointing=True,
+        enable_model_summary=False,
+    )
+    trainer.fit(LightningModule(), torch.utils.data.DataLoader(data, batch_size=4))
+
+    with OpsmlTestServer(cleanup=True):
+        with start_experiment(space="flavors", name="lightning"):
+            card = opsml_lightning.log_model(
+                trainer,
+                name="lightning-trainer",
+                sample_data=torch.rand(2, 1),
+                task_type=TaskType.Regression,
+            )
+
+        _assert_registered(card)
+
+
+@pytest.mark.tensorflow
+@pytest.mark.skipif(WINDOWS_EXCLUDE, reason="skipping")
+def test_tensorflow_log_model_round_trip():
+    opsml_tensorflow = pytest.importorskip("opsml.tensorflow")
+    tf = pytest.importorskip("tensorflow")
+
+    model = tf.keras.Sequential([tf.keras.layers.Input(shape=(4,)), tf.keras.layers.Dense(1)])
+    sample = np.random.rand(5, 4)
+
+    with OpsmlTestServer(cleanup=True):
+        with start_experiment(space="flavors", name="tensorflow"):
+            card = opsml_tensorflow.log_model(
+                model,
+                name="tf",
+                sample_data=sample,
+                task_type=TaskType.Regression,
+            )
+
+        _assert_registered(card)
+
+
+@pytest.mark.skipif(WINDOWS_EXCLUDE, reason="skipping")
+def test_huggingface_log_model_with_tokenizer_and_hf_task():
+    opsml_huggingface = pytest.importorskip("opsml.huggingface")
+    transformers = pytest.importorskip("transformers")
+    from opsml import HuggingFaceTask
+
+    config = transformers.BertConfig(
+        vocab_size=32,
+        hidden_size=8,
+        num_hidden_layers=1,
+        num_attention_heads=1,
+        intermediate_size=16,
+    )
+    model = transformers.BertModel(config)
+
+    with OpsmlTestServer(cleanup=True):
+        with start_experiment(space="flavors", name="huggingface"):
+            card = opsml_huggingface.log_model(
+                model,
+                name="hf",
+                hf_task=HuggingFaceTask.FeatureExtraction,
+                task_type=TaskType.Nlp,
+            )
+
+        _assert_registered(card)
+
+
+@pytest.mark.skipif(WINDOWS_EXCLUDE, reason="skipping")
+def test_onnx_log_model_round_trip():
+    opsml_onnx = pytest.importorskip("opsml.onnx")
+    onnx = pytest.importorskip("onnx")
+    helper = onnx.helper
+    tensor_proto = onnx.TensorProto
+
+    input_tensor = helper.make_tensor_value_info("input", tensor_proto.FLOAT, [None, 4])
+    output_tensor = helper.make_tensor_value_info("output", tensor_proto.FLOAT, [None, 4])
+    node = helper.make_node("Identity", inputs=["input"], outputs=["output"])
+    graph = helper.make_graph([node], "identity", [input_tensor], [output_tensor])
+    model = helper.make_model(
+        graph,
+        ir_version=11,
+        opset_imports=[helper.make_operatorsetid("", 11)],
+    )
+
+    with OpsmlTestServer(cleanup=True):
+        with start_experiment(space="flavors", name="onnx"):
+            card = opsml_onnx.log_model(
+                model,
+                name="onnx-identity",
+                sample_data=np.random.rand(5, 4).astype("float32"),
+                task_type=TaskType.Regression,
+            )
+
+        _assert_registered(card)