insika 0.2.0 → 0.7.0

data/lib/insika/wiring/graph_chat.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Insika
+  module Wiring
+    # A synchronous, in-process "chat" seam over an assembled `Graph::Result`:
+    # dispatch a Command, drain the event stream to its terminal event, hand
+    # back the outcome. Extracted from `DSL::Runtime#chat`/`#run_workflow`
+    # (C3.1) so a graph built OUTSIDE the DSL — `config/deployment.rb`, the
+    # actual production/round1 composition root `config.ru` boots — can hand a
+    # `#chat`-capable object to anything that needs one (today:
+    # `run_persona_eval`'s `Evals::GraphTransport` seam), without a second copy
+    # of this dispatch+drain plumbing. `DSL::Runtime` now delegates here too —
+    # one implementation, exercised by both roots.
+    class GraphChat
+      TERMINAL = %i[task_completed task_failed task_cancelled].freeze
+
+      def initialize(graph:)
+        @graph = graph
+      end
+
+      # One turn, in-process -> the assistant's text. `agent:` is REQUIRED —
+      # this seam has no notion of "the default agent" (that is a DSL::Runtime
+      # concept, filled in by its own caller before delegating here). Raises
+      # Insika::Error on a failed/cancelled turn, or the command's own
+      # rejection (unknown agent, bad schema) verbatim.
+      def chat(message, agent:, session_id: nil, timeout: nil)
+        command = Insika::Command.build(
+          :send_message, { agent: agent.to_s, message: message, session_id: session_id },
+          transport: :cli
+        )
+        run_command(command, session_id: session_id, timeout: timeout)[:text]
+      end
+
+      # Dispatch + drain, generic over any Command — the seam a workflow run
+      # also needs (a :trigger_workflow Command carries :output, not :text).
+      # Subscribes BEFORE dispatching (the fiber may emit eagerly) and binds to
+      # the dispatched task. A synchronous handler error (unknown agent/
+      # workflow, bad input against the schema) propagates untouched — the
+      # caller sees the real ValidationError/NotFoundError, not a turn failure.
+      def run_command(command, session_id:, timeout:)
+        require "async"
+        outcome = {}
+        rejected = nil
+        Async do |task|
+          serving = !session_id.nil?
+          @graph.executor.supervised = true if serving
+          ensure_session(session_id) if session_id
+          sub = @graph.event_stream.subscribe
+          res = begin
+            @graph.bus.dispatch(command)
+          rescue StandardError => e
+            # CAPTURED, not re-raised inside the reactor: letting it escape the
+            # Async block logs "Task may have ended with unhandled exception" —
+            # alarming noise for a DOCUMENTED rejection (a schema violation, an
+            # unknown agent). Re-raised verbatim below, outside the reactor.
+            sub.close
+            rejected = e
+            next
+          end
+          sub.bind(task_id: res[:task_id])
+          drain(sub, outcome, task, timeout)
+          teardown_serving if serving
+        end.wait
+        raise rejected if rejected
+        raise Insika::Error, "turn #{outcome[:error]}" if outcome[:error]
+
+        outcome
+      end
+
+      private
+
+      # Reads the stream until this turn reaches a terminal event, then stops.
+      # A workflow run also carries its typed OUTPUT, which is not the turn text.
+      def drain(sub, outcome, task, timeout)
+        reader = task.async do
+          sub.each do |ev|
+            case ev.type
+            when :task_completed      then outcome[:text] = ev.data[:content].to_s
+            when :workflow_completed  then outcome[:output] = ev.data[:output]
+            when :task_failed         then outcome[:error] = "failed: #{ev.data[:message] || ev.data[:error]}"
+            when :task_cancelled      then outcome[:error] = "cancelled"
+            end
+            sub.close if TERMINAL.include?(ev.type)
+          end
+        end
+        timeout ? task.with_timeout(timeout) { reader.wait } : reader.wait
+      rescue Async::TimeoutError
+        outcome[:error] = "timed out after #{timeout}s"
+        sub.close
+      end
+
+      def ensure_session(session_id)
+        @graph.session_store.find(session_id) || @graph.session_store.create(id: session_id, vars: {})
+      end
+
+      def teardown_serving
+        @graph.executor.stop_session_actors
+        @graph.executor.instance_variable_get(:@supervisor)&.stop
+      end
+    end
+  end
+end

data/lib/insika.rb

