pikuri 0.0.1 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ce82e87d9498175b524fae4b97d8409758d8fe18783bd7084ae79afd606c56a
-  data.tar.gz: a17444b138a83252172ba0bcaa9d99129642cef0be2e1307bcc0b9203092ebb8
+  metadata.gz: 8738b90aabdb724518baa950866de9b8719a6e45e53580662bf4926e16bdbd60
+  data.tar.gz: 1df5f75e1290b1c390a6cd858ce9d0d45062299a9a6a0624598e99bdea47e77c
 SHA512:
-  metadata.gz: 5620bfd3290ea12b6069375382c1e79e769a7a2822d94b91bc166c2d0ac50ea41a2b75fd618ff006ac4500398da05ab9d0f970b123e44ef2a4c6f01e1096dd4d
-  data.tar.gz: 995b317bce1952d161c2c4e0088eb92ee9cf7788252c7496949d14633e9126acfc4cedfb7a5f105f9ab4a6e359d63b41cce5d3246cc113d334c07ab259218862
+  metadata.gz: fc0724357798692147811c9f138c73feb8081125bf1d3462ad1ba8463894fa7acd236c3813782fc8e96f899d0e8e3edda6db7edc10f252c07213c0b5bad58d7d
+  data.tar.gz: 9feaf1d95c74c0cee37c22e18b8771321870d8ab3c6efb4fd06262f7fd51d013f842c44c0272c6c14c20b6fc71047d1d3bfe80fbbb9102df11e0b4039bc2eb6c

data/README.md

@@ -1,193 +1,57 @@
-# pikuri
+# pikuri (metagem)
 
