Package Overview (Production Map)

View Source

You want a clear map of what jido_ai provides before production rollout.

After this guide, you should be able to explain the package in a prioritized way and choose the right integration surface for each workload.

Core Product Surface

jido_ai is an AI runtime layer for Jido agents with:

  1. Agent macros with built-in reasoning strategies
  2. Tool-calling orchestration over Jido.Action modules
  3. Strategy-agnostic skills loading and registry
  4. Plugin-based capability mixins for reusable runtime features
  5. Action APIs for direct AI workflows outside agent macros
  6. First-class observability via signals, directives, and telemetry

Priority 1: Jido.AI.Agent (Default ReAct Agent)

Jido.AI.Agent is the anchor feature.

  • It is the generic AI agent macro.
  • Under the hood it uses Jido.AI.Reasoning.ReAct.Strategy.
  • It is built for tool use through a ReAct loop (reason, call tool, continue).
  • It supports request handles and async orchestration (ask/await/ask_sync).
  • ReAct requests can narrow tools per run with allowed_tools or fully override them with tools.
  • It uses standardized lifecycle and runtime contracts (ai.request.*, ai.llm.*, ai.tool.*).

If your production workload needs reliable tool-calling agents, this is the default entry point.

Priority 2: Multi-Strategy Agent Macros

jido_ai ships specialized agent macros for different reasoning patterns:

Supported strategy family:

  • ReAct
  • Chain-of-Draft
  • Chain-of-Thought
  • Algorithm-of-Thoughts
  • Tree-of-Thoughts
  • Graph-of-Thoughts
  • TRM
  • Adaptive

Use these when reasoning policy is part of the product requirement, not just a model prompt detail.

Tree-of-Thoughts Runtime Contract (Production)

Jido.AI.ToTAgent now returns a structured result contract (hard switch), not a plain string:

  • best: best-ranked candidate
  • candidates: top-K ranked leaves
  • termination: reason/status/depth/node-count/duration
  • tree: traversal and search-shape metadata
  • usage: accumulated token usage
  • diagnostics: parser mode/retries, convergence, tool-round diagnostics

ToT flexibility controls exposed at the agent macro level:

  • top_k, min_depth, max_nodes, max_duration_ms, beam_width
  • early_success_threshold, convergence_window, min_score_improvement
  • max_parse_retries
  • tools, tool_context, request_transformer, tool_timeout_ms, tool_max_retries, tool_retry_backoff_ms, max_tool_round_trips

Priority 3: Skills System (SKILL.md / skills.io-aligned workflow)

Skills are reusable instruction/capability units loaded at runtime:

  • Jido.AI.Skill.Loader parses skill files.
  • Jido.AI.Skill.Registry stores and resolves active skills.
  • Skills are strategy-agnostic and can be injected into agent behavior/context.
  • Skills are useful for domain behavior reuse without duplicating agent code.

This is the main packaging mechanism for reusable AI behavior in your system.

Priority 4: Plugins As Capability Mixins

Plugins should represent product capabilities, not low-level runtime plumbing.

Recommended plugin set (target production surface):

  1. Jido.AI.Plugins.Chat (anchor capability)
    • Unified conversational interface with built-in tool calling.
    • Replaces split end-user mental model of separate LLM + ToolCalling plugins.
    • Supports simple chat usage and tool-augmented chat under one contract.
  2. Jido.AI.Plugins.Planning
    • Structured planning, decomposition, and prioritization flows.
  3. Strategy invocation plugins (explicit reasoning as capabilities):
  4. Cross-cutting policy plugins (production hardening):
    • model routing/fallback
    • guardrails and safety policy
    • memory/retrieval enrichment
    • cost/quota/rate limiting

Non-goal for public plugin surface:

  • TaskSupervisor should not be treated as a primary user-facing capability plugin.
  • Async execution infrastructure should be handled by Jido runtime/Jido.Exec primitives and internal runtime wiring.

Where plugins fit:

  • Strategies decide control flow and reasoning mechanics.
  • Plugins package reusable capabilities and policy.
  • Actions remain the executable units behind both plugins and direct workflows.

Signal namespace contract for this plugin surface:

  • chat.message
  • reasoning.cod.run
  • reasoning.cot.run
  • reasoning.aot.run
  • reasoning.tot.run
  • reasoning.got.run
  • reasoning.trm.run
  • reasoning.adaptive.run

Priority 5: Actions As Independent Integration Surface

Standalone actions are the strategy-independent integration path for adding AI behavior directly to Jido apps via Jido.Exec.

Finalized standalone action set (recommended):

  1. Core generation primitives
  2. Tool orchestration primitives
  3. Planning domain templates
  4. Reasoning domain templates (optional, useful outside full strategy orchestration)
  5. Dedicated strategy orchestration
  6. Compatibility convenience

Not part of standalone action surface:

  • Strategy-internal command actions (*_start, *_llm_result, *_llm_partial, worker lifecycle events).
  • These are orchestration internals for ReAct/CoD/CoT/AoT/ToT/GoT/TRM/Adaptive strategies, not reusable app-level primitives.

Pragmatically:

  • Agent macros are the primary production surface for long-lived agent orchestration.
  • Direct actions are the flexible lower-level surface for pipelines, jobs, and custom runtime composition.

Runtime Map (End-To-End)

User/App Query
  -> Agent Macro (Jido.AI.Agent or strategy-specific agent)
  -> Strategy (ReAct/CoD/CoT/AoT/ToT/GoT/TRM/Adaptive)
  -> Directives (LLM, tool, control intents)
  -> Runtime Execution (ReqLLM + tool execution)
  -> Signals (ai.request.*, ai.llm.*, ai.tool.*, ai.usage)
  -> Strategy state updates
  -> Request completion/await result

Observability Guarantees

Observability is a core part of the package, not an add-on:

  • Typed signal contracts for lifecycle, LLM, tool, and usage events
  • Directive-level execution boundaries
  • Telemetry events for request, LLM, and tool phases
  • Request IDs and run IDs for correlation across async boundaries

Production Positioning Summary

When describing jido_ai for production, the concise version is:

  1. A ReAct-first AI agent framework (Jido.AI.Agent) with built-in tool calling.
  2. A multi-strategy reasoning platform (CoD, CoT, AoT, ToT, GoT, TRM, Adaptive, ReAct).
  3. A reusable skills layer for domain behavior packaging.
  4. A plugin layer for mountable capability mixins and policy controls.
  5. A lower-level actions API for strategy-independent AI workflows.
  6. Full runtime observability through directives, signals, and telemetry.

Next