pikuri 0.0.1

data/lib/pikuri.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require 'logger'
+require 'zeitwerk'
+
+# +Pikuri::VERSION+ lives in its own tiny file so the gemspec can read
+# the version constant via +require_relative+ at build time without
+# loading Zeitwerk and every runtime dep. Requiring it here makes the
+# constant available to ordinary +require 'pikuri'+ callers too —
+# without this line, Zeitwerk's ignore-rule below would leave
+# +Pikuri::VERSION+ undefined for anyone using the installed gem.
+require_relative 'pikuri/version'
+
+# Boot file: configures the Zeitwerk autoloader for every file under
+# +lib/pikuri/+ and eager-loads them all. After +require 'pikuri'+,
+# every constant pikuri ships (+Pikuri::Agent+, +Pikuri::Tool+,
+# +Pikuri::Tool::Calculator+, +Pikuri::Tool::Scraper::HTML+, ...) is
+# defined and resolvable.
+#
+# Beyond loading, the +Pikuri+ module owns the logging surface — see
+# {.logger_for}, {.log_io=}, and the +PIKURI_LOG+ /
+# +PIKURI_LOG_<NAME>+ env vars. Each subsystem holds its own
+# memoized +Logger+, all writing through a shared IO that
+# {.log_io=} can swap in one shot (handy in tests, daemons, or
+# anywhere stderr isn't the right sink).
+#
+# == Why eager-load
+#
+# Tool implementations (+Pikuri::Tool::CALCULATOR+,
+# +Pikuri::Tool::WEB_SEARCH+, +Pikuri::Tool::WEB_SCRAPE+,
+# +Pikuri::Tool::FETCH+) are +ALL_CAPS+ value constants rather than
+# classes/modules, and Zeitwerk only auto-loads constants that match
+# its filename-↔-CamelCase convention. Eager-loading at boot guarantees
+# the files defining those values run, so the bin script can splat them
+# straight into +Pikuri::Agent.new(tools: [...])+ without per-file
+# +require+ ceremony. The cost is a few milliseconds of startup —
+# negligible compared to a single LLM round-trip.
+module Pikuri
+  # Absolute path to the directory holding pikuri's bundled system
+  # prompts (+pikuri-chat.txt+, +coding-system-prompt.txt+). Resolves
+  # correctly both in a source checkout and in an installed gem because
+  # +__dir__+ tracks the file's actual location either way; the gem
+  # ships +prompts/+ as a sibling of +lib/+ so the same relative jump
+  # works.
+  #
+  # Exposed publicly so a downstream library user can read pikuri's
+  # prompts as a starting point for their own system prompt (or use
+  # them verbatim). Prefer {.prompt} for the common case of loading
+  # one by name; reach for this constant only if you need the
+  # directory itself (e.g. to list available prompts).
+  #
+  # @return [String]
+  PROMPTS_DIR = File.expand_path('../prompts', __dir__)
+
+  # Mapping from +PIKURI_LOG+ env-var values (lowercased) to
+  # {Logger} level constants. Anything else falls back to +INFO+.
+  #
+  # @return [Hash{String=>Integer}]
+  LOG_LEVELS = {
+    'debug' => Logger::DEBUG,
+    'info'  => Logger::INFO,
+    'warn'  => Logger::WARN,
+    'error' => Logger::ERROR,
+    'fatal' => Logger::FATAL
+  }.freeze
+
+  @log_io      = $stderr
+  @log_loggers = {} # name → Logger; lets {.log_io=} rewire all of them
+  @log_default = LOG_LEVELS.fetch(ENV['PIKURI_LOG'].to_s.downcase, Logger::INFO)
+
+  class << self
+    # @return [IO] shared sink every {.logger_for} writes through
+    attr_reader :log_io
+
+    # Swap the shared sink (e.g. a +StringIO+ in tests, a file in a
+    # daemon). Re-points every logger already handed out by
+    # {.logger_for} so callers don't have to re-fetch them.
+    #
+    # Why we don't use +Logger#reopen+: that method closes the previous
+    # sink before installing the new one, which makes "swap to a
+    # capture +StringIO+, then swap back to the original" impossible —
+    # the original handle would be dead the second time around. Instead
+    # we swap each logger's +@logdev+ to a fresh +Logger::LogDevice+
+    # over the new +io+, leaving the previous device untouched so the
+    # caller can hand the same +IO+ back in later. This uses a documented
+    # but internal Logger ivar; if a future Ruby renames it the
+    # +Engines+ logging specs will fail loudly.
+    #
+    # @param io [IO] new sink for every Pikuri logger
+    # @return [IO]
+    def log_io=(io)
+      @log_io = io
+      @log_loggers.each_value do |lg|
+        lg.instance_variable_set(:@logdev, Logger::LogDevice.new(io))
+      end
+      io
+    end
+
+    # Memoized {Logger} tagged with +name+ in its +progname+, so each
+    # subsystem's lines stand out in the shared sink. Level resolves
+    # in this order: +PIKURI_LOG_<NAME>+ (e.g. +PIKURI_LOG_ENGINES=debug+),
+    # then +PIKURI_LOG+, then +INFO+.
+    #
+    # Repeated calls with the same +name+ return the same instance so
+    # there is one logger per subsystem and {.log_io=} can rewire them
+    # all in one shot.
+    #
+    # @param name [String] subsystem tag (rendered as +progname+)
+    # @return [Logger]
+    def logger_for(name)
+      @log_loggers[name] ||= begin
+        lg = Logger.new(@log_io, progname: name)
+        override = ENV["PIKURI_LOG_#{name.upcase}"].to_s.downcase
+        lg.level = LOG_LEVELS.fetch(override, @log_default)
+        lg
+      end
+    end
+
+    # Read a bundled prompt by basename. +name+ is matched against the
+    # files in {PROMPTS_DIR}; a +.txt+ extension is auto-appended if
+    # absent. Symbols are accepted as a convenience (+:pikuri-chat+ /
+    # +'pikuri-chat'+ / +'pikuri-chat.txt'+ all resolve to the same file).
+    #
+    # Intended for downstream library users who want to bootstrap their
+    # own +Pikuri::Agent+ wiring from pikuri's defaults — read the
+    # prompt, customize the bits they care about, hand the result to
+    # +Agent.new(system_prompt: ...)+.
+    #
+    # @example
+    #   chat_prompt = Pikuri.prompt(:'pikuri-chat')
+    #   agent = Pikuri::Agent.new(system_prompt: chat_prompt, ...)
+    #
+    # @param name [String, Symbol] basename of the prompt file
+    # @return [String] file contents
+    # @raise [ArgumentError] if no matching file exists in {PROMPTS_DIR}
+    def prompt(name)
+      basename = name.to_s
+      basename += '.txt' unless basename.end_with?('.txt')
+      path = File.join(PROMPTS_DIR, basename)
+      unless File.exist?(path)
+        available = Dir.children(PROMPTS_DIR).sort.join(', ')
+        raise ArgumentError, "Unknown pikuri prompt #{name.inspect}; available: #{available}"
+      end
+      File.read(path)
+    end
+  end
+
+  Loader = Zeitwerk::Loader.new
+  Loader.tag = 'pikuri'
+  Loader.push_dir(File.expand_path('.', __dir__))
+  Loader.ignore(__FILE__)
+  # +lib/pikuri/version.rb+ defines +Pikuri::VERSION+ (an ALL_CAPS value
+  # constant), not +Pikuri::Version+ as Zeitwerk would expect from the
+  # filename — so tell the loader to skip it. The file is +require_relative+'d
+  # at the top of this file (and also by the gemspec at build time), so
+  # the constant is defined before Zeitwerk runs.
+  Loader.ignore(File.expand_path('pikuri/version.rb', __dir__))
+  Loader.inflector.inflect(
+    'html'       => 'HTML',
+    'pdf'        => 'PDF',
+    'duckduckgo' => 'DuckDuckGo'
+  )
+  Loader.setup
+  Loader.eager_load
+end

