akaitsume 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: de11bca8eff9c9ffcba7f00f11d998f61ad726fa2ec11031e7489e38c4278464
+  data.tar.gz: 259a7c03cd5e11b6b53c56431fe7df0b615b36362b07bf0af520d19b70960091
+SHA512:
+  metadata.gz: 58e94b9fe21a74c9c8365579dd188b0af2fecfcb0ec3abf3f55fa64829dcc33ab78c65dd4948a0d591063777fe2ae750b3145f1cf855d2ddb4bc87f226d29cd8
+  data.tar.gz: fe343f18ce0db6cf82aaea1a2828ac56b985fb7fed6b946dff3d2f5c94cf9c5b2246ece8af7466255deaf4991e7d1f2637a5583ff0265325e6d4834e9a8966c6

data/README.md

@@ -0,0 +1,208 @@
+# Akaitsume
+
+赤い爪 — A sharp, extensible AI agent framework for Ruby built on the Anthropic SDK.
+
+## Features
+
+- **Provider abstraction** — swap LLM backends without changing agent code (Anthropic built-in, OpenAI/Ollama ready to add)
+- **Tool system** — trait-based tools with auto-discovery: Bash, Files, HTTP, Memory
+- **Memory backends** — FileStore (default) or SQLite, switchable via config
+- **Session management** — conversation continuity with token/cost tracking
+- **Hooks** — `before_tool`, `after_tool`, `on_response`, `on_error` callbacks
+- **Structured logging** — JSON logs with token counts and tool durations
+- **Thor CLI** — `run`, `chat`, `tools`, `memory` commands with auto-generated help
+
+## Installation
+
+```ruby
+# Gemfile
+gem 'akaitsume'
+```
+
+Or install directly:
+
+```sh
+gem install akaitsume
+```
+
+## Quick start
+
+```sh
+export ANTHROPIC_API_KEY=sk-...
+
+# Single prompt
+akaitsume run "list files in the current directory"
+
+# Interactive chat (with conversation memory)
+akaitsume chat
+
+# List available tools
+akaitsume tools
+
+# Show/search agent memory
+akaitsume memory show
+akaitsume memory search "ruby"
+```
+
+## Usage from Ruby
+
+```ruby
+require 'akaitsume'
+
+agent = Akaitsume::Agent.new
+
+# Simple run
+result = agent.run("What files are in the workspace?")
+puts result
+
+# With hooks
+agent.before_tool { |name, input| puts "Calling #{name}..." }
+agent.on_response { |text| puts "Got: #{text}" }
+agent.run("Create a hello.txt file")
+
+# Chat with session continuity
+session = Akaitsume::Session.new
+agent.run("Remember: my name is Mateusz", session: session)
+agent.run("What's my name?", session: session)
+
+# Sub-agents
+researcher = agent.spawn(name: "researcher", role: :researcher)
+researcher.run("Find all TODO comments in the codebase")
+```
+
+## Configuration
+
+Config is loaded from YAML, environment variables, or passed directly:
+
+```yaml
+# config/agent.yml
+model: claude-sonnet-4-20250514
+max_turns: 20
+max_tokens: 8096
+workspace: ~/.akaitsume/workspace
+memory_backend: file        # or "sqlite"
+db_path: ~/.akaitsume/akaitsume.db
+log_level: info
+```
+
+```sh
+akaitsume run "hello" --config config/agent.yml
+```
+
+Environment: `ANTHROPIC_API_KEY` is required.
+
+## Architecture
+
+![Architecture](docs/architecture.png)
+
+> Greyed-out elements (Web/Webhook entry points, streaming, retry policy, session persistence, feature flags) are planned for future phases.
+
+```
+lib/akaitsume/
+├── agent.rb              # Orchestrator (agentic loop)
+├── cli.rb                # Thor CLI
+├── config.rb             # YAML + ENV config
+├── hooks.rb              # Event system module
+├── logger.rb             # Structured JSON logging
+├── session.rb            # Conversation state + token tracking
+│
+├── provider/
+│   ├── base.rb           # Provider contract (module)
+│   ├── response.rb       # Unified response value object
+│   └── anthropic.rb      # Anthropic SDK wrapper
+│
+├── tool/
+│   ├── base.rb           # Tool contract (module)
+│   ├── registry.rb       # Tool registry
+│   ├── bash.rb           # Shell execution
+│   ├── files.rb          # File operations (with path traversal protection)
+│   ├── http.rb           # HTTP requests via Faraday
+│   └── memory_tool.rb    # LLM-facing memory read/write/search
+│
+└── memory/
+    ├── base.rb           # Memory contract (module)
+    ├── file_store.rb     # Markdown file backend (default)
+    └── sqlite_store.rb   # SQLite backend (opt-in)
+```
+
+## Extending
+
+### Custom tool
+
+```ruby
+class MyTool
+  include Akaitsume::Tool::Base
+
+  tool_name   'weather'
+  description 'Get current weather for a city'
+  input_schema({
+    type: 'object',
+    properties: {
+      city: { type: 'string', description: 'City name' }
+    },
+    required: ['city']
+  })
+
+  def call(input)
+    # Your implementation here
+    "Weather in #{input['city']}: 22C, sunny"
+  end
+end
+
+# Register it
+agent = Akaitsume::Agent.new
+registry = Akaitsume::Tool::Registry.new
+registry.register(MyTool)
+agent = Akaitsume::Agent.new(tools: registry)
+```
+
+### Custom provider
+
+```ruby
+class OllamaProvider
+  include Akaitsume::Provider::Base
+
+  provider_name 'ollama'
+
+  def chat(messages:, system:, tools:, model:, max_tokens:)
+    # Call Ollama API, return Provider::Response
+    Akaitsume::Provider::Response.new(
+      content: [...],
+      stop_reason: 'end_turn',
+      model: model,
+      usage: { input_tokens: 0, output_tokens: 0 }
+    )
+  end
+end
+
+agent = Akaitsume::Agent.new(provider: OllamaProvider.new)
+```
+
+### Custom memory backend
+
+```ruby
+class RedisStore
+  include Akaitsume::Memory::Base
+
+  def read       = # ...
+  def store(entry) = # ...
+  def replace(content) = # ...
+  def search(query) = # ...
+end
+
+agent = Akaitsume::Agent.new(memory: RedisStore.new)
+```
+
+## Dependencies
+
+| Gem | Purpose |
+|-----|---------|
+| `anthropic` | Anthropic Claude SDK |
+| `zeitwerk` | Autoloading |
+| `faraday` | HTTP tool |
+| `sqlite3` | SQLite memory backend |
+| `thor` | CLI framework |
+
+## License
+
+MIT

