igniter 0.5.0 → 0.5.1

data/docs/TRANSCRIPTION_V1.md

@@ -1,403 +0,0 @@
-# Igniter — LLM::Transcriber
-
-`Igniter::LLM::Transcriber` is a first-class Executor for audio-to-text conversion.
-It plugs into the Contract graph exactly like any other compute node, giving you
-caching, dependency resolution, and parallel execution for free.
-
-```
-audio file / URL
-      │
-      ▼
- CallTranscriber          ← LLM::Transcriber subclass
-      │  TranscriptResult
-      │   .text, .words, .speakers, .duration
-      ▼
- CallExtractor            ← LLM::Executor subclass
-      │  Hash (structured JSON)
-      ▼
-  CRM / DB
-```
-
----
-
-## Quick start
-
-```ruby
-require "igniter/integrations/llm"
-
-Igniter::LLM.configure do |c|
-  c.deepgram.api_key = ENV["DEEPGRAM_API_KEY"]
-end
-
-class MyTranscriber < Igniter::LLM::Transcriber
-  transcription_provider :deepgram
-  model "nova-3"
-  language "en"
-  diarize true
-
-  def call(audio_path:) = transcribe(audio_path)
-end
-
-result = MyTranscriber.call(audio_path: "meeting.mp3")
-puts result.text
-puts result.speakers.map { |s| "#{s.speaker}: #{s.text}" }.join("\n")
-```
-
----
-
-## Providers
-
-### OpenAI Whisper / gpt-4o-mini-transcribe
-
-| | |
-|---|---|
-| **Sync** | Yes — single POST, immediate response |
-| **Diarization** | **No** |
-| **Word timestamps** | Yes |
-| **Languages** | 99+ (auto-detect or `language:`) |
-| **Max file size** | 20 MB |
-| **Pricing** | whisper-1: `$0.006/min` · gpt-4o-mini-transcribe: `$0.003/min` |
-
-```ruby
-class CallTranscriber < Igniter::LLM::Transcriber
-  transcription_provider :openai
-  model "gpt-4o-mini-transcribe"   # or "whisper-1"
-  language "en"
-
-  def call(audio_url:) = transcribe(audio_url)
-end
-```
-
-**Extra options:** `prompt:` — context hint to improve spelling/vocabulary accuracy.
-
----
-
-### Deepgram Nova-3
-
-| | |
-|---|---|
-| **Sync** | Yes — binary POST, immediate response |
-| **Diarization** | Yes (`diarize true`) |
-| **Word timestamps** | Yes (always included) |
-| **Languages** | 99+ Nova-3 Multilingual · single-language Nova-3 |
-| **Pricing** | `$0.0077/min` (includes diarization, per-second billing) |
-
-```ruby
-Igniter::LLM.configure do |c|
-  c.deepgram.api_key = ENV["DEEPGRAM_API_KEY"]
-end
-
-class CallTranscriber < Igniter::LLM::Transcriber
-  transcription_provider :deepgram
-  model "nova-3"
-  diarize true
-
-  def call(audio_url:) = transcribe(audio_url)
-end
-```
-
-**Extra options:**
-```ruby
-transcribe(audio_url,
-  sentiment: true,   # per-sentence sentiment scores
-  topics:    true,   # topic detection
-  intents:   true,   # intent recognition
-  summarize: true    # extractive summary
-)
-```
-
-Results accessible via `result.raw["results"]["channels"][0]["alternatives"][0]`.
-
----
-
-### AssemblyAI Universal-2
-
-| | |
-|---|---|
-| **Sync** | **No** — async: upload → submit → poll |
-| **Diarization** | Yes (`diarize true`) |
-| **Word timestamps** | Yes (millisecond precision) |
-| **Languages** | 99+ |
-| **Pricing** | `$0.0025/min` base + `$0.0003/min` speaker labels ≈ `$0.0028/min` |
-| **Free tier** | 333 hr/month |
-
-```ruby
-Igniter::LLM.configure do |c|
-  c.assemblyai.api_key      = ENV["ASSEMBLYAI_API_KEY"]
-  c.assemblyai.poll_interval = 3    # seconds between status checks
-  c.assemblyai.poll_timeout  = 600  # fail-safe timeout in seconds
-end
-
-class CallTranscriber < Igniter::LLM::Transcriber
-  transcription_provider :assemblyai
-  diarize true
-  poll_interval 3
-  poll_timeout  600
-
-  def call(audio_url:) = transcribe(audio_url)
-end
-```
-
-**Extra options:**
-```ruby
-transcribe(audio_url,
-  sentiment_analysis: true,
-  auto_chapters:      true,
-  entity_detection:   true,
-  pii_redact:         [:phone_number, :name, :email],
-  custom_vocabulary:  ["Acme", "thermidor"]
-)
-```
-
----
-
-## Provider comparison
-
-| Need | Recommended |
-|------|-------------|
-| Lowest cost, no speakers | `openai` + `gpt-4o-mini-transcribe` — $0.003/min |
-| Lowest cost WITH speakers | `assemblyai` — $0.0028/min |
-| Fastest response (sync) | `deepgram` — typical < 2 s |
-| Richest features | `assemblyai` — chapters, PII, entity detection |
-| Real-time / WebSocket | `deepgram` — same price as REST |
-
----
-
-## DSL reference
-
-```ruby
-class MyTranscriber < Igniter::LLM::Transcriber
-  # ── Required ──────────────────────────────────────────────────────────
-  transcription_provider :openai   # :openai | :deepgram | :assemblyai
-
-  # ── Optional ──────────────────────────────────────────────────────────
-  model "nova-3"            # defaults: openai→whisper-1, deepgram→nova-3,
-                            #          assemblyai→universal-2
-  language "en"             # BCP-47; nil = auto-detect
-  diarize true              # request speaker labels (not supported by OpenAI)
-  word_timestamps true      # per-word start/end times (default: true)
-
-  # AssemblyAI async polling
-  poll_interval 3           # seconds between poll attempts (default: 2)
-  poll_timeout  600         # max seconds to wait (default: 300)
-
-  def call(**inputs)
-    transcribe(inputs[:audio_url])
-    # or with provider-specific extras:
-    transcribe(inputs[:audio_url], sentiment: true, topics: true)
-  end
-end
-```
-
----
-
-## Result structure
-
-```ruby
-result = MyTranscriber.call(audio_url: "call.mp3")
-
-result.text       # => "Hello, thank you for calling..."
-result.language   # => "en"
-result.duration   # => 243.5   (seconds)
-result.provider   # => :assemblyai
-result.model      # => "universal-2"
-result.raw        # => Hash — original provider response
-
-# Word-level timestamps
-result.words.first
-# => #<TranscriptWord word="Hello" start_time=0.0 end_time=0.4 confidence=0.99 speaker="A">
-
-# Speaker segments (when diarize: true)
-result.speakers
-# => [
-#   #<SpeakerSegment speaker="A" start_time=0.0  end_time=5.1  text="Hello, thank you...">,
-#   #<SpeakerSegment speaker="B" start_time=5.3  end_time=12.4 text="Hi, I need help...">,
-#   ...
-# ]
-```
-
-> **Note:** AssemblyAI uses letter labels (`"A"`, `"B"`, ...).
-> Deepgram uses integers (`0`, `1`, ...).
-> OpenAI has no speaker labels — `speakers` is `nil`.
-
----
-
-## In a Contract graph
-
-Transcriber is a full `Igniter::Executor`. Use it as a `compute:` node
-with `cache_ttl:` to avoid re-transcribing the same audio on retries:
-
-```ruby
-class CallAnalysisPipeline < Igniter::Contract
-  define do
-    input :audio_url
-    input :recorded_at, required: false
-
-    compute :transcript, call: CallTranscriber,
-                         with: :audio_url,
-                         cache_ttl: 86_400   # 24 h — same URL = free
-
-    compute :extraction, call: CallExtractor,
-                         with: %i[transcript recorded_at]
-
-    output :transcript, from: :transcript
-    output :extraction, from: :extraction
-  end
-end
-
-result = CallAnalysisPipeline.call(
-  audio_url:   "https://cdn.callrail.com/recordings/abc123.mp3",
-  recorded_at: call.created_at.iso8601
-)
-result[:transcript]  # => TranscriptResult
-result[:extraction]  # => Hash from LLM analysis
-```
-
----
-
-## Production: call-center CRM (Rails)
-
-See `examples/llm/call_center_analysis.rb` for a complete runnable example.
-
-### Volume / cost estimate (27 000 min/month)
-
-```
-AssemblyAI (transcript + diarization)   ≈  $77/month
-gpt-4o-mini (extraction, 14 000 calls)  ≈   $4/month
-                                         ─────────────
-Total                                    ≈  $81/month
-```
-
-### Rails integration sketch
-
-```ruby
-# app/models/call_recording.rb
-class CallRecording < ApplicationRecord
-  after_create_commit :schedule_analysis, if: :audio_url?
-
-  private
-
-  def schedule_analysis = CallAnalysisJob.perform_later(id)
-end
-
-# app/jobs/call_analysis_job.rb
-class CallAnalysisJob < ApplicationJob
-  queue_as :transcription
-  sidekiq_options retry: 3
-
-  def perform(id)
-    rec    = CallRecording.find(id)
-    result = CallAnalysisPipeline.call(
-      audio_url:   rec.audio_url,
-      recorded_at: rec.created_at.iso8601
-    )
-    t = result[:transcript]
-    e = result[:extraction]
-
-    rec.update!(
-      transcript_text:  t.text,
-      duration_seconds: t.duration,
-      speakers_json:    t.speakers&.map(&:to_h),
-      conversion:       e["conversion"],
-      call_type:        e["call_type"],
-      zip_codes:        e["zip_codes"],
-      addresses:        e["addresses"],
-      phones:           e["phones"],
-      service_names:    e["service_names"],
-      scheduled_at:     e["scheduled_datetime"]&.then { Time.parse(_1) },
-      ai_confidence:    e["confidence"],
-      ai_notes:         e["notes"]
-    )
-  end
-end
-```
-
-### Recommended PostgreSQL columns
-
-```ruby
-add_column :call_recordings, :transcript_text,  :text
-add_column :call_recordings, :duration_seconds, :float
-add_column :call_recordings, :speakers_json,    :jsonb,  default: []
-add_column :call_recordings, :conversion,       :boolean
-add_column :call_recordings, :call_type,        :string
-add_column :call_recordings, :zip_codes,        :string, array: true, default: []
-add_column :call_recordings, :addresses,        :string, array: true, default: []
-add_column :call_recordings, :phones,           :string, array: true, default: []
-add_column :call_recordings, :service_names,    :string, array: true, default: []
-add_column :call_recordings, :scheduled_at,     :datetime
-add_column :call_recordings, :ai_confidence,    :float
-add_column :call_recordings, :ai_notes,         :text
-
-# Useful indexes
-add_index :call_recordings, :conversion
-add_index :call_recordings, :call_type
-add_index :call_recordings, :zip_codes,     using: :gin
-add_index :call_recordings, :service_names, using: :gin
-```
-
----
-
-## Roadmap: Real-time operator assistance (Asterisk)
-
-Once you own the Asterisk PBX, the path to live analysis:
-
-```
-Asterisk RTP stream
-      │  (audio chunks via AGI/AMI)
-      ▼
-Deepgram WebSocket
-      │  partial + final transcript events
-      ▼
-Igniter Actor (CallMonitorAgent)
-      │  detects key events in real-time
-      ▼
-ActionCable → Operator UI
-      │  "ZIP 77001 detected — pull nearby techs"
-      │  "Customer says 'Samsung washer' — show checklist"
-      │  "Sentiment dropping — offer discount code"
-```
-
-**Cost for real-time Deepgram:** same `$0.0077/min` (no surcharge vs REST).
-Total with real-time: ~$212/month vs $81/month batch.
-The premium pays for live operator assistance and reduced handle time.
-
-### Agent sketch
-
-```ruby
-class CallMonitorAgent < Igniter::Agent
-  on :transcript_chunk do |payload|
-    text = payload[:text]
-    next if text.length < 40   # wait for meaningful chunks
-
-    hints = ContextExtractor.call(partial_text: text)
-    next if hints.empty?
-
-    broadcast(:operator_hint,
-      call_id:     payload[:call_id],
-      operator_id: payload[:operator_id],
-      hints:       hints)
-  end
-end
-```
-
----
-
-## Configuration reference
-
-```ruby
-Igniter::LLM.configure do |c|
-  # OpenAI (used by both chat executors and openai transcription provider)
-  c.openai.api_key  = ENV["OPENAI_API_KEY"]
-  c.openai.base_url = "https://api.openai.com"  # override for Azure/proxy
-  c.openai.timeout  = 120
-
-  # Deepgram
-  c.deepgram.api_key = ENV["DEEPGRAM_API_KEY"]
-  c.deepgram.timeout = 300   # pre-recorded audio; allow for large files
-
-  # AssemblyAI
-  c.assemblyai.api_key       = ENV["ASSEMBLYAI_API_KEY"]
-  c.assemblyai.poll_interval = 3    # start polling after N seconds
-  c.assemblyai.poll_timeout  = 600  # raise ProviderError if not done in time
-end
-```

