Feature Placement

Purpose

This is the shortest possible answer to “where should this feature go?”.

Read architecture.md first if the boundary between agent/* and the legacy runtime is unclear. Use this file for fast triage before reading the longer algorithm-integration-guide.md. After choosing the matching row below, read only the guide sections relevant to that change type for interface, schema, test, example, and benchmark expectations.

Maintenance rule:

  • If a change adds a new workflow, capability family, persisted artifact type, or changes the recommended ownership for a feature, update this table in the same change.

Decision Table

You are adding

Primary files/packages

Notes

A new MCP tool that exposes an existing workflow

src/dymad/agent/mcp/user_tools.py or src/dymad/agent/mcp/demo_tools.py, then src/dymad/agent/mcp/server.py

Keep business logic out of server.py; it should register tools, not implement them

A new package CLI command that exposes an existing user workflow

src/dymad/cli.py for argument parsing and src/dymad/agent/app/* for shared path/config workflow assembly

Keep cli.py thin; use registry/compiler/executor/facade/store boundaries instead of routing directly to trainers

A new user-mode training capability or model family choice

src/dymad/agent/registry/models.py, src/dymad/agent/registry/workflows.py, src/dymad/agent/registry/training_schema.py

Add stable keys, summaries, dataset compatibility, allowed overrides, CV support metadata, translation guidance, constraint notes, and examples

A new user-mode request field or override validation rule

src/dymad/agent/compiler/training.py, src/dymad/agent/compiler/schemas.py, maybe src/dymad/agent/registry/training_schema.py

Compiler owns validation and normalization of user input, including overrides.cv sweep/search/bounds/selection config and profile-default phase preservation

A new analysis workflow

src/dymad/agent/registry/analyses.py, src/dymad/agent/compiler/analysis.py, src/dymad/agent/exec/workflow.py

Registry declares the workflow, compiler validates inputs, executor runs it

A new persisted request/artifact handle

src/dymad/agent/store/object_store.py, src/dymad/agent/store/filesystem_artifact_store.py, src/dymad/agent/facade/handles.py, src/dymad/agent/facade/operations.py

Add both record persistence and typed facade accessors

A new execution workflow that stitches existing pieces together

src/dymad/agent/exec/workflow.py or another focused module under src/dymad/agent/exec

Executor owns orchestration and workflow results; durable subprocess entrypoints such as async training workers belong in focused modules under agent/exec

A new model family or variant implementation

src/dymad/models/* and then src/dymad/agent/registry/models.py

Implementation first, registry exposure second

A new training phase kind

src/dymad/training/phases.py, src/dymad/training/phase_pipeline.py, maybe compiler/registry schema files

Runtime phase semantics do not belong in MCP adapters

A new checkpoint compatibility behavior

src/dymad/io/checkpoint.py, maybe src/dymad/agent/exec/workflow.py and facade/store files

Keep the public dymad.io behavior accurate even if the executor only plans part of the flow

A new low-level runtime, transform, or batching behavior

src/dymad/core/*, src/dymad/io/*, src/dymad/training/*

Do not route this through agent/* unless the boundary contract changes

A new numerical primitive or solver

src/dymad/numerics/*

Keep numerics isolated from agent/MCP concerns

A new spectral runtime or adapter behavior

src/dymad/sako/*, then registry/executor files if you want it exposed as an analysis workflow

Library behavior first, user-facing exposure second

Follow-Up Guide Sections

After the decision table identifies the likely owner, use this map to read the focused parts of algorithm-integration-guide.md:

Triage result

Read these guide sections

MCP tool, user-facing capability, request validation, execution workflow, or persisted handle

MCP Tools, Agent-Facing Schema Checklist, Data Structures To Consume And Return, Mandatory Tests, What Not To Touch

Model family or variant

Models and Prediction, Agent-Facing Schema Checklist if user-mode exposed, Mandatory Tests, Naming Conventions

Training phase or optimizer behavior

Training Algorithms and Phases, Agent-Facing Schema Checklist if user-mode exposed, Mandatory Tests, Examples

Analysis workflow or spectral adapter

Analysis Workflows, Agent-Facing Schema Checklist, Mandatory Tests, Examples

Core runtime, transform, batching, or data structure

Core Data Structures, Data Structures To Consume And Return, Mandatory Tests

Numerical primitive or solver

Numerical Algorithms, Mandatory Tests, Benchmarks when the hot path changes

Runnable example or benchmark

Examples, Benchmarks, Naming Conventions

Rules of Thumb

  • If the change introduces a new stable user-facing key, start in agent/registry/*.

  • If the change turns file paths or CLI config into a workflow request, put the path/config adaptation in agent/app/*, then call the same compiler/executor path as MCP user mode.

  • If the change teaches clients how to translate natural language into a user-mode request, put that guidance in agent/registry/*, not in MCP adapters or runtime code.

  • If the change validates or normalizes user input, start in agent/compiler/*.

  • If the change coordinates multiple steps, start in agent/exec/*.

  • If the change stores something under a handle, start in agent/store/* and agent/facade/*.

  • If the change is model/math/runtime behavior, it probably does not belong in agent/*.

  • If you need to touch server.py, you usually also need to touch a tool adapter first.

Common Mistakes

  • Putting workflow logic directly in src/dymad/agent/mcp/server.py

  • Routing package CLI configs directly into trainers instead of through agent/app, compiler, and executor boundaries

  • Adding user-mode string parsing to demo_tools.py instead of compiler/*

  • Adding registry-style metadata ad hoc inside executor methods

  • Adding persistence behavior directly in executor methods instead of the store/facade layer

  • Treating agent/* as the place for numerical or model implementation details

Test Pointers

Change type

Start with these tests

MCP mode/tool registration

tests/test_mcp_server_modes.py, tests/test_demo_tools.py, tests/test_mcp_user_tools.py

Package CLI commands and path-first user workflows

tests/test_agent_cli.py

Training capability/compiler changes

tests/test_training_compiler.py, tests/test_compiled_training_requests.py, tests/test_agent_registry.py

Analysis workflow changes

tests/test_analysis_workflows.py

Persisted handle/store/facade changes

tests/test_boundary_persistence.py, tests/test_checkpoint_e2e_layering.py

Checkpoint boundary changes

tests/test_public_load_model_boundary.py, tests/test_checkpoint_e2e_layering.py

Training runtime/phase changes

tests/test_training_phase_runtime.py plus the closest workflow tests

If Unsure

Start from the user-facing outcome:

  1. Stable capability name or workflow choice: registry/*

  2. Request validation and compile step: compiler/*

  3. Execution path: exec/*

  4. Durable artifact state: facade/* and store/*

  5. Actual model/runtime/math behavior: implementation packages