data/bin/akaitsume

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/akaitsume'
+
+Akaitsume::CLI.start(ARGV)

data/lib/akaitsume/agent.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Akaitsume
+  class Agent
+    include Hooks
+
+    attr_reader :name, :role, :config, :logger
+
+    def initialize(name: 'akaitsume', role: :orchestrator, config: Config.load,
+                   provider: nil, tools: nil, memory: nil, logger: nil)
+      @name     = name
+      @role     = role
+      @config   = config
+      @provider = provider || Provider::Anthropic.new(api_key: config.api_key)
+      @memory   = memory || build_memory(config, name)
+      @tools    = tools || Tool::Registry.default_for(config, memory: @memory)
+      @logger   = logger || Logger.new(level: config.log_level)
+      init_hooks
+    end
+
+    # Spawn a sub-agent with its own tools and memory
+    def spawn(name:, role:, tools: nil)
+      self.class.new(
+        name: name,
+        role: role,
+        config: @config,
+        provider: @provider,
+        tools: tools,
+        memory: build_memory(@config, name),
+        logger: @logger
+      )
+    end
+
+    # Run the agent loop.
+    # Pass a Session for conversation continuity (chat mode).
+    # Without a session, creates a temporary one for this single run.
+    def run(prompt, system: nil, session: nil, &block)
+      session ||= Session.new(system_prompt: system || default_system_prompt)
+      sys = session.system_prompt || system || default_system_prompt
+
+      inject_memory_and_prompt(session, prompt)
+
+      loop do
+        raise MaxTurnsError, "Exceeded max_turns (#{@config.max_turns})" if session.turn_count >= @config.max_turns
+
+        response = call_provider(sys, session)
+        session.add_assistant(response.content)
+        session.track_usage(response)
+
+        if response.tool_use?
+          tool_results = dispatch_tools(response.content)
+          session.add_tool_results(tool_results)
+        else
+          text = extract_text(response.content)
+          fire(:on_response, text)
+          block&.call(text)
+          return text
+        end
+      end
+    rescue StandardError => e
+      fire(:on_error, e)
+      raise
+    end
+
+    private
+
+    def build_memory(config, agent_name)
+      case config.memory_backend
+      when 'sqlite'
+        Memory::SqliteStore.new(db_path: config.db_path, agent_name: agent_name)
+      else
+        Memory::FileStore.new(dir: config.memory_dir, agent_name: agent_name)
+      end
+    end
+
+    def inject_memory_and_prompt(session, prompt)
+      content = if (mem = @memory.read)
+                  "<memory>\n#{mem}\n</memory>\n\n#{prompt}"
+                else
+                  prompt
+                end
+      session.add_user(content)
+    end
+
+    def call_provider(sys, session)
+      @logger.debug('api_call', model: @config.model, messages: session.messages.size)
+
+      response = @provider.chat(
+        model: @config.model,
+        max_tokens: @config.max_tokens,
+        system: sys,
+        tools: @tools.api_definitions,
+        messages: session.messages
+      )
+
+      @logger.info('api_response',
+                   stop_reason: response.stop_reason,
+                   input_tokens: response.input_tokens,
+                   output_tokens: response.output_tokens)
+
+      response
+    end
+
+    def default_system_prompt
+      parts = ["You are #{@name}, a #{@role} AI agent."]
+      parts << 'You can delegate tasks to sub-agents.' if @role == :orchestrator
+      parts << 'Be concise, precise, and always complete your task.'
+      parts.join("\n")
+    end
+
+    def dispatch_tools(content_blocks)
+      content_blocks.filter_map do |block|
+        next unless block.type == 'tool_use'
+
+        tool = @tools[block.name]
+
+        fire(:before_tool, block.name, block.input)
+        @logger.debug('tool_call', tool: block.name)
+
+        t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        result = tool.execute(block.input)
+        duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0) * 1000).round
+
+        fire(:after_tool, block.name, result)
+        @logger.debug('tool_result', tool: block.name, duration_ms: duration_ms)
+
+        {
+          type: 'tool_result',
+          tool_use_id: block.id,
+          content: [result]
+        }
+      end
+    end
+
+    def extract_text(content_blocks)
+      content_blocks
+        .select { |b| b.type == 'text' }
+        .map(&:text)
+        .join
+    end
+  end
+end

