insika 0.3.0 → 0.8.0

data/lib/insika/telemetry/recorder.rb

@@ -40,7 +40,8 @@ module Insika
       # and units are part of the documented contract (docs/OBSERVABILITY.md) —
       # renaming one breaks every dashboard built on it.
       class Instruments
-        attr_reader :turns, :turn_duration, :tokens, :cost, :tool_calls, :tool_duration
+        attr_reader :turns, :turn_duration, :tokens, :cost, :tool_calls, :tool_duration,
+                    :cache_hit_rate, :loop_intervened, :context_compacted
 
         def initialize(meter)
           @turns = meter.create_counter("insika.turns", unit: "{turn}",
@@ -55,6 +56,12 @@ module Insika
                                                                   description: "Tool invocations")
           @tool_duration = meter.create_histogram("insika.tool.duration", unit: "s",
                                                                          description: "Wall time of a tool call")
+          @cache_hit_rate = meter.create_histogram("insika.cache.hit_rate", unit: "%",
+                                                                            description: "Prompt-cache hit rate of a turn (cached / billed prompt tokens)")
+          @loop_intervened = meter.create_counter("insika.tool.loop_intervened", unit: "{intervention}",
+                                                                                 description: "Loop-detector warnings delivered to the model")
+          @context_compacted = meter.create_counter("insika.context.compacted", unit: "{compaction}",
+                                                                                description: "In-session compactions persisted (RFC-0044)")
         end
       end
 
@@ -73,6 +80,8 @@ module Insika
         when :tool_call      then start_tool(meta, data)
         when :tool_result    then finish_tool(meta)
         when :data_tool_call then point_tool(meta, data)
+        when :tool_loop_intervened then count_loop(meta, data)
+        when :context_compacted then count_compaction(data)
         when :task_completed then finish_turn(meta, data, :ok)
         when :task_failed    then finish_turn(meta, data, :error)
         when :task_cancelled then finish_turn(meta, data, :cancelled)
@@ -166,6 +175,45 @@ module Insika
         @instruments.turns.add(1, attributes: labels)
         @instruments.turn_duration.record(seconds, attributes: labels) if seconds
         count_usage(turn, usage)
+        count_cache_hit(turn, usage)
+      end
+
+      # Same arithmetic as the Executor's per-agent series (stamp_cache_hit):
+      # the billed prompt is fresh input + cache reads + cache writes, and the
+      # hit rate is reads over the whole billed prompt — always in [0,100]. A
+      # turn with no billed prompt tokens (no usage, usage without the fields)
+      # records nothing: absence is not a 0% hit.
+      def count_cache_hit(turn, usage)
+        return unless usage
+
+        billed = usage[:input_tokens].to_i + usage[:cached_tokens].to_i +
+                 usage[:cache_creation_tokens].to_i
+        return unless billed.positive?
+
+        rate = (usage[:cached_tokens].to_i * 100.0) / billed
+        base = turn.labels.merge(attrs("insika.model" => usage[:model]&.to_s))
+        @instruments.cache_hit_rate.record(rate, attributes: base)
+      end
+
+      # The loop detector delivered its one-shot warning (`:tool_loop_intervened`,
+      # counts and the tool name, never arguments). An orphan event (no open turn)
+      # is ignored, like every other consumer of this stream.
+      def count_loop(meta, data)
+        return unless @instruments
+
+        turn = @turns[meta[:task_id]] or return
+        labels = turn.labels.merge(attrs("insika.tool" => data[:name]&.to_s))
+        @instruments.loop_intervened.add(1, attributes: labels)
+      end
+
+      # A compaction persisted (`:context_compacted`, RFC-0044) — counted by
+      # agent/model, INDEPENDENT of any open turn: it fires post-turn, usually
+      # after task_completed already closed the span.
+      def count_compaction(data)
+        return unless @instruments
+
+        labels = attrs("insika.agent" => data[:agent]&.to_s, "insika.model" => data[:model]&.to_s)
+        @instruments.context_compacted.add(1, attributes: labels)
       end
 
       # Tokens ride ONE counter split by `insika.token.type` (instead of four

data/lib/insika/templates/browser-agent/README.md