data/prompts/coding-system-prompt.txt

@@ -0,0 +1,28 @@
+You are an expert coding assistant who reads, edits, and runs code via tools to solve software engineering tasks.
+
+You operate on the local filesystem under a workspace directory. All file-touching tools resolve paths within that workspace; trying to escape returns an error. The `bash` and `write` tools may prompt the user for confirmation before running — if they decline, accept it and don't retry the same operation.
+
+You have access to tools described in the API's tool list. To call one, use the standard tool-call mechanism — do not write tool calls as text.
+
+If several next steps are independent (e.g. reading two unrelated files, or running unrelated checks), emit them as parallel tool calls in a single turn rather than one at a time.
+
+Choosing a tool:
+- File reading: `read` for a known path, `grep` to search file contents by pattern, `glob` to find files by name pattern. Do NOT use `bash` for these (no `cat`, `sed`, `awk`, `rg`, `find`) — the dedicated tools respect the workspace and produce cleaner output.
+- Editing: `edit` for surgical changes — its `old_string` argument must match exact bytes, so always `read` the target file first. Use `write` for new files, or for wholesale rewrites of existing files (which will prompt the user for confirmation).
+- Running things: `bash` for tests, builds, git, scripts, and other shell commands. Briefly explain non-trivial commands before running them.
+- Research: `web_search`, `web_scrape`, `fetch` for stack traces, library docs, current API references — prefer local source via `read` / `grep` when the information is already in the workspace. `sub_agent` to delegate research that would otherwise blow up your context (full-codebase audits, multi-page reading).
+- `calculator` for arithmetic beyond simple mental math.
+
+Working on code:
+- Look at neighboring files first — match the existing conventions, library choices, naming, and comment style.
+- Make the smallest change that does the job. Don't refactor, rename, or add features beyond what was asked.
+- If you're unsure how a piece of code is used, `grep` for its callers before editing it.
+- After a substantive change, run the project's tests or build if you can locate them (look at README, package.json, Cargo.toml, Makefile, build.gradle, Gemfile, etc.).
+- Don't add ceremonial comments. Match the surrounding code's commenting style.
+- NEVER commit, push, or open a PR unless the user explicitly asks.
+
+Other guidelines:
+- Don't repeat a tool call with identical arguments — re-read the previous observation instead.
+- On a tool error (observation starting with `Error:`): use the data you already have to continue if you can. If you can't, reply to the user that you weren't able to complete the task and briefly say why (e.g. "the test runner isn't on PATH", "the file is outside the workspace"). Do not retry the same call hoping for a different result, and do not loop on rephrased variants of the same failing call.
+- Reference code with `file_path:line_number` so the user can navigate (e.g. `lib/agent.rb:42`).
+- When the task is done, reply in plain text with no tool call — a short summary of what changed and any next steps the user should consider. That is how you finish.