data/lib/akaitsume/cli.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require 'thor'
+
+module Akaitsume
+  class CLI < Thor
+    class_option :config, type: :string, desc: 'Path to config YAML file'
+
+    desc 'run PROMPT', 'Run agent with a single prompt'
+    method_option :model, type: :string, desc: 'Override model name'
+    def run_task(prompt)
+      agent = build_agent
+      agent.before_tool { |name, input| say "  \u2192 [#{name}] #{input.inspect}", :cyan }
+      agent.after_tool  { |name, _result| say "  \u2190 [#{name}]", :cyan }
+
+      say "\n\xF0\x9F\x94\xB4 akaitsume\n\n"
+      result = agent.run(prompt)
+      say result
+    end
+    map 'run' => :run_task
+
+    desc 'chat', 'Interactive chat mode'
+    def chat
+      agent   = build_agent
+      session = Session.new
+
+      agent.before_tool { |name, _input| $stdout.print "  \u2192 [#{name}] " }
+      agent.after_tool  { |name, _result| $stdout.puts "\u2190 [#{name}]" }
+
+      say "\xF0\x9F\x94\xB4 akaitsume chat (Ctrl+C or 'exit' to quit)\n\n"
+
+      loop do
+        print '> '
+        input = $stdin.gets&.chomp
+        break if input.nil? || input == 'exit'
+        next  if input.empty?
+
+        result = agent.run(input, session: session)
+        say "\n#{result}\n\n"
+      end
+
+      say "\nSession: #{session.turn_count} turns, #{session.total_tokens} tokens"
+    rescue Interrupt
+      say "\n\nSession: #{session.turn_count} turns, #{session.total_tokens} tokens"
+    end
+
+    desc 'tools', 'List registered tools'
+    def tools
+      cfg      = load_config
+      memory   = build_memory(cfg)
+      registry = Tool::Registry.default_for(cfg, memory: memory)
+
+      registry.names.each { |n| say "  \u2022 #{n}" }
+    end
+
+    desc 'memory SUBCOMMAND', 'Memory operations'
+    subcommand 'memory', Class.new(Thor) {
+      namespace 'memory'
+
+      desc 'show [AGENT]', 'Show agent memory'
+      def show(agent_name = 'akaitsume')
+        cfg   = parent_load_config
+        store = parent_build_memory(cfg, agent_name)
+        say store.read || '(empty)'
+      end
+
+      desc 'search QUERY [AGENT]', 'Search agent memory'
+      def search(query, agent_name = 'akaitsume')
+        cfg   = parent_load_config
+        store = parent_build_memory(cfg, agent_name)
+        say store.search(query)
+      end
+
+      no_commands do
+        def parent_load_config
+          path = parent_options[:config]
+          path ? Config.load(path: path) : Config.load
+        end
+
+        def parent_build_memory(cfg, agent_name = 'akaitsume')
+          case cfg.memory_backend
+          when 'sqlite'
+            Memory::SqliteStore.new(db_path: cfg.db_path, agent_name: agent_name)
+          else
+            Memory::FileStore.new(dir: cfg.memory_dir, agent_name: agent_name)
+          end
+        end
+      end
+    }
+
+    no_commands do
+      def load_config
+        path = options[:config]
+        cfg_hash = {}
+        cfg_hash[:model] = options[:model] if options[:model]
+
+        if path
+          Config.load(path: path)
+        else
+          Config.new(cfg_hash)
+        end
+      end
+
+      def build_memory(cfg, agent_name = 'akaitsume')
+        case cfg.memory_backend
+        when 'sqlite'
+          Memory::SqliteStore.new(db_path: cfg.db_path, agent_name: agent_name)
+        else
+          Memory::FileStore.new(dir: cfg.memory_dir, agent_name: agent_name)
+        end
+      end
+
+      def build_agent
+        cfg = load_config
+        Agent.new(config: cfg)
+      end
+    end
+  end
+end