data/lib/igniter/agents.rb

@@ -1,56 +0,0 @@
-# frozen_string_literal: true
-
-# Standard library of ready-made Igniter agents.
-#
-# Usage:
-#   require "igniter/agents"
-#
-# Provides production-grade agents per domain:
-#
-#   Reliability   — Igniter::Agents::RetryAgent
-#   Pipeline      — Igniter::Agents::BatchProcessorAgent
-#   Scheduling    — Igniter::Agents::CronAgent
-#   AI/LLM        — Igniter::Agents::RouterAgent
-#                   Igniter::Agents::CriticAgent
-#                   Igniter::Agents::PlannerAgent
-#                   Igniter::Agents::ChainAgent
-#                   Igniter::Agents::SelfReflectionAgent
-#                   Igniter::Agents::ObserverAgent
-#                   Igniter::Agents::EvaluatorAgent
-#                   Igniter::Agents::EvolutionAgent
-#   Proactive     — Igniter::Agents::ProactiveAgent  (base)
-#                   Igniter::Agents::AlertAgent
-#                   Igniter::Agents::HealthCheckAgent
-#   Observability — Igniter::Agents::MetricsAgent
-#
-require_relative "integrations/agents"
-require_relative "agents/reliability/retry_agent"
-require_relative "agents/pipeline/batch_processor_agent"
-require_relative "agents/scheduling/cron_agent"
-require_relative "agents/ai/router_agent"
-require_relative "agents/ai/critic_agent"
-require_relative "agents/ai/planner_agent"
-require_relative "agents/ai/chain_agent"
-require_relative "agents/ai/self_reflection_agent"
-require_relative "agents/ai/observer_agent"
-require_relative "agents/ai/evaluator_agent"
-require_relative "agents/ai/evolution_agent"
-require_relative "agents/proactive_agent"
-require_relative "agents/ai/alert_agent"
-require_relative "agents/ai/health_check_agent"
-require_relative "agents/observability/metrics_agent"
-
-module Igniter
-  module Agents
-    # Convenience method — list all registered stdlib agents.
-    #
-    # @return [Array<Class>]
-    def self.all
-      [RetryAgent, BatchProcessorAgent, CronAgent,
-       RouterAgent, CriticAgent, PlannerAgent, ChainAgent,
-       SelfReflectionAgent, ObserverAgent, EvaluatorAgent, EvolutionAgent,
-       AlertAgent, HealthCheckAgent,
-       MetricsAgent]
-    end
-  end
-end

