igniter 0.5.0 → 0.5.2

data/docs/SKILLS_V1.md

@@ -1,213 +0,0 @@
-# Igniter Skills — V1
-
-## Overview
-
-`Igniter::Skill` is a composable unit of agent capability — the bridge between
-atomic Tools and full autonomous Agents.
-
-| | Tool | Skill | Agent |
-|---|---|---|---|
-| **Purpose** | Single operation | Multi-step task | Long-running process |
-| **LLM inside** | No | Yes (own loop) | Yes (own loop + mailbox) |
-| **Discoverable** | ✓ | ✓ | — |
-| **Capability guard** | ✓ | ✓ | — |
-| **Registered in ToolRegistry** | ✓ | ✓ | — |
-| **Used in `tools` DSL** | ✓ | ✓ | — |
-| **Duration** | ms | s–min | unbounded |
-
-## Key Insight
-
-From the **parent agent's perspective**, a Skill looks identical to a Tool:
-it has a `name`, `description`, parameter schema, and a `call_with_capability_check!`
-interface. The parent LLM cannot tell the difference. This enables **hierarchical agents**
-where each level delegates to the next.
-
-```
-ChatExecutor (parent)
-  tools: [TimeTool, WeatherTool, ResearchSkill, WriteCodeSkill]
-                                      │
-                              ResearchSkill (sub-agent)
-                                tools: [SearchWebTool, ReadUrlTool]
-                                Runs own LLM + tool loop internally
-```
-
-## Defining a Skill
-
-```ruby
-class ResearchSkill < Igniter::Skill
-  # ── Discovery interface (same as Tool) ──
-  description "Research a topic by searching and synthesizing multiple sources"
-
-  param :topic, type: :string, required: true,
-                desc: "The subject to research"
-  param :depth, type: :string, required: false, default: "brief",
-                desc: "brief | detailed"
-
-  requires_capability :network
-
-  # ── Agentic implementation (LLM::Executor DSL) ──
-  provider :anthropic
-  model "claude-sonnet-4-6"
-  system_prompt "You are a research assistant. Be concise and accurate."
-
-  tools SearchWebTool, ReadUrlTool    # skill's own sub-tools
-  max_tool_iterations 8
-
-  def call(topic:, depth: "brief")
-    instruction = depth == "detailed" ? "comprehensive" : "concise 2-3 sentence"
-    complete("Research this and return a #{instruction} summary: #{topic}")
-  end
-end
-```
-
-## Hierarchy Example: ChatExecutor with Skills
-
-```ruby
-class ChatExecutor < Igniter::LLM::Executor
-  provider :ollama
-  model "llama3.1:8b"
-  capabilities :network, :storage     # controls which tools/skills may run
-
-  tools TimeTool,         # instant lookup, no LLM needed
-        WeatherTool,      # instant lookup, no LLM needed
-        SaveNoteTool,     # atomic storage write
-        GetNotesTool,     # atomic storage read
-        ResearchSkill,    # → triggers its own LLM loop when called
-        RemindMeSkill     # → triggers its own LLM loop when called
-
-  max_tool_iterations 6
-
-  def call(message:, conversation_history:, intent:)
-    ctx = build_context(conversation_history, intent)
-    complete(message, context: ctx)
-    # The auto loop transparently selects the right tool or skill per turn.
-    # When ResearchSkill is called, it runs its own sub-loop before returning.
-  end
-end
-```
-
-## Schema Generation
-
-Skills and Tools produce identical schema formats — providers cannot tell them apart.
-
-```ruby
-ResearchSkill.tool_name      # => "research_skill"
-ResearchSkill.to_schema      # => { name:, description:, parameters: {...} }
-ResearchSkill.to_schema(:anthropic)  # => { name:, description:, input_schema: {...} }
-ResearchSkill.to_schema(:openai)     # => { type: "function", function: {...} }
-```
-
-## ToolRegistry
-
-Skills register the same way as Tools:
-
-```ruby
-Igniter::ToolRegistry.register(
-  TimeTool, WeatherTool,    # tools
-  ResearchSkill,            # skill — registered exactly like a tool
-)
-
-Igniter::ToolRegistry.tools_for(capabilities: [:network])
-# => [WeatherTool, ResearchSkill]  (TimeTool has no cap requirement → always included)
-
-Igniter::ToolRegistry.schemas(:anthropic, capabilities: [:network, :storage])
-```
-
-## Capability Guard
-
-Same `call_with_capability_check!` interface as Tool. `CapabilityError` is the same class:
-
-```ruby
-Igniter::Skill::CapabilityError == Igniter::Tool::CapabilityError  # => true
-
-skill = ResearchSkill.new
-skill.call_with_capability_check!(allowed_capabilities: [], topic: "AI")
-# => raises Igniter::Tool::CapabilityError: "research_skill" requires [:network]
-```
-
-## Inheritance
-
-A Skill inherits BOTH the Discoverable DSL AND the LLM::Executor config:
-
-```ruby
-class BaseResearcher < Igniter::Skill
-  provider :anthropic
-  model "claude-sonnet-4-6"
-  requires_capability :network
-end
-
-class DeepResearchSkill < BaseResearcher
-  description "Exhaustive multi-source research with citations"
-  param :topic, type: :string, required: true, desc: "Topic"
-  max_tool_iterations 20
-  # inherits provider, model, requires_capability from BaseResearcher
-end
-```
-
-## Tool::Discoverable
-
-Both `Tool` and `Skill` include `Igniter::Tool::Discoverable`, which provides:
-
-| Method | Description |
-|--------|-------------|
-| `.description(text)` | Set LLM-facing description |
-| `.param(name, type:, ...)` | Declare a parameter |
-| `.requires_capability(*caps)` | Declare required capabilities |
-| `.tool_name` | Auto-derived snake_case name |
-| `.to_schema(provider)` | Generate LLM tool schema |
-| `.tool_params` | Array of declared params |
-| `.required_capabilities` | Array of required caps |
-| `#call_with_capability_check!(...)` | Guard + invoke `#call` |
-
-## When to Use Tool vs Skill vs Agent
-
-**Use a Tool when:**
-- Operation is atomic and deterministic
-- No LLM reasoning needed internally
-- Response comes back in milliseconds
-- Examples: `TimeTool`, `SaveNoteTool`, `WebhookTool`
-
-**Use a Skill when:**
-- Task requires multi-step reasoning or tool orchestration
-- Output benefits from LLM synthesis (not just data retrieval)
-- Task runs in seconds (not unbounded)
-- Parent agent should treat it as a single callable unit
-- Examples: `ResearchSkill`, `RemindMeSkill`, `WriteCodeSkill`, `TranslateDocumentSkill`
-
-**Use an Agent when:**
-- Long-running process with its own lifecycle (mailbox, supervisor)
-- Needs to handle events asynchronously
-- Maintains complex persistent state
-- Examples: monitoring agent, background indexer, event-driven workflow
-
-## Companion Example
-
-The Companion voice assistant uses both tools and skills:
-
-```
-ChatExecutor
-├── TimeTool        [tool]  → "what time is it?"
-├── WeatherTool     [tool]  → "weather in Moscow?"
-├── SaveNoteTool    [tool]  → persist a note
-├── GetNotesTool    [tool]  → recall a note
-├── ResearchSkill   [skill] → "explain how Raft consensus works"
-└── RemindMeSkill   [skill] → "remind me to call Alice tomorrow at 3pm"
-```
-
-Skills in Companion:
-- `ResearchSkill` — keyword search + LLM synthesis (uses `SaveNoteTool` to persist findings)
-- `RemindMeSkill` — NL parsing + structured save (uses `TimeTool` + `SaveNoteTool`)
-  When Consensus cluster is active, notes survive node failures automatically.
-
-## Key Files
-
-| File | Description |
-|------|-------------|
-| `lib/igniter/skill.rb` | Skill base class |
-| `lib/igniter/tool/discoverable.rb` | Shared DSL (Tool + Skill) |
-| `lib/igniter/tool.rb` | Tool base class |
-| `lib/igniter/tool_registry.rb` | Registry for Tool + Skill |
-| `spec/igniter/skill_spec.rb` | 30+ examples |
-| `examples/companion/skills/research_skill.rb` | ResearchSkill demo |
-| `examples/companion/skills/remind_me_skill.rb` | RemindMeSkill demo |
-| `docs/TOOLS_V1.md` | Tool system docs |