data/lib/akaitsume/config.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'fileutils'
+
+module Akaitsume
+  class Config
+    DEFAULTS = {
+      model: 'claude-opus-4-6',
+      max_turns: 20,
+      max_tokens: 8096,
+      workspace: Dir.home + '/.akaitsume/workspace',
+      memory_dir: Dir.home + '/.akaitsume/memory',
+      memory_backend: 'file',
+      db_path: Dir.home + '/.akaitsume/akaitsume.db',
+      log_level: 'info'
+    }.freeze
+
+    attr_reader :model, :max_turns, :max_tokens, :workspace,
+                :memory_dir, :memory_backend, :db_path, :log_level, :api_key
+
+    def self.load(path: nil)
+      file_cfg = path ? YAML.safe_load_file(path, symbolize_names: true) : {}
+      new(file_cfg)
+    end
+
+    def initialize(overrides = {})
+      cfg = DEFAULTS.merge(overrides)
+      @api_key        = ENV.fetch('ANTHROPIC_API_KEY') { raise ConfigError, 'ANTHROPIC_API_KEY not set' }
+      @model          = cfg[:model]
+      @max_turns      = cfg[:max_turns].to_i
+      @max_tokens     = cfg[:max_tokens].to_i
+      @workspace      = cfg[:workspace]
+      @memory_dir     = cfg[:memory_dir]
+      @memory_backend = cfg[:memory_backend].to_s
+      @db_path        = cfg[:db_path]
+      @log_level      = cfg[:log_level]
+
+      FileUtils.mkdir_p(@workspace)
+      FileUtils.mkdir_p(@memory_dir)
+    end
+  end
+end

