# `Jido.AI.Plugins.Planning`
[🔗](https://github.com/agentjido/jido_ai/blob/v2.4.0/lib/jido_ai/plugins/planning.ex#L6)

A Jido.Plugin providing AI-powered planning capabilities.

This plugin exposes three planning actions:

* `Plan` - Generate structured plans from goals with constraints and resources
* `Decompose` - Break down complex goals into hierarchical sub-goals
* `Prioritize` - Order tasks by priority based on given criteria

## Signal Contracts

- `planning.plan` -> `Jido.AI.Actions.Planning.Plan`
- `planning.decompose` -> `Jido.AI.Actions.Planning.Decompose`
- `planning.prioritize` -> `Jido.AI.Actions.Planning.Prioritize`

## Mount State Defaults

`mount/2` initializes shared defaults consumed by planning actions when caller
params omit those fields:

- `default_model`: `:planning`
- `default_max_tokens`: `4096`
- `default_temperature`: `0.7`

Action-specific inputs remain action-owned:

- `Plan`: `goal` + optional `constraints`, `resources`, `max_steps`
- `Decompose`: `goal` + optional `max_depth`, `context`
- `Prioritize`: `tasks` + optional `criteria`, `context`

## Usage

Attach to an agent:

    defmodule MyAgent do
      use Jido.Agent,

      plugins: [
        {Jido.AI.Plugins.Planning, []}
      ]
    end

Or use the action directly:

    Jido.Exec.run(Jido.AI.Actions.Planning.Plan, %{
      goal: "Build a web application",
      constraints: ["Must use Elixir", "Budget limited"],
      resources: ["2 developers", "3 months"]
    })

## Model Resolution

The plugin uses `Jido.AI.resolve_model/1` to resolve model aliases:

* `:fast` - Quick model for simple tasks
* `:capable` - Capable model for complex tasks
* `:planning` - Model optimized for planning (default: `anthropic:claude-sonnet-4-20250514`)

Direct model specs are also supported.

## Architecture Notes

**Direct ReqLLM Calls**: Planning actions call ReqLLM directly.
**Specialized Prompts**: Each action uses a task-specific system prompt.
**Lightweight State**: Plugin state only stores execution defaults.

# `__plugin_metadata__`

```elixir
@spec __plugin_metadata__() :: map()
```

Returns metadata for Jido.Discovery integration.

This function is used by `Jido.Discovery` to index plugins
for fast lookup and filtering.

# `actions`

```elixir
@spec actions() :: [module()]
```

Returns the list of action modules provided by this plugin.

# `capabilities`

```elixir
@spec capabilities() :: [atom()]
```

Returns the capabilities provided by this plugin.

# `category`

```elixir
@spec category() :: String.t() | nil
```

Returns the plugin's category.

# `config_schema`

```elixir
@spec config_schema() :: Zoi.schema() | nil
```

Returns the Zoi schema for per-agent configuration.

# `description`

```elixir
@spec description() :: String.t() | nil
```

Returns the plugin's description.

# `handle_signal`

```elixir
@spec handle_signal(term(), map()) ::
  {:ok, term()} | {:ok, {:override, term()}} | {:error, term()}
```

Pre-routing hook for incoming signals.

Currently returns :continue to allow normal routing.

# `manifest`

```elixir
@spec manifest() :: Jido.Plugin.Manifest.t()
```

Returns the plugin manifest with all metadata.

The manifest provides compile-time metadata for discovery
and introspection, including capabilities, requirements,
signal routes, and schedules.

# `mount`

```elixir
@spec mount(term(), map()) :: {:ok, map() | nil} | {:error, term()}
```

Initialize plugin state when mounted to an agent.

Returns initial state with any configured defaults.

# `name`

```elixir
@spec name() :: String.t()
```

Returns the plugin's name.

# `otp_app`

```elixir
@spec otp_app() :: atom() | nil
```

Returns the OTP application for config resolution.

# `plugin_spec`

```elixir
@spec plugin_spec(map()) :: Jido.Plugin.Spec.t()
```

Returns the plugin specification with optional per-agent configuration.

## Examples

    spec = MyModule.plugin_spec(%{})
    spec = MyModule.plugin_spec(%{custom_option: true})

# `requires`

```elixir
@spec requires() :: [tuple()]
```

Returns the requirements for this plugin.

# `schedules`

```elixir
@spec schedules() :: [tuple()]
```

Returns the schedules for this plugin.

# `schema`

```elixir
@spec schema() :: Zoi.schema() | nil
```

Returns the schema for plugin state.

Defines the structure and defaults for Planning plugin state.

# `signal_patterns`

```elixir
@spec signal_patterns() :: [String.t()]
```

Returns signal patterns this plugin responds to.

# `signal_routes`

```elixir
@spec signal_routes() :: [tuple()]
```

Returns the signal routes for this plugin.

# `signal_routes`

```elixir
@spec signal_routes(map()) :: [tuple()]
```

Returns the signal router for this plugin.

Maps signal patterns to action modules.

# `singleton?`

```elixir
@spec singleton?() :: boolean()
```

Returns whether this plugin is a singleton.

# `state_key`

```elixir
@spec state_key() :: atom()
```

Returns the key used to store plugin state in the agent.

# `subscriptions`

```elixir
@spec subscriptions() :: [Jido.Plugin.sensor_subscription()]
```

Returns the sensor subscriptions for this plugin.

# `tags`

```elixir
@spec tags() :: [String.t()]
```

Returns the plugin's tags.

# `transform_result`

```elixir
@spec transform_result(module() | String.t(), term(), map()) :: term()
```

Transform the result returned from action execution.

Currently passes through results unchanged.

# `vsn`

```elixir
@spec vsn() :: String.t() | nil
```

Returns the plugin's version.

---

*Consult [api-reference.md](api-reference.md) for complete listing*