RubyGems - igniter - Versions diffs - 0.5.0 → 0.5.2 - Mend

igniter 0.5.0 → 0.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (840) hide show

data/docs/TRANSCRIPTION_V1.md DELETED Viewed

@@ -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/examples/agents.rb DELETED Viewed

@@ -1,150 +0,0 @@
-# frozen_string_literal: true
-# Agents — stateful actors with supervision and continuous contract loops
-#
-# Demonstrates:
-#   - Igniter::Agent       — stateful message-driven actor
-#   - Igniter::Supervisor  — one_for_one supervision with restart budget
-#   - Igniter::Registry    — looking up agents by name
-#   - Igniter::StreamLoop  — continuous contract tick-loop
-#
-# Run: ruby examples/agents.rb
-$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
-require "igniter"
-require "igniter/integrations/agents"
-# ── Contract used by the stream loop ─────────────────────────────────────────
-class ThresholdContract < Igniter::Contract
-  define do
-    input :value,     type: :numeric
-    input :threshold, type: :numeric
-    compute :status, depends_on: %i[value threshold] do |value:, threshold:|
-      value > threshold ? :alert : :normal
-    end
-    output :status
-  end
-end
-# ── Counter Agent ─────────────────────────────────────────────────────────────
-class CounterAgent < Igniter::Agent
-  initial_state counter: 0, history: []
-  on :increment do |state:, payload:, **|
-    by        = payload.fetch(:by, 1)
-    new_count = state[:counter] + by
-    state.merge(
-      counter: new_count,
-      history: (state[:history] + [new_count]).last(10)
-    )
-  end
-  on :reset do |state:, **|
-    state.merge(counter: 0, history: [])
-  end
-  # Returns the current count to sync callers
-  on :count do |state:, **|
-    state[:counter]
-  end
-  # Returns the last N history entries
-  on :history do |state:, payload:, **|
-    state[:history].last(payload.fetch(:n, 5))
-  end
-end
-# ── Logger Agent ──────────────────────────────────────────────────────────────
-class LoggerAgent < Igniter::Agent
-  initial_state entries: []
-  on :log do |state:, payload:, **|
-    ts    = Time.now.strftime("%H:%M:%S")
-    entry = "[#{ts}] #{payload[:message]}"
-    state.merge(entries: (state[:entries] + [entry]).last(100))
-  end
-  on :dump do |state:, **|
-    state[:entries]
-  end
-end
-# ── Supervisor ────────────────────────────────────────────────────────────────
-class AppSupervisor < Igniter::Supervisor
-  strategy     :one_for_one
-  max_restarts 3, within: 10
-  children do |c|
-    c.worker :counter, CounterAgent
-    c.worker :logger,  LoggerAgent
-  end
-end
-# ── Run: Supervised agents ────────────────────────────────────────────────────
-puts "=== Supervised agents ==="
-sup     = AppSupervisor.start
-counter = sup.child(:counter)
-logger  = sup.child(:logger)
-counter.send(:increment, by: 5)
-counter.send(:increment, by: 3)
-total = counter.call(:count)
-puts "counter=#{total}"
-logger.send(:log, message: "Counter reached #{total}")
-counter.send(:reset)
-counter.send(:increment, by: 10)
-new_total = counter.call(:count)
-puts "after_reset=#{new_total}"
-hist = counter.call(:history, { n: 5 })
-puts "history=#{hist.inspect}"
-# ── Run: Registry ─────────────────────────────────────────────────────────────
-puts "\n=== Registry lookup ==="
-named_ref = CounterAgent.start(name: :named_counter)
-Igniter::Registry.find(:named_counter).send(:increment, by: 42)
-puts "named_counter=#{named_ref.call(:count)}"
-named_ref.stop
-Igniter::Registry.unregister(:named_counter)
-# ── Run: StreamLoop ───────────────────────────────────────────────────────────
-puts "\n=== Stream loop ==="
-statuses = []
-stream = Igniter::StreamLoop.new(
-  contract: ThresholdContract,
-  tick_interval: 0.05,
-  inputs: { value: 20.0, threshold: 25.0 },
-  on_result: ->(result) { statuses << result.status }
-)
-stream.start
-sleep(0.15)                            # ~3 ticks at :normal
-stream.update_inputs(value: 30.0)
-sleep(0.15)                            # ~3 ticks at :alert
-stream.stop
-puts "statuses_sample=#{statuses.uniq.sort.inspect}"
-# ── Teardown ──────────────────────────────────────────────────────────────────
-log_entries = logger.call(:dump)
-puts "\nlog_entries=#{log_entries.size}"
-sup.stop
-puts "done=true"