-A small Ruby AI assistant you run on your own machine. `bin/pikuri-chat`
-is a general-purpose chatbot with a calculator, web search, web
-scraping, and a fetch tool — wired by default to a
-[llama.cpp](https://github.com/ggml-org/llama.cpp) server running
-locally, so the conversation never leaves your computer unless the
-model itself decides to call a tool.
+The convenience bundle for the
+[pikuri](https://codeberg.org/mvysny/pikuri) AI-assistant toolkit:
+`gem install pikuri` brings in every pikuri-* gem in one shot, and
+`require 'pikuri'` boots them all.
 
-## Quick start
+This gem ships no Ruby code of its own — its `lib/pikuri.rb` is
+seven `require` lines, one per sibling.
 
-```sh
-git clone https://codeberg.org/mvysny/pikuri.git
-cd pikuri
-
-# Ruby 3.x + bundler (Ubuntu/Debian)
-sudo apt install ruby ruby-bundler
-
-bundle install
-
-./bin/pikuri-chat "What is 17 * 23?"
-```
-
-The first run won't get far — pikuri-chat needs a model behind it. See
-[GETTING_STARTED.md](GETTING_STARTED.md) for the full walkthrough:
-installing `llama.cpp`, pulling a model, starting `llama-server`, and
-asking your first question.
-
-## Using pikuri as a library
-
-Pikuri is shipped as a Ruby gem you can use in your own project. The
-recommended path: **first** play with `bin/pikuri-chat`, inspect the
-sources, get a feel for the shape — *then* pull pikuri into your
-project as a library:
+## Install
 
 ```ruby
-# In your Gemfile
+# Gemfile
 gem 'pikuri'
 ```
 
-A minimal wiring — single agent, default `llama.cpp` transport, the
-bundled calculator + web-search tools, the same system prompt
-`pikuri-chat` uses:
-
-```ruby
-require 'pikuri'
-
-RubyLLM.configure do |c|
-  c.openai_api_base = 'http://localhost:8080/v1'  # llama.cpp default
-  c.openai_api_key  = 'not-needed'
-end
-
-agent = Pikuri::Agent.new(
-  transport: Pikuri::Agent::ChatTransport.new(
-    model: 'unsloth/Qwen3.6-35B-A3B-GGUF',
-    provider: :openai,
-    assume_model_exists: true
-  ),
-  system_prompt: Pikuri.prompt(:'pikuri-chat'),
-  tools: [Pikuri::Tool::CALCULATOR, Pikuri::Tool::WEB_SEARCH],
-  listeners: Pikuri::Agent::ListenerList.new([
-    Pikuri::Agent::Listener::Terminal.new,
-    Pikuri::Agent::Listener::StepLimit.new(max: 20)
-  ])
-)
-
-agent.run_loop(user_message: 'What is 17 * 23?')
-```
-
-`bin/pikuri-chat` and `bin/pikuri-code` in this repo are the canonical
-working examples — they're dev/demo scripts (not installed by
-`gem install pikuri`), but they're the easiest place to crib wiring
-from. The bundled system prompts under `prompts/` are loadable as a
-starting point via `Pikuri.prompt(name)`.
-
-## Why this exists
-
-The existing self-hosted agent stacks have grown big and now have a
-steep learning curve — a privacy-conscious user arriving fresh hits a
-wall of JSON configuration before the first conversation. Pikuri is
-the deliberate counter-move:
-
-- **Privacy-first.** Defaults wire a local `llama.cpp` server. No
-  cloud account, no API key, no telemetry, no request leaving the
-  machine — unless you explicitly opt in by configuring an external
-  provider, or the model calls a network tool like `web_search`.
-- **Simple.** Two short scripts, sane defaults, no config file required
-  to get the first conversation going.
-- **Gentle learning curve.** Defaults work without a config file. The
-  surface area grows as you grow into it: start by chatting, then add
-  a search API key when you want better results, then edit the system
-  prompt when you want to specialise behaviour.
-- **Teaches you how to use it.** [GETTING_STARTED.md](GETTING_STARTED.md)
-  walks you from zero — a fresh checkout, no model running — to a
-  working personal assistant: installing the local model server,
-  asking your first question, understanding what each bundled tool
-  does, and choosing a search backend that matches your privacy
-  comfort level.
+Transitively installs:
+- [`pikuri-core`](../pikuri-core/README.md) — the foundation
+- [`pikuri-skills`](../pikuri-skills/README.md) — Agent Skills support
+- [`pikuri-workspace`](../pikuri-workspace/README.md) — filesystem tools
+- [`pikuri-code`](../pikuri-code/README.md) — Bash + `bin/pikuri-code`
+- [`pikuri-mcp`](../pikuri-mcp/README.md) — MCP support
+- [`pikuri-subagents`](../pikuri-subagents/README.md) — `agent` tool + bundled personas + `bin/pikuri-minions`
+- [`pikuri-assistant`](../pikuri-assistant/README.md) — `bin/pikuri-assistant`
 
-## Curious how the agentic loop actually works?
+All version-locked together — bumping the metagem requires the
+matching sibling versions.
 
-Pikuri sits on top of [ruby_llm](https://rubyllm.com), which owns the
-Thought → Tool-call → Observation loop. If you want to *learn* how
-that loop works internally — minimal code, no extension surface,
-nothing to wade through — read
-[agentic-loop-demo](https://codeberg.org/mvysny/agentic-loop-demo).
-It's the same author's small didactic project, written precisely so
-the source is the lesson. Pikuri is the production-shaped sibling:
-same loop, plus tools, listeners, sub-agents, and ergonomics.
+## When NOT to use this gem
 
-# More Substance
+Privacy-conscious users who care about a minimal dependency tree
+should install just the lean core + the extensions they actually
+need:
 
-pikuri-chat builds your understanding of pikuri underpinnings, but it's just a toy.
-The real fun begins now.
-
-## pikuri-code
-
-An in-repo coding agent in the spirit of Claude Code, opencode, or
-pi-code — but kept deliberately small so you can read the sources in
-an evening. Wire-by-wire it's the same `Pikuri::Agent` as
-`pikuri-chat`, with a different system prompt and a different toolset:
-`read`, `write`, `edit`, `grep`, `glob`, `bash`, plus the web tools
-and the calculator. Sub-agents are enabled, and any
-[Agent Skills](https://agentskills.io/specification) discovered under
-`.pikuri/skills`, `.claude/skills`, `.agents/skills` (project or home)
-get exposed to the model on demand.
-
-Run it from the root of the repo you want it to work in:
-
-```sh
-cd ~/code/your-project
-/path/to/pikuri/bin/pikuri-code
-```
-
-You'll land in a REPL — type a request at the `>` prompt, hit enter,
-and the agent will start reading files, running commands, and editing
-code to satisfy it. Ctrl+D (or Ctrl+C) exits. You can also pass an
-initial message on the command line:
-
-```sh
-/path/to/pikuri/bin/pikuri-code "find the failing spec and fix it"
+```ruby
+gem 'pikuri-core'
+gem 'pikuri-mcp'     # if they want MCP
+gem 'pikuri-skills'  # if they want skills
+# ... etc.
 ```
 
-The first time the agent wants to write a file or run a shell command,
-it prompts you on the terminal (`(y/n)?`). Read what it's about to do
-before you say yes. If an `AGENTS.md` or `CLAUDE.md` exists at the
-workspace root, it's prepended to the system prompt as project
-context.
-
-### Security: this is a tech demo, treat it accordingly
-
-**Do not run `pikuri-code` against a sensitive checkout on a machine
-that holds secrets you care about.** It is a working demo of the
-coding-agent shape, *not* a hardened tool. The threat model has
-glaring holes:
-
-- **No sandbox.** The `bash` tool runs commands as your user, with
-  your environment, your `$HOME`, your `~/.ssh`, your shell history,
-  your browser cookies, your cloud CLI credentials — all reachable.
-  An LLM that's been prompt-injected (e.g. by a malicious README it
-  scraped, a poisoned dependency, or a crafted file in the repo) can
-  ask to run `cat ~/.ssh/id_ed25519 | curl -X POST ...` and the only
-  thing standing between that and exfiltration is *you* reading the
-  confirmation prompt carefully. The workspace lock applies to
-  pikuri's own `read`/`write`/`edit`/`grep`/`glob` tools — it does
-  **not** apply to `bash`, which can `cat`, `cp`, `scp`, `curl`
-  anything the OS lets your user touch.
-- **`--yolo` auto-approves everything.** That flag exists for use
-  *inside* a disposable container or VM. Running `--yolo` on your
-  laptop is equivalent to handing the model a root shell. Don't.
-- **Network tools fetch arbitrary URLs.** `web_search`, `web_scrape`,
-  and `fetch` are happy to pull whatever the model asks for, and the
-  content of those pages then becomes part of the conversation —
-  classic indirect prompt-injection surface.
-- **No audit log of approved actions.** Once you approve a `bash`
-  command it runs; there's no separate record beyond your scrollback.
-
-In short: run it inside a Docker container, a dev container, a VM, a
-fresh user account — anywhere you'd be fine with a stranger having a
-shell. The sandboxing story is a known gap and tracked as future
-work (see `IDEAS.md`); until it lands, **assume the agent can do
-anything your user can do**, and approve prompts on that basis.
-
-## pikuri-assistant
-
-Has access to your private documents, can read and respond to e-mails, remembers
-stuff. TODO implemented in the future.
-
-## Tests
-
-```sh
-bundle exec rspec
-```
+`pikuri-core` is the minimal install. Adding `pikuri-mcp` adds
+exactly one new runtime gem (`mcp`); `pikuri-workspace` /
+`pikuri-skills` / `pikuri-code` / `pikuri-subagents` /
+`pikuri-assistant` add nothing beyond pikuri's own gems. The dep
+tree stays auditable.
+
+## Further reading
+
+- **Narrative walkthrough:** the [pikuri
+  guide](../docs/guide/) — a short sequential book covering the
+  whole family, chapter by chapter.
+- **API reference:** browse the YARD docs at
+  <https://rubydoc.info/gems/pikuri> (once published), or run
+  `bundle exec yard` in any sibling gem's directory for a local
+  copy of that gem's docs.

data/lib/pikuri.rb

@@ -1,165 +1,19 @@
 # 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).
+# +pikuri+ metagem entry file. Boots every sibling gem in dependency
+# order so +require 'pikuri'+ pulls in the whole pikuri-* family in
+# one shot. Each sibling owns its own Zeitwerk loader + PROMPT_DIRS
+# registration; we just need them loaded.
 #
-# == 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
+# Privacy-conscious users who want a minimal dependency tree should
+# install +pikuri-core+ directly and skip this metagem.
+require 'pikuri-core'
+require 'pikuri-skills'
+require 'pikuri-tasks'
+require 'pikuri-memory'
+require 'pikuri-workspace'
+require 'pikuri-mcp'
+require 'pikuri-code'
+require 'pikuri-subagents'
+require 'pikuri-vectordb'
+require 'pikuri-assistant'