data/lib/igniter/application/app_config.rb

@@ -1,32 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  class Application
-    # Unified configuration object for an Igniter::Application.
-    # Wraps server-level settings in a single place.
-    # Call #to_server_config to get a Server::Config for HttpServer / RackApp.
-    class AppConfig
-      attr_accessor :host, :port, :store, :log_format, :drain_timeout, :metrics_collector
-
-      def initialize
-        @host              = "0.0.0.0"
-        @port              = 4567
-        @store             = nil # nil → MemoryStore default inside Server::Config
-        @log_format        = :text
-        @drain_timeout     = 30
-        @metrics_collector = nil
-      end
-
-      def to_server_config
-        Igniter::Server::Config.new.tap do |sc|
-          sc.host              = host
-          sc.port              = port
-          sc.store             = store if store
-          sc.log_format        = log_format
-          sc.drain_timeout     = drain_timeout
-          sc.metrics_collector = metrics_collector
-        end
-      end
-    end
-  end
-end

data/lib/igniter/application/generator.rb

@@ -1,157 +0,0 @@
-# frozen_string_literal: true
-
-require "fileutils"
-
-module Igniter
-  class Application
-    # Generates a new Igniter application scaffold.
-    # Invoked via: igniter-server new my_app
-    #
-    # Creates:
-    #   my_app/
-    #   ├── application.rb     — Application class (entry point)
-    #   ├── application.yml    — base config (port, log_format, etc.)
-    #   ├── Gemfile
-    #   ├── config.ru          — Rack entry point for Puma/Unicorn
-    #   ├── bin/start          — convenience start script
-    #   ├── contracts/         — Contract subclasses
-    #   ├── executors/         — Executor subclasses
-    #   └── agents/            — Agent, Supervisor, and ProactiveAgent subclasses
-    class Generator
-      def initialize(name)
-        @name = name.to_s.strip
-        raise ArgumentError, "App name cannot be blank" if @name.empty?
-
-        @dir = @name
-      end
-
-      def generate # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
-        create_dir ""
-        create_dir "contracts"
-        create_dir "executors"
-        create_dir "agents"
-        create_dir "bin"
-
-        write "application.rb",  application_rb
-        write "application.yml", application_yml
-        write "Gemfile",         gemfile
-        write "config.ru",       config_ru
-        write "bin/start",       bin_start
-        write "contracts/.keep", ""
-        write "executors/.keep", ""
-        write "agents/.keep",    ""
-
-        FileUtils.chmod(0o755, path("bin/start"))
-
-        puts
-        puts "Done! Next steps:"
-        puts "  cd #{@name}"
-        puts "  bundle install"
-        puts "  bin/start"
-        puts
-        puts "To run with Puma:"
-        puts "  bundle add puma"
-        puts "  bundle exec puma config.ru"
-      end
-
-      private
-
-      def path(rel) = File.join(@dir, rel)
-
-      def create_dir(rel)
-        full = rel.empty? ? @dir : path(rel)
-        FileUtils.mkdir_p(full)
-        puts "  create  #{full}/"
-      end
-
-      def write(rel, content)
-        full = path(rel)
-        File.write(full, content)
-        puts "  create  #{full}"
-      end
-
-      def module_name
-        @name.split(/[-_\s]+/).map(&:capitalize).join
-      end
-
-      def application_rb
-        <<~RUBY
-          # frozen_string_literal: true
-
-          $LOAD_PATH.unshift(File.join(__dir__, "../../lib")) if File.exist?("../../lib/igniter.rb")
-
-          require "igniter"
-          require "igniter/server"
-          require "igniter/application"
-          require "igniter/agents"
-
-          class #{module_name}App < Igniter::Application
-            config_file File.join(__dir__, "application.yml")
-
-            # Eagerly load all .rb files from these directories on startup.
-            executors_path "executors"
-            contracts_path "contracts"
-            agents_path    "agents"
-
-            configure do |c|
-              # Override YAML values here, e.g.:
-              # c.port  = ENV.fetch("PORT", 4567).to_i
-              # c.store = Igniter::Runtime::Stores::MemoryStore.new
-            end
-
-            # Register contracts for HTTP dispatch:
-            # register "MyContract", MyContract
-
-            # Recurring background jobs:
-            # schedule :heartbeat, every: "30s" do
-            #   puts "[heartbeat] \#{Time.now.strftime("%H:%M:%S")}"
-            # end
-          end
-
-          #{module_name}App.start if $PROGRAM_NAME == __FILE__
-        RUBY
-      end
-
-      def application_yml
-        <<~YAML
-          server:
-            port: 4567
-            host: "0.0.0.0"
-            log_format: text   # text | json  (json = Loki/ELK compatible)
-            drain_timeout: 30  # seconds to wait for in-flight requests on shutdown
-        YAML
-      end
-
-      def gemfile
-        <<~RUBY
-          # frozen_string_literal: true
-
-          source "https://rubygems.org"
-
-          gem "igniter"
-        RUBY
-      end
-
-      def config_ru
-        <<~RUBY
-          # frozen_string_literal: true
-          # Rack entry point — use with Puma or any Rack-compatible server.
-          #   bundle exec puma config.ru
-
-          require_relative "application"
-
-          run #{module_name}App.rack_app
-        RUBY
-      end
-
-      def bin_start
-        <<~BASH
-          #!/usr/bin/env bash
-          set -e
-          cd "$(dirname "$0")/.."
-          exec bundle exec ruby application.rb "$@"
-        BASH
-      end
-    end
-  end
-end