data/docs/STORE_ADAPTERS.md

@@ -1,154 +0,0 @@
-# Store Adapters
-
-Igniter ships with reference execution stores for:
-
-- memory
-- file
-- ActiveRecord-style persistence
-- Redis-style persistence
-
-All stores implement the same protocol:
-
-| Method | Description |
-|--------|-------------|
-| `save(snapshot, correlation: nil, graph: nil)` | Persist a snapshot; build secondary indexes for query |
-| `fetch(execution_id)` | Load a snapshot by ID; raises on missing |
-| `delete(execution_id)` | Remove a snapshot and clean up indexes |
-| `exist?(execution_id)` | Check existence without raising |
-| `find_by_correlation(graph:, correlation:)` | Find execution_id by correlation hash |
-| `list_all(graph: nil)` | All execution_ids, optionally filtered by graph name |
-| `list_pending(graph: nil)` | Execution_ids that have at least one node in `:pending` state |
-
-## Memory Store
-
-Useful for tests and single-process flows.
-
-```ruby
-Igniter.execution_store = Igniter::Runtime::Stores::MemoryStore.new
-```
-
-## File Store
-
-Useful for local development and smoke-testing worker flows.
-
-```ruby
-Igniter.execution_store = Igniter::Runtime::Stores::FileStore.new(
-  root: Rails.root.join("tmp/igniter_executions")
-)
-```
-
-## ActiveRecord Store
-
-Expected record shape:
-
-- one unique `execution_id` column
-- one text/json column for serialized snapshot payload
-
-Example model:
-
-```ruby
-class IgniterExecutionSnapshot < ApplicationRecord
-  validates :execution_id, presence: true, uniqueness: true
-end
-```
-
-Example migration:
-
-```ruby
-class CreateIgniterExecutionSnapshots < ActiveRecord::Migration[7.1]
-  def change
-    create_table :igniter_execution_snapshots do |t|
-      t.string :execution_id, null: false
-      t.jsonb :snapshot_json, null: false, default: {}
-      t.timestamps
-    end
-
-    add_index :igniter_execution_snapshots, :execution_id, unique: true
-  end
-end
-```
-
-Store configuration:
-
-```ruby
-Igniter.execution_store = Igniter::Runtime::Stores::ActiveRecordStore.new(
-  record_class: IgniterExecutionSnapshot,
-  execution_id_column: :execution_id,
-  snapshot_column: :snapshot_json
-)
-```
-
-## Redis Store
-
-`RedisStore` maintains secondary indexes so it can answer all query API calls efficiently:
-
-| Key pattern | Redis type | Purpose |
-|-------------|-----------|---------|
-| `{ns}:{execution_id}` | String | Serialized snapshot JSON |
-| `{ns}:all` | Set | All execution IDs |
-| `{ns}:graph:{name}` | Set | Execution IDs for one graph |
-| `{ns}:corr:{graph}` | Hash | `JSON(sorted_correlation)` → execution_id |
-
-The client must support these Redis commands:
-`set`, `get`, `del`, `exists?`, `sadd`, `srem`, `smembers`, `hset`, `hget`.
-
-The standard [`redis` gem](https://github.com/redis/redis-rb) satisfies this interface.
-
-```ruby
-redis = Redis.new(url: ENV.fetch("REDIS_URL"))
-
-Igniter.execution_store = Igniter::Runtime::Stores::RedisStore.new(
-  redis: redis,
-  namespace: "igniter:executions"   # optional, default shown
-)
-```
-
-**Query API:**
-
-```ruby
-store = Igniter::Runtime::Stores::RedisStore.new(redis: redis)
-
-# Find a pending execution by correlation
-execution_id = store.find_by_correlation(
-  graph: "OrderContract",
-  correlation: { order_id: "o-42" }
-)
-
-# List all executions for a graph
-ids = store.list_all(graph: "OrderContract")
-
-# List only pending executions (O(n) scan — acceptable for moderate volumes)
-pending_ids = store.list_pending(graph: "OrderContract")
-```
-
-## Worker Flow
-
-Store-backed contracts should declare:
-
-```ruby
-class AsyncPricingContract < Igniter::Contract
-  run_with runner: :store
-end
-```
-
-Producer side:
-
-```ruby
-contract = AsyncPricingContract.new(order_total: 100)
-deferred = contract.result.gross_total
-
-execution_id = contract.execution.events.execution_id
-token = deferred.token
-```
-
-Worker side:
-
-```ruby
-AsyncPricingContract.resume_from_store(
-  execution_id,
-  token: token,
-  value: 150
-)
-```
-
-If the resumed execution finishes successfully, the current `StoreRunner` deletes the persisted snapshot automatically.

data/docs/TEMPORAL_V1.md

@@ -1,174 +0,0 @@
-# Temporal Contracts — v1
-
-Temporal contracts make time an explicit, first-class input so that every execution is
-fully reproducible. By supplying the original timestamp you can replay any historical
-computation and get the identical result — even months later.
-
-## Quick Start
-
-```ruby
-require "igniter/temporal"
-
-class TaxRateContract < Igniter::Contract
-  include Igniter::Temporal
-
-  define do
-    input :country
-
-    # `as_of` is injected automatically (default: Time.now)
-    temporal_compute :rate, depends_on: :country do |country:, as_of:|
-      HISTORICAL_RATES.dig(country, as_of.year) || 0.0
-    end
-
-    output :rate
-  end
-end
-
-# Current rate — as_of defaults to Time.now
-TaxRateContract.new(country: "UA").result.rate
-# => 0.22
-
-# Reproduce the 2024 rate exactly
-TaxRateContract.new(country: "UA", as_of: Time.new(2024, 1, 1)).result.rate
-# => 0.20
-```
-
-## How It Works
-
-Including `Igniter::Temporal` overrides `define` to inject one extra input before the
-user block runs:
-
-```ruby
-input :as_of, default: -> { Time.now }
-```
-
-The default is a Proc so it is called freshly at execution time — no stale timestamps
-if the contract class is reused across requests.
-
-`temporal_compute` is a DSL helper that behaves identically to `compute` but automatically
-appends `:as_of` to the `depends_on` list.
-
-## Module Inclusion
-
-```ruby
-class MyContract < Igniter::Contract
-  include Igniter::Temporal
-  # ...
-end
-
-MyContract.temporal?  # => true
-```
-
-Plain contracts without the mixin return `false` from `respond_to?(:temporal?)`.
-
-## `as_of` Input
-
-The injected input behaves like any other input:
-
-- **Default**: `-> { Time.now }` — evaluated at execution time.
-- **Override**: pass `as_of:` when constructing the contract.
-- **Type**: any `Time`-like object is accepted (no type constraint).
-
-```ruby
-# Explicit as_of
-contract = TaxRateContract.new(country: "UA", as_of: Time.new(2024, 6, 1))
-contract.result.rate  # => 0.20 (2024 rate)
-
-# Default as_of — Time.now
-contract = TaxRateContract.new(country: "UA")
-contract.result.rate  # => current rate
-```
-
-## `temporal_compute` DSL
-
-`temporal_compute` is equivalent to:
-
-```ruby
-compute :name, depends_on: [:original_deps..., :as_of], ...
-```
-
-The block receives `as_of:` as a keyword argument alongside the declared dependencies:
-
-```ruby
-temporal_compute :result, depends_on: [:amount, :country] do |amount:, country:, as_of:|
-  # as_of is available automatically
-  rate = RateTable.lookup(country: country, year: as_of.year)
-  amount * rate
-end
-```
-
-You can also mix `temporal_compute` with regular `compute` in the same contract —
-only the nodes that need time-awareness need to use `temporal_compute`.
-
-## Class-Based Executors
-
-For class-based compute nodes in temporal contracts, inherit from
-`Igniter::Temporal::Executor`. This signals intent and ensures `as_of:` is always
-passed as a keyword argument:
-
-```ruby
-class TaxRateExecutor < Igniter::Temporal::Executor
-  def call(country:, as_of:)
-    HISTORICAL_RATES.dig(country, as_of.year) || 0.0
-  end
-end
-
-class TaxRateContract < Igniter::Contract
-  include Igniter::Temporal
-
-  define do
-    input :country
-    temporal_compute :rate, depends_on: :country, call: TaxRateExecutor
-    output :rate
-  end
-end
-```
-
-`Igniter::Temporal::Executor` is a plain subclass of `Igniter::Executor` — it imposes
-no additional behaviour, it is purely documentary.
-
-## Reproducibility Pattern
-
-The key property of temporal contracts: given the same inputs **and** the same `as_of`,
-the output is always identical. Store the `as_of` alongside your results and you can
-replay any historical computation:
-
-```ruby
-# At billing time
-result     = InvoiceContract.new(customer_id: "c1").result
-as_of_used = result.states[:as_of].value   # the Time.now captured during execution
-invoice_id = persist(result, as_of: as_of_used)
-
-# Audit replay 6 months later
-audit = InvoiceContract.new(customer_id: "c1", as_of: as_of_used).result
-audit.total == result.total  # => true
-```
-
-## Combining with Other Extensions
-
-Temporal contracts compose with every other Igniter feature:
-
-```ruby
-require "igniter/temporal"
-require "igniter/extensions/content_addressing"
-
-class TaxCalculator < Igniter::Temporal::Executor
-  pure                          # content-addressed — same country+as_of → cached result
-  fingerprint "tax_v2"
-
-  def call(country:, as_of:)
-    HISTORICAL_RATES.dig(country, as_of.year) || 0.0
-  end
-end
-```
-
-When combined with [content addressing](CONTENT_ADDRESSING_V1.md), the `as_of` value
-is part of the content key, so the cache is invalidated automatically when time changes.
-
-## Files
-
-| File | Purpose |
-|------|---------|
-| `lib/igniter/temporal.rb` | `Temporal` module, `ClassMethods#define`, `temporal_compute` DSL helper, `Temporal::Executor` base class |
-| `lib/igniter/runtime/input_validator.rb` | Proc defaults called at execution time (`apply_defaults`, `missing_value!`) |
-| `spec/igniter/temporal_spec.rb` | 13 examples |