jido_ai

# Jido.AI

[![Hex.pm](https://img.shields.io/hexpm/v/jido_ai.svg)](https://hex.pm/packages/jido_ai)
[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/jido_ai/)
[![CI](https://github.com/agentjido/jido_ai/actions/workflows/ci.yml/badge.svg)](https://github.com/agentjido/jido_ai/actions/workflows/ci.yml)
[![License](https://img.shields.io/hexpm/l/jido_ai.svg)](https://github.com/agentjido/jido_ai/blob/main/LICENSE)
[![Website](https://img.shields.io/badge/website-jido.run-0f172a.svg)](https://jido.run)
[![Ecosystem](https://img.shields.io/badge/ecosystem-jido.run-0ea5e9.svg)](https://jido.run/ecosystem)
[![Discord](https://img.shields.io/badge/discord-join-5865F2.svg?logo=discord&logoColor=white)](https://jido.run/discord)

Build tool-using Elixir agents with explicit reasoning strategies and production-ready request orchestration.

[Hex](https://hex.pm/packages/jido_ai) | [HexDocs](https://hexdocs.pm/jido_ai) | [Jido Ecosystem](https://jido.run/ecosystem) | [Discord](https://jido.run/discord)

`jido_ai` is the AI runtime layer for Jido. You define tools and agents as Elixir modules, then run synchronous or asynchronous requests with built-in model routing, retries, and observability.

```elixir
defmodule MyApp.Actions.AddNumbers do
  use Jido.Action,
    name: "add_numbers",
    schema: Zoi.object(%{a: Zoi.integer(), b: Zoi.integer()}),
    description: "Add two numbers."

  @impl true
  def run(%{a: a, b: b}, _context), do: {:ok, %{sum: a + b}}
end

defmodule MyApp.MathAgent do
  use Jido.AI.Agent,
    name: "math_agent",
    model: :fast,
    tools: [MyApp.Actions.AddNumbers],
    system_prompt: "Solve accurately. Use tools for arithmetic."
end

{:ok, pid} = Jido.AgentServer.start(agent: MyApp.MathAgent)
{:ok, answer} = MyApp.MathAgent.ask_sync(pid, "What is 19 + 23?")
```

## Where This Package Fits

`jido_ai` is a **core package** in the Jido ecosystem:

- [jido](https://hex.pm/packages/jido): agent runtime, process model, and signal lifecycle
- [jido_action](https://hex.pm/packages/jido_action): typed tool/action contract used by `jido_ai`
- [req_llm](https://hex.pm/packages/req_llm): provider abstraction for Anthropic, OpenAI, Google, and others

Use `jido_ai` when you need long-lived agents, tool-calling loops, or explicit reasoning strategies. You can also use it without a running agent process via `Jido.AI.generate_text/2`, `Jido.AI.ask/2`, or `Jido.Exec.run/3` with any action module.
For cross-package tutorials and the package map, see [jido.run/ecosystem](https://jido.run/ecosystem).

In `jido_ai`, tool actions are allowed to be effectful. They often perform HTTP, LLM, database, or file I/O because the model needs the result back in the same ReAct loop.

The purity boundary lives around agent strategy decisions and runtime orchestration, not necessarily inside each tool action. Use a tool action when the next reasoning step needs the result now. Use directives, signals, or runtime integrations when an outbound effect has already been decided and the runtime should own delivery, retry, and observability.

## Installation

### Igniter Installation (Recommended)

The fastest way to get started is with [Igniter](https://hex.pm/packages/igniter):

```bash
mix igniter.install jido_ai
```

This automatically:
- Adds `jido_ai` to your dependencies
- Configures default model aliases
- Reminds you to set up API keys

### Manual Installation

Add `jido_ai` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:jido, "~> 2.0"},
    {:jido_ai, "~> 2.0.0-rc.0"}
  ]
end
```

```bash
mix deps.get
```

Configure model aliases and at least one provider credential:

```elixir
# config/config.exs
config :jido_ai,
  model_aliases: %{
    fast: "provider:fast-model",
    capable: "provider:capable-model"
  }

config :req_llm,
  anthropic_api_key: System.get_env("ANTHROPIC_API_KEY"),
  openai_api_key: System.get_env("OPENAI_API_KEY")
```

## Quick Start

1. Define one `Jido.Action` tool.
2. Define one `Jido.AI.Agent` with that tool.
3. Start the agent and call `ask_sync/3` or `ask/3` + `await/2`.

```elixir
defmodule MyApp.Actions.Multiply do
  use Jido.Action,
    name: "multiply",
    schema: Zoi.object(%{a: Zoi.integer(), b: Zoi.integer()})

  @impl true
  def run(%{a: a, b: b}, _context), do: {:ok, %{product: a * b}}
end

defmodule MyApp.Agent do
  use Jido.AI.Agent,
    name: "my_agent",
    model: :fast,
    tools: [MyApp.Actions.Multiply]
end

{:ok, pid} = Jido.AgentServer.start(agent: MyApp.Agent)

# Sync convenience path
{:ok, result} = MyApp.Agent.ask_sync(pid, "What is 15 * 23?")

# Async path with explicit request handle
{:ok, request} = MyApp.Agent.ask(pid, "What is 144 * 12?")
{:ok, result2} = MyApp.Agent.await(request, timeout: 15_000)
```

## Request-Scoped ReAct Controls

`ask/3` and `ask_sync/3` can narrow or override the active tool registry for a single run:

```elixir
{:ok, result} =
  MyApp.Agent.ask_sync(pid, "Multiply 15 by 23",
    allowed_tools: ["multiply"],
    tool_context: %{tenant_id: "acme"},
    llm_opts: [reasoning_effort: :medium]
  )
```

- `allowed_tools:` filters the agent's configured tools by name for one request.
- `tools:` replaces the tool registry for one request.
- `request_transformer:` lets you reshape each LLM turn, including dynamic tool gating and structured-output schemas.

After a ReAct run, `snapshot.result` is the final assistant answer. Completed
tool outputs are available separately through
`snapshot.details[:tool_results]`, so callers do not need to parse conversation
messages or request traces to recover structured tool data.

For retrieval or classification flows, prefer having tools write `StateOp.SetState` updates and let a `request_transformer` read `context[:state]` to constrain the next turn. That keeps tool exposure, runtime state, and output schemas aligned without scraping message history. See [Standalone ReAct Runtime](guides/user/standalone_react_runtime.md) for the pattern.

Need one-shot text generation without an agent process?

```elixir
{:ok, text} = Jido.AI.ask("Summarize Phoenix PubSub in one paragraph.", model: :fast)
```

## Choose Your Integration Surface

| If you need | Use | Why |
|---|---|---|
| Tool-using agent loops | `Jido.AI.Agent` | ReAct strategy with request tracking and tool orchestration |
| Fixed reasoning strategy | `Jido.AI.CoDAgent`, `Jido.AI.CoTAgent`, `Jido.AI.AoTAgent`, `Jido.AI.ToTAgent`, `Jido.AI.GoTAgent`, `Jido.AI.TRMAgent`, `Jido.AI.AdaptiveAgent` | Strategy-specific control over reasoning behavior |
| AI inside existing workflows/jobs | `Jido.AI.Actions.*` | Run via `Jido.Exec.run/3` without defining an agent module |
| Streaming + checkpoint/resume | `Jido.AI.Reasoning.ReAct` | Standalone ReAct runtime with event streams and checkpoint tokens |
| Thin model facade helpers | `Jido.AI.generate_text/2`, `generate_object/3`, `stream_text/2`, `ask/2` | Fast path for direct LLM calls with alias/default support |

## Strategy Quick Pick

- **ReAct (`Jido.AI.Agent`)**: default for tool/API calls.
- **CoD (`Jido.AI.CoDAgent`)**: concise reasoning with lower latency/cost.
- **Chain-of-Thought (CoT) (`Jido.AI.CoTAgent`)**: asks the model to reason through a problem in explicit intermediate steps before the final answer; useful for math, logic, and other multi-step tasks.
- **AoT (`Jido.AI.AoTAgent`)**: one-pass algorithmic exploration with explicit final answer extraction.
- **ToT / GoT (`Jido.AI.ToTAgent`, `Jido.AI.GoTAgent`)**: branching or graph-style exploration for complex tasks.
- **TRM (`Jido.AI.TRMAgent`)**: iterative recursive refinement.
- **Adaptive (`Jido.AI.AdaptiveAgent`)**: mixed workloads where strategy selection varies per task.

Full tradeoff matrix: [Strategy Selection Playbook](guides/user/strategy_selection_playbook.md)

## Common First-Run Errors

**`Unknown model alias: :my_model`**
- Add the alias under `config :jido_ai, model_aliases: ...`
- Or pass a direct model string (for example `"provider:exact-model-id"`)

**`{:error, :not_a_tool}` when registering or calling tools**
- Ensure your tool module implements `name/0`, `schema/0`, and `run/2`
- Validate with `Jido.AI.register_tool(pid, MyToolModule)`

## Documentation

- [HexDocs](https://hexdocs.pm/jido_ai) — Full API reference and guides
- [Jido Ecosystem](https://jido.run/ecosystem) — Ecosystem overview and cross-package tutorials
- [Discord](https://jido.run/discord) — Community discussion

### Documentation Map

Start here:
- [Package Overview](guides/user/package_overview.md)
- [Getting Started](guides/user/getting_started.md)
- [First Agent](guides/user/first_react_agent.md)

Strategy guides:
- [Strategy Selection Playbook](guides/user/strategy_selection_playbook.md)
- [Strategy Recipes](guides/user/strategy_recipes.md)
- [Model Routing And Policy](guides/user/model_routing_and_policy.md)

Integration and runtime guides:
- [LLM Facade Quickstart](guides/user/llm_facade_quickstart.md)
- [Tool Calling With Actions](guides/user/tool_calling_with_actions.md)
- [Context And Message Projection](guides/user/thread_context_and_message_projection.md)
- [Turn And Tool Results](guides/user/turn_and_tool_results.md)
- [Request Lifecycle And Concurrency](guides/user/request_lifecycle_and_concurrency.md)
- [Retrieval And Quota](guides/user/retrieval_and_quota.md)
- [Observability Basics](guides/user/observability_basics.md)
- [Standalone ReAct Runtime](guides/user/standalone_react_runtime.md)
- [CLI Workflows](guides/user/cli_workflows.md)

Upgrading:
- [Migration: Plugins And Signals v3](guides/user/migration_plugins_and_signals_v3.md)

Deep reference:
- [Actions Catalog](guides/developer/actions_catalog.md)
- [Configuration Reference](guides/developer/configuration_reference.md)
- [Architecture And Runtime Flow](guides/developer/architecture_and_runtime_flow.md)
- [Thread-Context Projection Model](guides/developer/thread_context_projection_model.md)
- [HexDocs](https://hexdocs.pm/jido_ai)

## Runnable Examples

The runnable demos now live in the top-level [`examples/`](https://github.com/agentjido/jido_ai/tree/main/examples)
folder and are loaded on demand, so they stay out of the core `jido_ai` compile path.

```bash
mix run examples/scripts/demo/actions_llm_runtime_demo.exs
mix run examples/scripts/demo/actions_tool_calling_runtime_demo.exs
mix run examples/scripts/demo/actions_reasoning_runtime_demo.exs
mix run examples/scripts/demo/weather_multi_turn_context_demo.exs
```

Additional examples:
- [`examples/lib/agents/weather_agent.ex`](https://github.com/agentjido/jido_ai/blob/main/examples/lib/agents/weather_agent.ex)
- [`examples/lib/agents/react_demo_agent.ex`](https://github.com/agentjido/jido_ai/blob/main/examples/lib/agents/react_demo_agent.ex)
- [`examples/lib/tools/weather_by_location.ex`](https://github.com/agentjido/jido_ai/blob/main/examples/lib/tools/weather_by_location.ex)

## Why Jido.AI

- ReAct-first agent runtime with explicit request handles — `ask/await` prevents concurrent result overwrites
- Eight built-in reasoning strategy families (ReAct, CoD, CoT, AoT, ToT, GoT, TRM, Adaptive)
- Unified tool contract via `Jido.Action` modules with compile-time safety
- Strategy-independent `Actions` API for direct integration with `Jido.Exec`
- Stable telemetry event names via `Jido.AI.Observe` for production dashboards
- Policy and quota plugins rewrite unsafe or over-budget requests deterministically

## Contributing

See [CONTRIBUTING.md](https://github.com/agentjido/jido_ai/blob/main/CONTRIBUTING.md).

## License

Apache-2.0. See [LICENSE.md](LICENSE.md).