data/lib/igniter/application/yml_loader.rb

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-require "yaml"
-
-module Igniter
-  class Application
-    # Loads an application.yml and applies values to an AppConfig.
-    # YAML is loaded BEFORE the Ruby configure block, so blocks always win.
-    #
-    # Supported YAML structure:
-    #   server:
-    #     port: 4567
-    #     host: "0.0.0.0"
-    #     log_format: json        # "text" or "json"
-    #     drain_timeout: 30
-    class YmlLoader
-      # Maps [section, key] paths in YAML to AppConfig setters.
-      MAPPINGS = {
-        %w[server port] => ->(cfg, v) { cfg.port = Integer(v) },
-        %w[server host] => ->(cfg, v) { cfg.host = v.to_s },
-        %w[server log_format] => ->(cfg, v) { cfg.log_format = v.to_sym },
-        %w[server drain_timeout] => ->(cfg, v) { cfg.drain_timeout = Integer(v) }
-      }.freeze
-
-      def self.load(path)
-        return {} unless File.exist?(path.to_s)
-
-        YAML.safe_load(File.read(path)) || {}
-      end
-
-      def self.apply(config, yml)
-        MAPPINGS.each do |keys, setter|
-          value = yml.dig(*keys)
-          setter.call(config, value) unless value.nil?
-        end
-      end
-    end
-  end
-end