@@ -1,13 +1,55 @@
 # frozen_string_literal: true
 
+# Templates under lib/insika/templates/*/agent.rb open with a bare
+# `require "insika"` (the line a standalone `ruby agent.rb` run needs) and
+# Templates.evaluate instance_evals that same source in-process — so this
+# file's own directory must be on $LOAD_PATH, or that require raises
+# LoadError whenever nothing else already activated the "insika" gem
+# (no Bundler.setup, no globally installed gem).
+$LOAD_PATH.unshift(__dir__) unless $LOAD_PATH.include?(__dir__)
+
 require_relative "insika/version"
 require_relative "insika/errors"
+# the payload selection + the domain-boundary audit yardstick.
+# Pure module — loaded by the gemspec too, so it carries no app requires.
+require_relative "insika/packaging"
 require_relative "insika/provider_error_classifier"
 require_relative "insika/token_store"
 require_relative "insika/budget_ledger"
 require_relative "insika/circuit_state"
 require_relative "insika/reliability"
+require_relative "insika/routing"
+require_relative "insika/media"
 require_relative "insika/alert_dispatcher"
+require_relative "insika/outcome_store"
+require_relative "insika/retention"
+require_relative "insika/funnel_declaration"
+require_relative "insika/funnel_store"
+require_relative "insika/funnel_fold"
+# the parsed follow-up policy of ONE agent — the ONLY shape the
+# engine accepts (tool/engine/doctor/Studio share it). Pure value object.
+require_relative "insika/followup_policy"
+# the contact-state cells and the follow-up schedule records.
+# Both are dumb domain stores over the injected backend.
+require_relative "insika/contact_store"
+require_relative "insika/followup_store"
+# the tick-driven firer — rides the same tick as retention/funnel.
+require_relative "insika/followup_engine"
+# IANA zone resolution through the OS tz database — the stdlib-only route
+# to a zone NAME (Follow-up quiet hours, the cron scheduler, the doctor).
+require_relative "insika/timezone"
+# the recurring schedule: the five-field cron subset + next-fire
+# materialization, the declaration parse, the per-agent rows, and the
+# tick-driven firer (the recurring half of the tick).
+require_relative "insika/cron"
+require_relative "insika/schedule"
+require_relative "insika/schedule_store"
+require_relative "insika/schedule_engine"
+# the report destination — one record per run, no
+# versioning; the signing half of the sharing link (HMAC, no secret stored).
+require_relative "insika/artifact_store"
+require_relative "insika/artifact_signing"
+require_relative "insika/commands/freeze_funnel_baseline"
 require_relative "insika/channels/webhook"
 require_relative "insika/coercion"
 require_relative "insika/message_origin"
@@ -21,6 +63,9 @@ require_relative "insika/model_selection"
 require_relative "insika/model_resolver"
 require_relative "insika/tool_definition"
 require_relative "insika/tool_manifest"
+# the pack's grounding policy (Insika::Grounding + the
+# GroundingMatcher it wraps). Pure Ruby — profile data, parsed per turn.
+require_relative "insika/grounding"
 require_relative "insika/frontmatter"
 require_relative "insika/token_estimator"
 require_relative "insika/checkpoint"
@@ -33,9 +78,12 @@ require_relative "insika/usage_ledger"
 require_relative "insika/budget_ledger"
 require_relative "insika/edge_limiter"
 require_relative "insika/tool_output_compressor"
-# Content safety / guardrails. detectors.rb is self-contained (the eval
-# requires it directly); the rest hang off Middleware/hooks seams. No ruby_llm
-# at load-time — Factory requires the gem lazily, like the Executor's create_chat.
+# Content safety / guardrails. The pattern SOURCE is the
+# language-tagged data in safety/corpus.rb; detectors.rb compiles it. Both are
+# self-contained (the eval requires detectors.rb directly); the rest hang off
+# Middleware/hooks seams. No ruby_llm at load-time — Factory requires the gem
+# lazily, like the Executor's create_chat.
+require_relative "insika/safety/corpus"
 require_relative "insika/safety/detectors"
 require_relative "insika/safety/safe_responses"
 require_relative "insika/safety/config"
@@ -55,7 +103,13 @@ require_relative "insika/context/providers/skill"
 require_relative "insika/context/providers/skill_trigger"
 require_relative "insika/context/providers/tool_search"
 require_relative "insika/context/providers/memory"
+require_relative "insika/context/providers/knowledge"
 require_relative "insika/context/providers/session"