data/examples/async_store.rb DELETED Viewed

@@ -1,47 +0,0 @@
-# frozen_string_literal: true
-$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
-require "igniter"
-require "tmpdir"
-class AsyncQuoteExecutor < Igniter::Executor
-  input :order_total, type: :numeric
-  def call(order_total:)
-    defer(token: "quote-#{order_total}", payload: { kind: "pricing_quote" })
-  end
-end
-class AsyncPricingContract < Igniter::Contract
-  run_with runner: :store
-  define do
-    input :order_total, type: :numeric
-    compute :quote_total, depends_on: [:order_total], call: AsyncQuoteExecutor
-    compute :gross_total, depends_on: [:quote_total] do |quote_total:|
-      quote_total * 1.2
-    end
-    output :gross_total
-  end
-end
-Dir.mktmpdir("igniter-example-store") do |dir|
-  original_store = Igniter.execution_store
-  Igniter.execution_store = Igniter::Runtime::Stores::FileStore.new(root: dir)
-  contract = AsyncPricingContract.new(order_total: 100)
-  deferred = contract.result.gross_total
-  execution_id = contract.execution.events.execution_id
-  puts "pending_token=#{deferred.token}"
-  puts "stored_execution_id=#{execution_id}"
-  puts "pending_status=#{contract.result.pending?}"
-  resumed = AsyncPricingContract.resume_from_store(execution_id, token: deferred.token, value: 150)
-  puts "resumed_gross_total=#{resumed.result.gross_total}"
-ensure
-  Igniter.execution_store = original_store
-end

data/examples/basic_pricing.rb DELETED Viewed

@@ -1,27 +0,0 @@
-# frozen_string_literal: true
-$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
-require "igniter"
-class PriceContract < Igniter::Contract
-  define do
-    input :order_total, type: :numeric
-    input :country, type: :string
-    compute :vat_rate, depends_on: [:country] do |country:|
-      country == "UA" ? 0.2 : 0.0
-    end
-    compute :gross_total, depends_on: %i[order_total vat_rate] do |order_total:, vat_rate:|
-      order_total * (1 + vat_rate)
-    end
-    output :gross_total
-  end
-end
-contract = PriceContract.new(order_total: 100, country: "UA")
-puts "gross_total=#{contract.result.gross_total}"
-contract.update_inputs(order_total: 150)
-puts "updated_gross_total=#{contract.result.gross_total}"

data/examples/collection.rb DELETED Viewed

@@ -1,43 +0,0 @@
-# frozen_string_literal: true
-$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
-require "igniter"
-class TechnicianContract < Igniter::Contract
-  define do
-    input :technician_id
-    input :name
-    compute :summary, with: %i[technician_id name] do |technician_id:, name:|
-      { id: technician_id, name: name }
-    end
-    output :summary
-  end
-end
-class TechnicianBatchContract < Igniter::Contract
-  define do
-    input :technician_inputs, type: :array
-    collection :technicians,
-      with: :technician_inputs,
-      each: TechnicianContract,
-      key: :technician_id,
-      mode: :collect
-    output :technicians
-  end
-end
-contract = TechnicianBatchContract.new(
-  technician_inputs: [
-    { technician_id: 1, name: "Anna" },
-    { technician_id: 2, name: "Mike" }
-  ]
-)
-result = contract.result.technicians
-puts "keys=#{result.keys.inspect}"
-puts "items=#{result.to_h.inspect}"