data/lib/akaitsume/hooks.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Akaitsume
+  module Hooks
+    EVENTS = %i[before_tool after_tool on_response on_error].freeze
+
+    def self.included(base)
+      base.define_method(:init_hooks) do
+        @hooks = EVENTS.each_with_object({}) { |e, h| h[e] = [] }
+      end
+    end
+
+    EVENTS.each do |event|
+      define_method(event) do |&block|
+        @hooks[event] << block
+      end
+    end
+
+    private
+
+    def fire(event, *args)
+      @hooks.fetch(event, []).each { |h| h.call(*args) }
+    end
+  end
+end

data/lib/akaitsume/logger.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+module Akaitsume
+  class Logger
+    LEVELS = { debug: 0, info: 1, warn: 2, error: 3 }.freeze
+
+    def initialize(level: :info, output: $stderr)
+      @level  = LEVELS.fetch(level.to_sym, 1)
+      @output = output
+    end
+
+    def debug(message, **context) = log(:debug, message, **context)
+    def info(message, **context)  = log(:info, message, **context)
+    def warn(message, **context)  = log(:warn, message, **context)
+    def error(message, **context) = log(:error, message, **context)
+
+    private
+
+    def log(level, message, **context)
+      return if LEVELS[level] < @level
+
+      entry = {
+        ts: Time.now.iso8601,
+        level: level,
+        msg: message
+      }
+      entry.merge!(context) unless context.empty?
+
+      @output.puts(JSON.generate(entry))
+    end
+  end
+end

data/lib/akaitsume/memory/base.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Akaitsume
+  module Memory
+    module Base
+      # Returns full memory content or nil if empty.
+      def read
+        raise NotImplementedError, "#{self.class}#read not implemented"
+      end
+
+      # Appends an entry to memory.
+      def store(entry)
+        raise NotImplementedError, "#{self.class}#store not implemented"
+      end
+
+      # Replaces entire memory content.
+      def replace(content)
+        raise NotImplementedError, "#{self.class}#replace not implemented"
+      end
+
+      # Searches memory for a query string, returns matching results.
+      def search(query)
+        raise NotImplementedError, "#{self.class}#search not implemented"
+      end
+    end
+  end
+end

data/lib/akaitsume/memory/file_store.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Akaitsume
+  module Memory
+    class FileStore
+      include Base
+
+      MEMORY_FILE = 'MEMORY.md'
+
+      def initialize(dir:, agent_name: 'agent')
+        @path = File.join(dir, "#{agent_name}.md")
+        FileUtils.mkdir_p(dir)
+        FileUtils.touch(@path) unless File.exist?(@path)
+      end
+
+      # Returns full memory content (injected into system prompt)
+      def read
+        content = File.read(@path).strip
+        content.empty? ? nil : content
+      end
+
+      # Appends a timestamped entry
+      def store(entry)
+        File.open(@path, 'a') do |f|
+          f.puts "\n## #{Time.now.strftime('%Y-%m-%d %H:%M')}\n#{entry.strip}\n"
+        end
+      end
+
+      # Replaces entire memory (for summarization)
+      def replace(content)
+        File.write(@path, content.to_s.strip + "\n")
+      end
+
+      # Simple keyword search
+      def search(query)
+        lines = File.readlines(@path)
+        matches = lines.each_with_object([]).with_index do |(line, acc), i|
+          acc << "L#{i + 1}: #{line.chomp}" if line.downcase.include?(query.downcase)
+        end
+        matches.empty? ? "(no matches for '#{query}')" : matches.join("\n")
+      end
+    end
+  end
+end