@@ -0,0 +1,36 @@
+# browser-agent
+
+**MCP trail (stdio).** A live MCP tool-loop over stdio: the
+engine spawns [Playwright's MCP server](https://github.com/microsoft/playwright-mcp)
+(`npx @playwright/mcp@latest`) as a child process and wires its browser
+tools straight into the agent's tool-loop. No API key beyond your LLM
+provider's.
+
+## Before you run it
+
+Two things this template needs beyond the gem and a provider key:
+
+1. **Node.js and npm** — `npx` spawns the MCP server as a child process.
+2. **`INSIKA_MCP_STDIO=1`** — a stdio MCP instance is arbitrary command
+   execution by config, so the engine refuses to start it until you opt in
+   explicitly (same discipline as the egress env vars for private hosts).
+
+```bash
+node --version   # confirm Node.js is installed
+INSIKA_MCP_STDIO=1 DEEPSEEK_API_KEY=sk-... ruby browser-agent/agent.rb "go to example.com and summarize the page"
+```
+
+Without `INSIKA_MCP_STDIO=1` the reply will say the tool call failed —
+that's the gate working, not a bug.
+
+## Swap the server
+
+This is not a Playwright showcase — it's exactly how you plug **any** MCP
+server into an agent over stdio:
+
+```bash
+MCP_COMMAND=your-mcp-server MCP_ARGS="--flag value" INSIKA_MCP_STDIO=1 DEEPSEEK_API_KEY=sk-... ruby browser-agent/agent.rb "..."
+```
+
+Point `MCP_COMMAND`/`MCP_ARGS` at any stdio MCP server and rewrite the
+instructions for its tools — nothing else in `agent.rb` changes.

data/lib/insika/templates/browser-agent/agent.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# ---
+# title: Browser Agent
+# trail: MCP
+# description: Live MCP tool-loop over stdio — navigates and summarizes a real webpage via Playwright's MCP server. Requires Node.js/npm and INSIKA_MCP_STDIO=1.
+# capabilities: mcp, stdio
+# env: INSIKA_MCP_STDIO
+# requires: Node.js and npm (npx spawns the MCP server as a child process)
+# ---
+#
+# browser-agent — a live MCP tool-loop over STDIO: the agent
+# drives a real, sandboxed browser through Playwright's MCP server
+# (@playwright/mcp, no API key). stdio is arbitrary command execution by
+# config, so it needs the operator's explicit opt-in (INSIKA_MCP_STDIO=1)
+# and Node.js/npm on the machine — the two things this template needs
+# beyond the gem and a provider key. Swap MCP_COMMAND/MCP_ARGS for any other
+# MCP server and nothing else in this file changes.
+#
+#   INSIKA_MCP_STDIO=1 DEEPSEEK_API_KEY=sk-... ruby browser-agent/agent.rb "go to example.com and summarize the page"
+require "insika"
+require "shellwords"
+
+browser = Insika.agent("browser-agent") do
+  model "deepseek-v4-flash"
+  provider :deepseek
+
+  instructions <<~PROMPT
+    You browse the web using the browser MCP tools. Navigate to the
+    requested page, then extract or summarize what was asked. Never invent
+    page content — always navigate and read it first.
+  PROMPT
+
+  mcp "browser", transport: :stdio,
+      command: ENV.fetch("MCP_COMMAND", "npx"),
+      args: Shellwords.split(ENV.fetch("MCP_ARGS", "-y @playwright/mcp@latest"))
+end
+
+if __FILE__ == $PROGRAM_NAME
+  if ARGV.delete("--serve")
+    browser.serve
+  else
+    message = ARGV.join(" ")
+    message = "Go to https://example.com and summarize the page in two sentences." if message.empty?
+    puts browser.reply(message)
+  end
+end
+
+browser

data/lib/insika/templates/daily-digest/README.md

@@ -0,0 +1,47 @@
+# daily-digest
+
+**Always-on trail.** The report pipeline in one file: a recurring
+`schedule` (the engine's own tick fires it), a `save_artifact`
+tool (the report destination), and a store-free skill describing
+*how* to build the report. No database, no store content — the day's
+numbers are fake, inline text.
+
+```bash
+DEEPSEEK_API_KEY=sk-... ruby daily-digest/agent.rb
+```
+
+Expected output: a reply ending in `Report: /studio/artifacts/<id>`.
+
+```bash
+DEEPSEEK_API_KEY=sk-... ruby daily-digest/agent.rb --serve
+```
+
+Then open `/studio`, log in with the printed token, and either wait for the
+schedule (22:00 America/Sao_Paulo) or send a message to the "reporter" agent
+in the Playground — the artifact lands on the Artifacts tab either way.
+
+## What's real here
+
+- The **schedule** is a live engine feature: the tick actually fires this
+  turn at the cron time, in the same process, no external cron needed.
+- The **artifact** is a real signed/authenticated URL the report is saved
+  to — open it and the HTML renders with its own strict CSP (`default-src
+  'none'`), so the inline SVG chart has to be self-contained by
+  construction, not by convention.
+- The **numbers** are not. Swap the literal string in `agent.rb` for a
+  `data_tool` against your own sales API and nothing else changes.
+
+## When the report needs real data
+
+One agent doing 30–50 tool calls at one reasoning effort is how a report turn
+hits the 300 s timeout. The recipe is to split the phases across agents —
+`thinking: "low"` miners fanned out with `spawn_subagents`, a `thinking: "high"`
+orchestrator that plans and writes. See
+[Artifacts](https://github.com/guizaols/insika/blob/main/docs/ARTIFACTS.md), "Reasoning effort on a report turn",
+and the `research-analyst` template for the fan-out shape.
+
+## Edit it
+
+The skill's instructions are the actual report spec — change the palette,
+add a second table, or add another chart. The schedule's `cron`/`tz` are
+plain arguments.

data/lib/insika/templates/daily-digest/agent.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+# ---
+# title: Daily Digest
+# trail: Always-on
+# description: A recurring schedule plus save_artifact build and publish a self-contained HTML report — no store, fake in-memory numbers only.
+# capabilities: schedule, save_artifact, skill
+# ---
+#
+# daily-digest — the report pipeline in one file: a recurring schedule (the
+# engine's own tick fires it), a daily-digest skill (the inline-SVG
+# pattern), the save_artifact tool (the report destination) and the
+# per-agent allowlist that gates it. No store content — fake, in-memory
+# "sales" numbers only.
+#
+#   DEEPSEEK_API_KEY=sk-... ruby daily-digest/agent.rb
+#   DEEPSEEK_API_KEY=sk-... ruby daily-digest/agent.rb --serve
+#       # --serve: open /studio, log in with the printed token, then send a
+#       # message to the "reporter" agent in the Playground — the artifact
+#       # lands on the Artifacts tab. The schedule fires the same run at
+#       # 22:00 America/Sao_Paulo on its own.
+require "insika"
+
+todays_sales = "Coffee 128 units ($512), Tea 64 units ($192), Pastries 40 units ($160)."
+
+reporter = Insika.agent("reporter") do
+  model "deepseek-v4-flash"
+  provider :deepseek
+
+  instructions <<~PROMPT
+    You produce the daily sales digest from the numbers given to you in the
+    message. Follow the daily-digest skill exactly, then save the finished
+    page with save_artifact (HTML with inline SVG). End your reply with the
+    artifact url, on its own line, prefixed with "Report: ".
+  PROMPT
+
+  # The per-agent allowlist IS the switch for save_artifact — without this
+  # line the model never even sees the tool.
+  tools %w[save_artifact]
+
+  # A recurring turn — the engine's tick fires it. session_mode:
+  # "new" = a fresh session per run (the report shape); the overrides raise
+  # the chat-time ceilings a real report needs.
+  schedule "daily_report", cron: "0 22 * * *", tz: "America/Sao_Paulo",
+           message: "Run the daily report now. Today's sales: #{todays_sales}",
+           session_mode: "new",
+           overrides: { turn_timeout: 600, max_tool_calls: 120 }
+
+  # The generic, store-free skill: how a report is BUILT — the inline-SVG
+  # pattern (palette, table, pure-SVG bars, light/dark). No store ids, no
+  # queries — that half belongs in a merchant's pack, not here.
+  skill "daily-digest",
+        description: "How to build the daily sales digest as a self-contained HTML report",
+        instructions: <<~MD
+          Build the digest as ONE self-contained HTML page:
+          - a <style> block with a light palette (e.g. #f8fafc bg, #0f172a text,
+            #6366f1 accent), plus a prefers-color-scheme: dark override;
+          - one <table> of the numbers (th/tbody, right-aligned amounts);
+          - one inline SVG bar chart (no <script>, no <img>, no <iframe>,
+            no external fonts or fetches — the report is served with
+            default-src 'none', so nothing external can load);
+          - a title and the run date.
+          Keep it readable on a phone. The report is the deliverable; the
+          channel message is just the link to it.
+        MD
+end
+
+if __FILE__ == $PROGRAM_NAME
+  if ARGV.delete("--serve")
+    reporter.serve
+  else
+    puts reporter.reply("Run the daily report now. Today's sales: #{todays_sales}")
+    puts "\nThen open the returned /studio/artifacts/<id> page (or --serve and look at the Artifacts tab)."
+  end
+end
+
+reporter

data/lib/insika/templates/repo-explorer/README.md

@@ -0,0 +1,36 @@
+# repo-explorer
+
+**MCP trail (http).** A live MCP tool-loop over Streamable HTTP:
+the agent calls a real, running MCP server's tools — not a snapshot, not a
+hand-rolled HTTP wrapper. The default target is
+[DeepWiki's public MCP server](https://mcp.deepwiki.com/mcp), which needs
+no API key for public repos.
+
+```bash
+DEEPSEEK_API_KEY=sk-... ruby repo-explorer/agent.rb "how does rails/rails route a request?"
+```
+
+This is not a DeepWiki showcase — it's exactly how you plug **any** MCP
+server into an agent:
+
+```bash
+MCP_URL=https://your-mcp-server/mcp DEEPSEEK_API_KEY=sk-... ruby repo-explorer/agent.rb "..."
+```
+
+Point `MCP_URL` at any Streamable HTTP or SSE MCP server and nothing else
+in `agent.rb` changes — swap the URL, rewrite the instructions for the new
+server's tools, done.
+
+## Under the hood
+
+`mcp "repo-docs", transport: :http, url: …` declares the instance; the
+engine connects live, discovers its tools (`read_wiki_structure`,
+`read_wiki_contents`, `ask_question`), and wires them straight into the
+agent's tool-loop with group `mcp:repo-docs`. Declaring an `mcp` inside an
+agent's block auto-grants that agent access to the group — see
+`lib/insika/dsl.rb`'s `mcp` method if you're curious why that matters.
+
+A public HTTPS target needs no extra configuration (same egress guard as
+any data-tool). A target on a private network needs the same
+`INSIKA_EGRESS_ALLOW_PRIVATE`/`INSIKA_EGRESS_HOSTS` env vars a data-tool
+would.

data/lib/insika/templates/repo-explorer/agent.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# ---
+# title: Repo Explorer
+# trail: MCP
+# description: Live MCP tool-loop over http — answers questions about any public GitHub repo via a keyless public MCP server. Point MCP_URL at any other MCP server instead.
+# capabilities: mcp, http
+# ---
+#
+# repo-explorer — a live MCP tool-loop over HTTP: the agent calls
+# a real MCP server's tools (read_wiki_structure, read_wiki_contents,
+# ask_question) to answer questions about a public GitHub repo. The default
+# target is DeepWiki's public, keyless MCP server — swap MCP_URL for any
+# other MCP server and nothing else in this file changes.
+#
+#   DEEPSEEK_API_KEY=sk-... ruby repo-explorer/agent.rb "how does rails/rails route a request?"
+#   MCP_URL=https://your-mcp-server/mcp DEEPSEEK_API_KEY=sk-... ruby repo-explorer/agent.rb "..."
+require "insika"
+
+repo = Insika.agent("repo-explorer") do
+  model "deepseek-v4-flash"
+  provider :deepseek
+
+  instructions <<~PROMPT
+    You answer questions about public GitHub repositories using the
+    repo-docs MCP tools (read_wiki_structure, read_wiki_contents,
+    ask_question). Repos are named "owner/repo" (e.g. "rails/rails"). Never
+    answer from your own training data when a tool can check — call
+    ask_question first.
+  PROMPT
+
+  mcp "repo-docs", transport: :http, url: ENV.fetch("MCP_URL", "https://mcp.deepwiki.com/mcp")
+end
+
+if __FILE__ == $PROGRAM_NAME
+  if ARGV.delete("--serve")
+    repo.serve
+  else
+    message = ARGV.join(" ")
+    message = "In the rails/rails repo, how does routing work? One paragraph." if message.empty?
+    puts repo.reply(message)
+  end
+end
+
+repo

data/lib/insika/templates/research-analyst/README.md

@@ -0,0 +1,26 @@
+# research-analyst
+
+**Advanced trail.** Four agents in one `Insika.system`: three specialists
+(market, technical, risk) and a lead ("analyst") that has no expertise of
+its own and must delegate. The MODEL decides to fan out — nothing in Ruby
+orchestrates the parallel calls.
+
+```bash
+DEEPSEEK_API_KEY=sk-... ruby research-analyst/agent.rb "a subscription box for specialty coffee"
+```
+
+Under the hood: the lead calls `spawn_subagents` once with all three
+specialist ids, they run **in parallel** (each in an isolated context — a
+child never sees the parent's conversation), and the lead synthesizes their
+three answers into one recommendation.
+
+Nothing forces the model to delegate — that's the trade of a model-driven
+pattern over a hand-coded workflow. If it answers alone instead, the fix is
+the lead's prompt, not the code: it needs to be told, plainly, that it has
+no expertise of its own.
+
+## Edit it
+
+Add a fourth specialist (`agent("competitors") { … }`, then add it to
+`subagents`), or turn any specialist into a `Insika.agent` with its own
+data-tools — a subagent is an ordinary agent, capability included.

data/lib/insika/templates/research-analyst/agent.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+# ---
+# title: Research Analyst
+# trail: Advanced
+# description: Insika.system fan-out — three specialist subagents research different angles of a topic in parallel, the lead delegates and synthesizes.
+# capabilities: subagents, delegation, system
+# ---
+#
+# research-analyst — a lead agent with no expertise of its own: it must
+# delegate. spawn_subagents fans out to three specialists on separate angles
+# of a business idea, IN PARALLEL (each in its own isolated context), then
+# the lead synthesizes one recommendation.
+#
+# Reasoning effort is split by ROLE, not spread evenly: the specialists answer
+# one narrow question each (`thinking: "low"`), the lead plans the delegation
+# and weighs three answers against each other (`thinking: "high"`). A child
+# inherits the environment as a DEFAULT only, so its own `params` wins. See
+# docs/ARTIFACTS.md, "Reasoning effort on a report turn".
+#
+#   DEEPSEEK_API_KEY=sk-... ruby research-analyst/agent.rb "a subscription box for specialty coffee"
+#   DEEPSEEK_API_KEY=sk-... ruby research-analyst/agent.rb --serve
+require "insika"
+
+team = Insika.system do
+  provider :deepseek
+
+  agent("market") do
+    model "deepseek-v4-flash"
+    params thinking: "low"
+    instructions "Research the MARKET angle of a business idea: audience, demand, competitors. Three sentences."
+  end
+  agent("technical") do
+    model "deepseek-v4-flash"
+    params thinking: "low"
+    instructions "Research the TECHNICAL/OPERATIONAL angle of a business idea: what it takes to build and run it. Three sentences."
+  end
+  agent("risk") do
+    model "deepseek-v4-flash"
+    params thinking: "low"
+    instructions "Research the RISK angle of a business idea: what could make it fail. Three sentences."
+  end
+
+  agent "analyst" do
+    model "deepseek-v4-flash"
+    params thinking: "high"
+    instructions <<~PROMPT
+      You are a research LEAD with no expertise of your own — never answer
+      from your own knowledge. Given a business idea, call spawn_subagents
+      once with all three specialists (market, technical, risk), then
+      synthesize their findings into one short recommendation: go, no-go, or
+      go-with-changes, and why.
+    PROMPT
+    subagents "market", "technical", "risk"
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  if ARGV.delete("--serve")
+    team.serve
+  else
+    topic = ARGV.join(" ")
+    topic = "a subscription box for specialty coffee" if topic.empty?
+    puts team.reply("analyst", "Research this idea: #{topic}")
+  end
+end
+
+team

data/lib/insika/templates/review-panel/README.md

@@ -0,0 +1,20 @@
+# review-panel
+
+**Teams trail.** The `Insika.system` snippet from the gem's main examples
+README, promoted to a runnable template: a "reviewer" lead with no
+expertise of its own delegates to two specialists — security and
+performance — IN PARALLEL, then synthesizes one prioritized fix.
+
+```bash
+DEEPSEEK_API_KEY=sk-... ruby review-panel/agent.rb
+```
+
+`panel.reply("reviewer", …)` — the target agent is always explicit; with
+several agents in one system, inferring which one should answer would be a
+guess, and a wrong guess is a silently wrong conversation.
+
+## Edit it
+
+Add a third specialist (a `style` reviewer, say), list it in `subagents`,
+and the lead's synthesis prompt already generalizes — it doesn't name the
+specialists, just says "both".

data/lib/insika/templates/review-panel/agent.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# ---
+# title: Review Panel
+# trail: Teams
+# description: Two specialists reviewed in parallel by a synthesizing lead, explicit target agent (Insika.system + subagents).
+# capabilities: subagents, delegation, system
+# ---
+#
+# review-panel — promotes the examples/README.md snippet to a runnable
+# template: a "reviewer" lead that has no expertise of its own delegates to
+# two specialists (security, performance) IN PARALLEL, then synthesizes.
+#
+#   DEEPSEEK_API_KEY=sk-... ruby review-panel/agent.rb
+#   DEEPSEEK_API_KEY=sk-... ruby review-panel/agent.rb --serve
+require "insika"
+
+panel = Insika.system do
+  provider :deepseek
+
+  agent("security")    { model "deepseek-v4-flash"; instructions "Review code for SECURITY issues. Two sentences." }
+  agent("performance") { model "deepseek-v4-flash"; instructions "Review code for PERFORMANCE issues. Two sentences." }
+
+  agent "reviewer" do
+    model "deepseek-v4-flash"
+    instructions <<~PROMPT
+      You are a review LEAD with no reviewing expertise of your own — never
+      review from your own knowledge. Call spawn_subagents once with both
+      specialists (security, performance), then synthesize their findings
+      into the single highest-priority fix.
+    PROMPT
+    subagents "security", "performance"
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  code = <<~RUBY
+    def find_user(name)
+      User.where("name = '\#{name}'").to_a.select { |u| u.active }
+    end
+  RUBY
+
+  if ARGV.delete("--serve")
+    panel.serve
+  else
+    puts panel.reply("reviewer", "Review this code:\n#{code}")
+  end
+end
+
+panel

data/lib/insika/templates/travel-planner/README.md

@@ -0,0 +1,35 @@
+# travel-planner
+
+**Starter trail.** A trip-planning assistant built entirely from **declarative
+data-tools** — no Ruby tool class, no rebuild. Three tools, three public
+HTTPS APIs, zero API keys beyond your LLM provider's:
+
+- `geocode_city` — Open-Meteo's geocoding API (city name → coordinates)
+- `get_weather` — Open-Meteo's forecast API (coordinates → today's conditions)
+- `convert_currency` — Frankfurter's reference exchange rates
+
+```bash
+DEEPSEEK_API_KEY=sk-... ruby travel-planner/agent.rb "3 days in Lisbon, budget 200 USD"
+```
+
+The model chains the first two tools itself (geocode, then weather) and
+calls the third when a budget is mentioned — nothing here tells it the
+order, the instructions just describe what each tool is for.
+
+## Egress guard (SSRF protection)
+
+Data-tools make **server-side** HTTP calls, so the engine ships an egress
+guard that is strict by default: public HTTPS only. This template works
+with zero configuration because all three endpoints are public HTTPS — a
+tool pointed at `http://…`, `localhost`, or a private IP would be blocked
+instead (`{ error: "destination blocked: …" }` back to the model, a clean
+tool error, never a crash). Opting a private/internal target in is a
+deployment env var (`INSIKA_EGRESS_ALLOW_HTTP`/`_PRIVATE`/`_HOSTS`), never a
+DSL setting — see `docs/TOOLS.md`'s "MCP servers" / egress sections in the
+installed gem's docs for the full contract.
+
+## Edit it
+
+Open `agent.rb` — it's the same file `insika new` copied and the same one
+this README describes. Add a fourth data-tool, change the model, or point
+an existing one at a different provider; nothing else needs to change.

data/lib/insika/templates/travel-planner/agent.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+# ---
+# title: Travel Planner
+# trail: Starter
+# description: Weather + currency data-tools against keyless public APIs (Open-Meteo, Frankfurter) — the egress guard does its job with zero configuration.
+# capabilities: data-tool, egress-guard
+# ---
+#
+# travel-planner — plans a trip: geocodes the destination, checks today's
+# weather, and converts a budget to the local currency. Three declarative
+# data-tools, no Ruby tool class, no API key beyond the LLM provider's.
+#
+#   DEEPSEEK_API_KEY=sk-... ruby travel-planner/agent.rb "3 days in Lisbon, budget 200 USD"
+#   DEEPSEEK_API_KEY=sk-... ruby travel-planner/agent.rb --serve
+require "insika"
+
+travel = Insika.agent("travel-planner") do
+  model "deepseek-v4-flash"
+  provider :deepseek
+
+  instructions <<~PROMPT
+    You are a travel-planning assistant. Given a destination and, optionally,
+    a budget amount + currency:
+      1. geocode_city to find its coordinates — never guess them.
+      2. get_weather for those coordinates and summarize today's conditions.
+      3. If a budget was given, convert_currency to the destination's local
+         currency and report the converted amount.
+    Never invent coordinates, weather or exchange rates — always call the tools.
+  PROMPT
+
+  data_tool(
+    "name"        => "geocode_city",
+    "description" => "Latitude/longitude for a city name (Open-Meteo geocoding).",
+    "parameters"  => {
+      "type" => "object",
+      "properties" => { "city" => { "type" => "string", "description" => "city name, e.g. Lisbon" } },
+      "required" => ["city"]
+    },
+    "request"  => { "method" => "GET", "url" => "https://geocoding-api.open-meteo.com/v1/search?name={{city}}&count=1" },
+    "response" => { "extract" => "body_raw" }
+  )
+
+  data_tool(
+    "name"        => "get_weather",
+    "description" => "Current weather for a latitude/longitude (Open-Meteo).",
+    "parameters"  => {
+      "type" => "object",
+      "properties" => {
+        "latitude"  => { "type" => "number", "description" => "from geocode_city" },
+        "longitude" => { "type" => "number", "description" => "from geocode_city" }
+      },
+      "required" => %w[latitude longitude]
+    },
+    "request"  => { "method" => "GET", "url" => "https://api.open-meteo.com/v1/forecast?latitude={{latitude}}&longitude={{longitude}}&current_weather=true" },
+    "response" => { "extract" => "body_raw" }
+  )
+
+  # Author the FINAL url — the HTTP client does not follow redirects.
+  # api.frankfurter.app now redirects to api.frankfurter.dev.
+  data_tool(
+    "name"        => "convert_currency",
+    "description" => "Latest reference exchange rate between two currencies.",
+    "parameters"  => {
+      "type" => "object",
+      "properties" => {
+        "from" => { "type" => "string", "description" => "source currency code, e.g. USD" },
+        "to"   => { "type" => "string", "description" => "target currency code, e.g. BRL" }
+      },
+      "required" => %w[from to]
+    },
+    "request"  => { "method" => "GET", "url" => "https://api.frankfurter.dev/v1/latest?from={{from}}&to={{to}}" },
+    "response" => { "extract" => "body_raw" }
+  )
+end
+
+if __FILE__ == $PROGRAM_NAME
+  if ARGV.delete("--serve")
+    travel.serve
+  else
+    message = ARGV.join(" ")
+    message = "I'm spending 3 days in Lisbon with a budget of 200 USD. What should I pack, and how much is that in EUR?" if message.empty?
+    puts travel.reply(message)
+  end
+end
+
+travel