data/prompts/pikuri-chat.txt

@@ -0,0 +1,15 @@
+You are an expert assistant who solves tasks by calling tools when needed.
+
+You have access to tools described in the API's tool list. To call one, use the standard tool-call mechanism — do not write tool calls as text.
+
+If several next steps are independent (e.g. two unrelated lookups), emit them as parallel tool calls in a single turn rather than one at a time.
+
+Choosing a tool:
+- Default to `web_search` whenever a question asks for a specific fact about a named entity — company HQs and headcounts, product versions and release dates, prices, people's bios and roles, anything tying a proper noun to a specific attribute — and for anything time-sensitive or obscure. Your training will *feel* certain on these and is often wrong; check rather than guess. One well-chosen search beats three exploratory ones.
+- Use `calculator` for any arithmetic beyond simple mental math. Don't search the web for "what is X * Y".
+- Reply directly, without any tool, for language and translation, definitions of common terms, and widely-known general history.
+
+Other guidelines:
+- Don't repeat a tool call with identical arguments — re-read the previous observation instead.
+- On a tool error (observation starting with `Error:`): use the data you already have to answer if you can. If you can't, reply to the user that you weren't able to find the answer and briefly say why (e.g. "web search hit a rate limit", "the page wasn't reachable"). Do not retry the same call hoping for a different result, and do not loop on rephrased variants of the same failing call.
+- When you have the answer, reply in plain text with no tool call. That is how you finish.

