guides/user/package_overview.md

Select File:
guides/user/package_overview.md

# Package Overview (Production Map)

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:

- `Jido.AI.CoDAgent` -> `Jido.AI.Reasoning.ChainOfDraft.Strategy`
- `Jido.AI.CoTAgent` -> `Jido.AI.Reasoning.ChainOfThought.Strategy`
- `Jido.AI.AoTAgent` -> `Jido.AI.Reasoning.AlgorithmOfThoughts.Strategy`
- `Jido.AI.ToTAgent` -> `Jido.AI.Reasoning.TreeOfThoughts.Strategy`
- `Jido.AI.GoTAgent` -> `Jido.AI.Reasoning.GraphOfThoughts.Strategy`
- `Jido.AI.TRMAgent` -> `Jido.AI.Reasoning.TRM.Strategy`
- `Jido.AI.AdaptiveAgent` -> `Jido.AI.Reasoning.Adaptive.Strategy`

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):
   - `Jido.AI.Plugins.Reasoning.ChainOfDraft`
   - `Jido.AI.Plugins.Reasoning.ChainOfThought`
   - `Jido.AI.Plugins.Reasoning.AlgorithmOfThoughts`
   - `Jido.AI.Plugins.Reasoning.TreeOfThoughts`
   - `Jido.AI.Plugins.Reasoning.GraphOfThoughts`
   - `Jido.AI.Plugins.Reasoning.TRM`
   - `Jido.AI.Plugins.Reasoning.Adaptive`
   - These expose reasoning strategies as callable plugin capabilities, independent of which agent macro strategy is primary.
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
   - `Jido.AI.Actions.LLM.Chat` (single-turn conversational generation)
   - `Jido.AI.Actions.LLM.GenerateObject` (schema-constrained structured output)
   - `Jido.AI.Actions.LLM.Embed` (embedding generation for retrieval/search)
2. Tool orchestration primitives
   - `Jido.AI.Actions.ToolCalling.CallWithTools` (LLM + tool schema + optional auto-execution loop)
   - `Jido.AI.Actions.ToolCalling.ExecuteTool` (direct tool execution by name)
   - `Jido.AI.Actions.ToolCalling.ListTools` (tool discovery and schema inspection)
3. Planning domain templates
   - `Jido.AI.Actions.Planning.Plan`
   - `Jido.AI.Actions.Planning.Decompose`
   - `Jido.AI.Actions.Planning.Prioritize`
4. Reasoning domain templates (optional, useful outside full strategy orchestration)
   - `Jido.AI.Actions.Reasoning.Analyze`
   - `Jido.AI.Actions.Reasoning.Infer`
   - `Jido.AI.Actions.Reasoning.Explain`
5. Dedicated strategy orchestration
   - `Jido.AI.Actions.Reasoning.RunStrategy` (isolated strategy execution for `:cod | :cot | :aot | :tot | :got | :trm | :adaptive`)
6. Compatibility convenience
   - `Jido.AI.Actions.LLM.Complete` (simple completion path; overlaps with `Chat` and can remain as 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)

```text
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

- [First Agent](first_react_agent.md)
- [Request Lifecycle And Concurrency](request_lifecycle_and_concurrency.md)
- [Strategy Selection Playbook](strategy_selection_playbook.md)
- [Migration Guide: Plugins And Signals (v2 -> v3)](migration_plugins_and_signals_v3.md)
- [Architecture And Runtime Flow](../developer/architecture_and_runtime_flow.md)