+require_relative "insika/context/providers/briefing"
+# the cache-prefix hash chain + the per-agent cache-hit series.
+# Both are referenced by the Executor at runtime, so they load before it.
+require_relative "insika/prefix_fingerprint"
+require_relative "insika/cache_series_store"
 require_relative "insika/policy/policy"
 require_relative "insika/policy/engine"
 require_relative "insika/registry"
@@ -78,8 +132,13 @@ require_relative "insika/delegation_store"
 # Channels: the outbound record + the inbound retry window. Both are
 # plain stores; the channel objects themselves come after the HTTP client.
 require_relative "insika/outbox_store"
+require_relative "insika/shadow_pair_store"
 require_relative "insika/inbound_log"
 require_relative "insika/memory_store"
+require_relative "insika/knowledge_store"
+# the operator-mutation audit trail. After memory_store (no
+# mutual deps). Pure stdlib — `load_guard_spec` stays green.
+require_relative "insika/memory_audit_store"
 require_relative "insika/config_store"
 require_relative "insika/profile_source"
 require_relative "insika/agent_file_store"
@@ -88,6 +147,10 @@ require_relative "insika/secret_masking"
 require_relative "insika/tool_store"
 require_relative "insika/tool_trace_store"
 require_relative "insika/context_trace_store"
+# the model-visible payload of one ask + its durable trace —
+# "model-visible means logged" (the conformance suite's reconstruction half).
+require_relative "insika/model_visible"
+require_relative "insika/model_visible_trace_store"
 # Refinement: the run record + the evidence half of the loop.
 # Reads sessions/tasks/traces above; requires Safety::Detectors (loaded earlier) for
 # the PII redaction of the snippets it puts in a report.
@@ -101,6 +164,9 @@ require_relative "insika/refinement/candidate"
 require_relative "insika/refinement/proposer"
 require_relative "insika/egress_guard"
 require_relative "insika/schema_guard"
+# the evidence contract (Spec + Processor + EvidenceLedger). Pure Ruby.
+# Required BEFORE tool_envelope.rb — the envelope references it at runtime.
+require_relative "insika/evidence"
 require_relative "insika/sandbox"
 require_relative "insika/http_client"
 # Channels: the registry, the bundled relay adapter and the
@@ -130,6 +196,14 @@ require_relative "insika/evals/runner"
 require_relative "insika/evals/report"
 require_relative "insika/evals/baseline"
 require_relative "insika/evals/transport"
+# simulated users: the persona data + the conversation driver.
+# Pure — the persona model is an injected ask, the target rides the Transport.
+require_relative "insika/evals/persona"
+require_relative "insika/evals/simulator"
+# shadow parity: the frozen criterion and the mechanical
+# fold over the pair store (C6). Pure — no store, no provider gem.
+require_relative "insika/parity/criterion"
+require_relative "insika/parity/verdict"
 # Authored eval cases: the corpus becomes editable without a
 # checkout. Requires the loader above (it is the one validator).
 require_relative "insika/golden_store"
@@ -143,6 +217,14 @@ require_relative "insika/refinement/panel"
 require_relative "insika/mcp_store"
 require_relative "insika/mcp_http_client"
 require_relative "insika/mcp_tool_ingestor"
+# require "ruby_llm/mcp" itself is LAZY, inside .for — this require_relative only
+# loads the thin factory (see spec/insika/load_guard_spec.rb).
+require_relative "insika/mcp_client"
+# insika/mcp_live_tool (< RubyLLM::Tool) is NOT required here — McpToolRegistry
+# require_relative's it lazily on the 1st instance (turn time), same as
+# OverlayToolRegistry does for tools/data_defined_tool.
+require_relative "insika/mcp_tool_registry"
+require_relative "insika/mcp_json"
 require_relative "insika/system_file_store"
 require_relative "insika/recovery"
 require_relative "insika/command_bus"
@@ -177,6 +259,54 @@ require_relative "insika/commands/delete_llm_provider"
 require_relative "insika/commands/issue_tenant_token"
 require_relative "insika/commands/revoke_token"
 require_relative "insika/commands/rotate_tenant_token"