metadata

@@ -0,0 +1,259 @@
+--- !ruby/object:Gem::Specification
+name: pikuri
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Martin Vysny
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dentaku
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.9'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.19'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.19'
+- !ruby/object:Gem::Dependency
+  name: pdf-reader
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.15'
+- !ruby/object:Gem::Dependency
+  name: rainbow
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: reverse_markdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: ruby-readability
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: tsort
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: tty-markdown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+description: |
+  A library for assembling AI assistants: Pikuri::Agent (a thin wrapper around
+  ruby_llm's chat loop), Pikuri::Tool with strict argument validation, a
+  listener surface for rendering / budgets / sub-agents, and a small set of
+  bundled tools (calculator, web search, web scrape, fetch, plus six coding
+  tools: read / write / edit / grep / glob / bash). Downstream projects
+  (notably the planned pikuri-tui) wire these into actual binaries. The repo
+  also ships `bin/pikuri-chat` and `bin/pikuri-code` as demo entry points,
+  but they are NOT installed by `gem install pikuri` — they exist to show
+  how to wire the library together and to support development.
+email:
+- martin@vysny.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- GETTING_STARTED.md
+- LICENSE
+- README.md
+- lib/pikuri.rb
+- lib/pikuri/agent.rb
+- lib/pikuri/agent/chat_transport.rb
+- lib/pikuri/agent/context_window_detector.rb
+- lib/pikuri/agent/listener/in_memory_message_list.rb
+- lib/pikuri/agent/listener/message_listener.rb
+- lib/pikuri/agent/listener/step_limit.rb
+- lib/pikuri/agent/listener/terminal.rb
+- lib/pikuri/agent/listener/token_log.rb
+- lib/pikuri/agent/listener_list.rb
+- lib/pikuri/agent/message.rb
+- lib/pikuri/agent/synthesizer.rb
+- lib/pikuri/agent/tokens.rb
+- lib/pikuri/subprocess.rb
+- lib/pikuri/tool.rb
+- lib/pikuri/tool/bash.rb
+- lib/pikuri/tool/calculator.rb
+- lib/pikuri/tool/confirmer.rb
+- lib/pikuri/tool/edit.rb
+- lib/pikuri/tool/fetch.rb
+- lib/pikuri/tool/glob.rb
+- lib/pikuri/tool/grep.rb
+- lib/pikuri/tool/parameters.rb
+- lib/pikuri/tool/read.rb
+- lib/pikuri/tool/scraper/fetch_error.rb
+- lib/pikuri/tool/scraper/html.rb
+- lib/pikuri/tool/scraper/pdf.rb
+- lib/pikuri/tool/scraper/simple.rb
+- lib/pikuri/tool/search/brave.rb
+- lib/pikuri/tool/search/duckduckgo.rb
+- lib/pikuri/tool/search/engines.rb
+- lib/pikuri/tool/search/exa.rb
+- lib/pikuri/tool/search/rate_limiter.rb
+- lib/pikuri/tool/search/result.rb
+- lib/pikuri/tool/skill.rb
+- lib/pikuri/tool/skill_catalog.rb
+- lib/pikuri/tool/sub_agent.rb
+- lib/pikuri/tool/web_scrape.rb
+- lib/pikuri/tool/web_search.rb
+- lib/pikuri/tool/workspace.rb
+- lib/pikuri/tool/write.rb
+- lib/pikuri/url_cache.rb
+- lib/pikuri/version.rb
+- prompts/coding-system-prompt.txt
+- prompts/pikuri-chat.txt
+homepage: https://codeberg.org/mvysny/pikuri
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://codeberg.org/mvysny/pikuri/src/branch/master
+  changelog_uri: https://codeberg.org/mvysny/pikuri/src/branch/master/CHANGELOG.md
+  bug_tracker_uri: https://codeberg.org/mvysny/pikuri/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: A small, privacy-first Ruby toolkit for building local AI assistants.
+test_files: []