Skip to content

architecture_and_runtime_flow.md

Latest commit

 

History

History
102 lines (73 loc) · 3.07 KB

architecture_and_runtime_flow.md

File metadata and controls

102 lines (73 loc) · 3.07 KB

Architecture And Runtime Flow

You need a mental model of how a query moves through strategy, directives, signals, and runtime execution.

After this guide, you can trace one request end-to-end and debug failures at the correct layer.

Runtime Flow

  1. Agent receives query signal (for example ai.react.query).
  2. Strategy (Jido.AI.Reasoning.*.Strategy) translates instruction into machine message.
  3. Machine emits directives (Jido.AI.Directive.*).
  4. Runtime executes directives (LLM, tools, embedding, emits lifecycle signals).
  5. Signals (Jido.AI.Signal.*) route back into strategy commands.
  6. Strategy updates state and eventually completes request.

Key Boundaries

  • Strategy: state transitions and orchestration policy
  • Directive: side-effect intent only
  • Runtime: side-effect execution and signal emission
  • Signal: typed contract between runtime and strategy

Minimal Trace Setup

:telemetry.attach_many(
  "jido-ai-trace",
  [
    [:jido, :ai, :llm, :start],
    [:jido, :ai, :llm, :complete],
    [:jido, :ai, :tool, :start],
    [:jido, :ai, :tool, :complete]
  ],
  fn event, measurements, metadata, _ ->
    IO.inspect({event, measurements, metadata})
  end,
  nil
)

Failure Mode: Fixing Bugs In The Wrong Layer

Symptom:

  • strategy logic changed to fix provider/network behavior

Fix:

  • keep strategy pure and orchestration-focused
  • fix provider behavior at the direct ReqLLM call-site
  • fix execution semantics in directive runtime path

Defaults You Should Know

  • strategies store internal data in agent.state.__strategy__
  • request lifecycle signals are standardized under ai.request.*
  • canonical signal contracts are defined by Jido.AI.Signal and strategy routes

Compile-Cycle Triage With mix xref

Use mix xref whenever recompilation feels wider than expected:

# Show compile-connected strongly connected components (SCCs)
mix xref graph --format cycles --label compile-connected

# Show cycle counts and graph stats
mix xref graph --format stats --label compile-connected

# Trace a dependency path between files
mix xref graph --source lib/path_a.ex --sink lib/path_b.ex

# Show direct compile edges from one file
mix xref graph --label compile --source lib/path_a.ex

Interpretation:

  • compile edges have the highest recompilation impact.
  • export edges recompile dependents when a module public API changes.
  • runtime edges have the lowest compile-time impact.
  • Prioritize removing SCCs that include at least one compile edge.

Registry Lifecycle Guarantees

Jido.AI.Skill.Registry supports:

  • explicit supervised startup via start_link/1
  • lazy startup via ensure_started/0 for call-site safety
  • startup-order independence for library consumers

When To Use / Not Use

Use this guide when:

  • you are debugging execution flow or extending runtime behavior

Do not use this guide when:

  • you only need to build and run an agent quickly

Next