+require_relative "insika/commands/record_outcome"
+require_relative "insika/commands/record_shadow_reply"
+require_relative "insika/commands/judge_shadow_pairs"
+require_relative "insika/commands/session_purge"
+require_relative "insika/commands/forget_customer"
+require_relative "insika/commands/delete_tenant_data"
+# the LGPD access right — export one customer's memory cell as
+# content (the Studio download); the event stays counts-only.
+require_relative "insika/commands/export_customer_memory"
+# the operator/integration follow-up mutations (cancel one
+# record; revoke a contact + fall its pending records atomically).
+require_relative "insika/commands/cancel_followup"
+require_relative "insika/commands/revoke_contact"
+# the report destination's Studio mutation — delete one artifact
+# (a bus command, like every Studio mutation).
+require_relative "insika/commands/delete_artifact"
+# session distillation — the distiller (pure, injected ask)
+# and the proposal store (proposals + the latched dedup ledger + the
+# per-session distilled marker).
+require_relative "insika/distill"
+require_relative "insika/proposal_store"
+require_relative "insika/commands/run_distillation"
+require_relative "insika/distill_engine"
+require_relative "insika/commands/resolve_proposal"
+# the gated harvest — the miner (pure, injected ask), the
+# frozen conversion criterion and the versioned negative list. The provider
+# touch stays inside MinerFactory's lazy ask (load_guard stays green).
+require_relative "insika/harvest"
+require_relative "insika/harvest/criterion"
+require_relative "insika/harvest/negative_list"
+require_relative "insika/harvest/conversion_gate"
+require_relative "insika/harvest/gate"
+require_relative "insika/harvest_store"
+require_relative "insika/commands/run_harvest"
+require_relative "insika/commands/gate_harvest"
+require_relative "insika/commands/promote_harvest"
+require_relative "insika/commands/rollback_harvest"
+require_relative "insika/commands/reject_harvest"
+require_relative "insika/harvest_engine"
+# post-turn learning — the extractor (pure, injected ask) and the
+# concept format itself (markdown + YAML frontmatter, the SkillCatalog
+# split). The provider touch stays inside ExtractorFactory's lazy ask
+# (load_guard stays green).
+require_relative "insika/knowledge"
+require_relative "insika/commands/backfill_knowledge"
+require_relative "insika/commands/write_concept"
+require_relative "insika/commands/delete_concept"
+require_relative "insika/commands/restore_concept"
 require_relative "insika/commands/upsert_mcp"
 require_relative "insika/commands/delete_mcp"
 require_relative "insika/commands/write_system_file"
@@ -187,6 +317,14 @@ require_relative "insika/commands/delete_data_tool"
 require_relative "insika/commands/restore_data_tool"
 require_relative "insika/commands/import_tools"
 require_relative "insika/commands/import_mcp_tools"
+require_relative "insika/commands/refresh_mcp_tools"
+# the demo seed (OSS onboarding): one bundled agent + golden
+# set + the Seeder that populates every loop's stores at once, and its bus
+# adapter for `insika demo:seed` and the Studio's "Seed demo data" button.
+require_relative "insika/demo/agent_attrs"
+require_relative "insika/demo/golden_cases"
+require_relative "insika/demo/seeder"
+require_relative "insika/commands/seed_demo_data"
 require_relative "insika/event_stream"
 require_relative "insika/task_actor"
 require_relative "insika/queue_policy"
@@ -195,6 +333,7 @@ require_relative "insika/skill_catalog"
 require_relative "insika/tool_catalog"
 require_relative "insika/steer_injector"
 require_relative "insika/loop_detector"
+require_relative "insika/balloon_splitter"
 require_relative "insika/turn_output"
 require_relative "insika/turn_state"
 require_relative "insika/turn_timing"
@@ -207,10 +346,17 @@ require_relative "insika/shutdown"
 require_relative "insika/tick"
 require_relative "insika/pack"
 require_relative "insika/pack_importer"
+require_relative "insika/templates"
 require_relative "insika/telemetry"
 # Strict config + diagnosis. Doctor reads the config stores above;
 # EnvSchema (required at the top) is its env layer.
 require_relative "insika/doctor"
+# Soak: the 72h uptime-degradation harness. Pure stdlib — the
+# envelope and the report fold are deterministic, the runner only talks Net::HTTP.
+require_relative "insika/soak/envelope"
+require_relative "insika/soak/report"
+require_relative "insika/soak/runner"
+require_relative "insika/vitals"
 # Shared composition core for both roots (config/wiring.rb + config/deployment.rb).
 # Only references the classes above at call-time, so require order is unconstrained.
 require_relative "insika/wiring/graph"