kodo-bot 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 65b530bf1300200558b1ece1066f34868e8b97c675f911b1d2c9c005e46cdb46
+  data.tar.gz: f482bb17f09d346b3b21f1de00e88cea25f7c8685e14d7b1319459442b05148f
+SHA512:
+  metadata.gz: 6f19367ea55d9172468c4b3b3810f95a08102b09829bb7460d461278bf6b72f692a383d68ae9d91dcc661d69ecb28be25a4654e3a1f5e5f813f41fcb2be7bf7c
+  data.tar.gz: a5c012da9b6ffd653c1fa042bb983e8d245c22edbf85d9af30ab15b4cccfc8e85a170a90a54eb5ad52fc20bb60384cdce2de10924e847ef347e0e8b6b6c7bf81

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Freedom Dumlao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,157 @@
+# 🥁 Kodo
+
+**Kodo** (鼓動, "heartbeat") is an open-source, security-first AI agent framework
+written in Ruby. It runs locally on your hardware and communicates through the
+messaging platforms you already use.
+
+Unlike cloud-hosted AI assistants, Kodo keeps your data on your machine, enforces
+capability-based permissions on every action, and gives you full control over
+what your agent can and cannot do.
+
+> **Status:** Early development. Phase 1 — Foundation.
+
+## Quick Start
+
+### Prerequisites
+
+- Ruby 3.2+
+- An API key for any supported LLM provider:
+  [Anthropic](https://console.anthropic.com/),
+  [OpenAI](https://platform.openai.com/),
+  [Gemini](https://aistudio.google.com/),
+  [Ollama](https://ollama.com/) (free, local), and
+  [many more](https://rubyllm.com/)
+- A Telegram Bot Token (message [@BotFather](https://t.me/BotFather) on Telegram)
+
+### Setup
+
+```bash
+git clone https://github.com/apiguy/kodo.git
+cd kodo
+bundle install
+
+# Initialize Kodo's home directory
+ruby bin/kodo init
+
+# Set your LLM API key (pick any provider)
+export ANTHROPIC_API_KEY="sk-ant-..."
+# or: export OPENAI_API_KEY="sk-..."
+# or: just run Ollama locally — no key needed
+
+# Set up Telegram
+export TELEGRAM_BOT_TOKEN="123456:ABC-DEF..."
+
+# Enable Telegram and set your model in the config
+# Edit ~/.kodo/config.yml
+
+# Start Kodo
+ruby bin/kodo start
+```
+
+Now message your bot on Telegram. Kodo is alive.
+
+### CLI Chat (no Telegram needed)
+
+```bash
+export ANTHROPIC_API_KEY="sk-ant-..."  # or any provider key
+ruby bin/kodo chat
+```
+
+## Commands
+
+```
+kodo start     Start the Kodo daemon
+kodo chat      Chat with Kodo directly in the terminal
+kodo status    Show daemon status
+kodo init      Create default config in ~/.kodo/
+kodo version   Show version
+kodo help      Show help
+```
+
+## How It Works
+
+Kodo runs a **heartbeat loop** — a periodic cycle that polls your messaging
+channels for new messages, processes them through an LLM, and sends responses
+back. This heartbeat is what makes Kodo an agent rather than a chatbot: it runs
+continuously, can notice things, and will eventually take proactive action on
+your behalf.
+
+```
+Your Phone (Telegram) ←→ Telegram API ←→ Kodo Daemon ←→ Anthropic Claude
+                                              │
+                                         Memory Store
+                                        (conversations,
+                                         audit trail)
+```
+
+## Architecture
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the full system design, component
+details, and phase roadmap.
+
+## Configuration
+
+Kodo stores its config and data in `~/.kodo/`:
+
+```
+~/.kodo/
+├── config.yml              # LLM provider and channel settings
+├── persona.md              # Agent personality and tone (make Kodo yours)
+├── user.md                 # Tell Kodo about yourself
+├── pulse.md                # What to notice during idle beats
+├── origin.md               # First-run onboarding conversation
+└── memory/
+    ├── conversations/      # Chat history (per-conversation JSON)
+    ├── knowledge/          # Long-term memory (future)
+    └── audit/              # Daily audit logs (JSONL)
+```
+
+### Prompt Files
+
+Kodo's personality is defined by **plain Markdown files**, not code. Edit
+them to make the agent yours:
+
+- **`persona.md`** — How Kodo talks. Tone, style, opinions. "Respond like
+  a senior engineer doing code review" is more useful than "be helpful."
+- **`user.md`** — Who you are. Name, role, timezone, current projects.
+  Helps Kodo give contextual answers.
+- **`pulse.md`** — What Kodo should pay attention to during idle heartbeat
+  cycles. "Remind me about standup at 9:45am" or "summarize unread messages
+  if more than 5 accumulate."
+- **`origin.md`** — Runs on first conversation only. Kodo introduces itself
+  and helps you set up.
+
+These files are **advisory** — they shape behavior but cannot override Kodo's
+hardcoded security invariants (no data exfiltration, no prompt injection
+compliance, no impersonation).
+
+Secrets (API keys, bot tokens) are never stored in config files. Instead, config
+references environment variable names using the `_env` suffix convention:
+
+```yaml
+llm:
+  api_key_env: ANTHROPIC_API_KEY  # reads $ANTHROPIC_API_KEY at runtime
+```
+
+## Security
+
+Kodo is being built security-first. The current phase has basic protections;
+future phases will add:
+
+- **Capability-based permissions** — skills declare what they need, you grant
+  scoped access
+- **Sandboxed skill execution** — skills run in isolated processes
+- **Signed skills** — cryptographic verification before loading any skill
+- **Encrypted memory** — conversation history encrypted at rest
+- **Audit trail** — every action logged with what triggered it and what
+  permissions were used
+
+## License
+
+MIT
+
+## Links
+
+- **Website:** [kodo.bot](https://kodo.bot)
+- **Architecture:** [ARCHITECTURE.md](ARCHITECTURE.md)
+- **Development Guide:** [CLAUDE.md](CLAUDE.md)

data/bin/kodo

@@ -0,0 +1,160 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/kodo"
+
+module Kodo
+  class CLI
+    COMMANDS = {
+      "start"   => "Start the Kodo daemon",
+      "chat"    => "Chat with Kodo directly in the terminal",
+      "status"  => "Show daemon status",
+      "version" => "Show version",
+      "init"    => "Create default config and prompt files in ~/.kodo/",
+      "help"    => "Show this help"
+    }.freeze
+
+    def run(args = ARGV)
+      command = args.first || "help"
+
+      case command
+      when "start"   then start(args)
+      when "chat"    then chat
+      when "init"    then init
+      when "version" then puts "kodo v#{VERSION}"
+      when "status"  then status
+      else help
+      end
+    end
+
+    private
+
+    def start(args)
+      interval = nil
+      args.each do |arg|
+        if arg.start_with?("--heartbeat-interval=")
+          interval = arg.split("=", 2).last.to_i
+        end
+      end
+      if (idx = args.index("--heartbeat-interval")) && !args[idx + 1]&.start_with?("--")
+        interval = args[idx + 1]&.to_i
+      end
+
+      daemon = Daemon.new(heartbeat_interval: interval)
+      daemon.start!
+    end
+
+    def chat
+      Config.ensure_home_dir!
+      assembler = PromptAssembler.new
+      assembler.ensure_default_files!
+      LLM.configure!(Kodo.config)
+
+      puts "🥁 Kodo v#{VERSION} — direct chat mode"
+      puts "   Model: #{Kodo.config.llm_model}"
+      puts "   Type your message and press Enter. Ctrl+C to quit.\n\n"
+
+      memory = Memory::Store.new
+      audit = Memory::Audit.new
+      router = Router.new(memory: memory, audit: audit, prompt_assembler: assembler)
+      console = Channels::Console.new
+      console.connect!
+
+      loop do
+        print "\e[33mYou:\e[0m "
+        input = $stdin.gets&.strip
+        break if input.nil? || input.empty?
+
+        message = Message.new(
+          channel_id: "console",
+          sender: :user,
+          content: input,
+          metadata: { chat_id: "console" }
+        )
+
+        response = router.route(message, channel: console)
+        console.send_message(response)
+      end
+    rescue Interrupt
+      puts "\n\n🥁 Goodbye."
+    end
+
+    def init
+      Config.ensure_home_dir!
+      PromptAssembler.new.ensure_default_files!
+
+      puts "✅ Kodo home directory: #{Kodo.home_dir}"
+      puts ""
+      puts "   Created files:"
+      puts "   📋 config.yml     — LLM provider and channel settings"
+      puts "   🎭 persona.md     — personality and tone (make Kodo yours)"
+      puts "   👤 user.md        — tell Kodo about yourself"
+      puts "   💓 pulse.md       — what to notice during idle beats"
+      puts "   🌱 origin.md      — first-run onboarding conversation"
+      puts ""
+      puts "   Quick start:"
+      puts "   1. Set an LLM API key (e.g. ANTHROPIC_API_KEY, OPENAI_API_KEY)"
+      puts "   2. Set TELEGRAM_BOT_TOKEN (get one from @BotFather on Telegram)"
+      puts "   3. Enable Telegram in ~/.kodo/config.yml"
+      puts "   4. Edit ~/.kodo/persona.md to customize Kodo's personality"
+      puts "   5. Run: kodo start"
+      puts ""
+      puts "   Supported LLM providers:"
+      puts "   Anthropic, OpenAI, Gemini, DeepSeek, Mistral, Ollama,"
+      puts "   OpenRouter, Perplexity, xAI, and any OpenAI-compatible API"
+    end
+
+    def status
+      puts "🥁 Kodo v#{VERSION}"
+      puts ""
+      puts "   Home:   #{Kodo.home_dir}"
+      puts "   Config: #{File.exist?(Config.config_path) ? "✅" : "❌"} #{Config.config_path}"
+      puts ""
+
+      # Prompt files
+      puts "   Prompt files:"
+      %w[persona.md user.md pulse.md origin.md].each do |f|
+        path = File.join(Kodo.home_dir, f)
+        status = File.exist?(path) ? "✅" : "  "
+        puts "   #{status} #{f}"
+      end
+      puts ""
+
+      # Provider keys
+      puts "   LLM providers:"
+      {
+        "ANTHROPIC_API_KEY"  => "Anthropic",
+        "OPENAI_API_KEY"     => "OpenAI",
+        "GEMINI_API_KEY"     => "Gemini",
+        "OLLAMA_API_BASE"    => "Ollama"
+      }.each do |env, name|
+        s = ENV[env] ? "✅ set" : "  not set"
+        puts "   #{s.start_with?("✅") ? "✅" : "  "} #{name.ljust(12)} (#{env})"
+      end
+      puts ""
+
+      puts "   Telegram: #{ENV["TELEGRAM_BOT_TOKEN"] ? "✅ set" : "❌ TELEGRAM_BOT_TOKEN missing"}"
+    end
+
+    def help
+      puts "🥁 Kodo v#{VERSION} — your personal AI agent"
+      puts ""
+      puts "Usage: kodo <command> [options]"
+      puts ""
+      COMMANDS.each do |cmd, desc|
+        puts "  %-12s %s" % [cmd, desc]
+      end
+      puts ""
+      puts "Options:"
+      puts "  --heartbeat-interval=N   Set heartbeat interval in seconds (default: 60)"
+      puts ""
+      puts "Prompt files in ~/.kodo/:"
+      puts "  persona.md    Your agent's personality and tone"
+      puts "  user.md       Tell Kodo about yourself"
+      puts "  pulse.md      What to notice during idle beats"
+      puts "  origin.md     First-run onboarding conversation"
+    end
+  end
+end
+
+Kodo::CLI.new.run

data/config/default.yml

@@ -0,0 +1,40 @@
+---
+daemon:
+  port: 7377
+  heartbeat_interval: 60
+
+llm:
+  # Any model supported by your configured providers
+  # Examples: claude-sonnet-4-20250514, gpt-4o, gemini-2.5-pro, llama3:8b
+  model: claude-sonnet-4-20250514
+
+  # Add API keys for any providers you want to use.
+  # Only configure the ones you need — Kodo won't complain about the rest.
+  providers:
+    anthropic:
+      api_key_env: ANTHROPIC_API_KEY
+    # openai:
+    #   api_key_env: OPENAI_API_KEY
+    # gemini:
+    #   api_key_env: GEMINI_API_KEY
+    # deepseek:
+    #   api_key_env: DEEPSEEK_API_KEY
+    # mistral:
+    #   api_key_env: MISTRAL_API_KEY
+    # openrouter:
+    #   api_key_env: OPENROUTER_API_KEY
+    # ollama:
+    #   api_base: http://localhost:11434  # no API key needed
+
+channels:
+  telegram:
+    enabled: false
+    bot_token_env: TELEGRAM_BOT_TOKEN
+
+memory:
+  encryption: false
+  store: file
+
+logging:
+  level: info
+  audit: true

data/lib/kodo/channels/base.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Kodo
+  module Channels
+    class Base
+      attr_reader :channel_id
+
+      def initialize(channel_id:)
+        @channel_id = channel_id
+        @running = false
+      end
+
+      def connect!
+        raise NotImplementedError
+      end
+
+      def disconnect!
+        @running = false
+      end
+
+      # Check for new messages. Returns Array<Kodo::Message>
+      def poll
+        raise NotImplementedError
+      end
+
+      # Send a message through this channel
+      def send_message(message)
+        raise NotImplementedError
+      end
+
+      def running?
+        @running
+      end
+    end
+  end
+end

data/lib/kodo/channels/console.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Kodo
+  module Channels
+    class Console < Base
+      def initialize
+        @inbox = Queue.new
+        super(channel_id: "console")
+      end
+
+      def connect!
+        @running = true
+        Kodo.logger.info("Console channel ready")
+        self
+      end
+
+      def disconnect!
+        @running = false
+      end
+
+      def poll
+        messages = []
+        messages << @inbox.pop(true) until @inbox.empty?
+        messages
+      rescue ThreadError
+        # Queue.pop(true) raises ThreadError when empty
+        messages
+      end
+
+      def send_message(message)
+        puts "\n\e[36mKodo:\e[0m #{message.content}\n\n"
+      end
+
+      # Push a message into the inbox (called from CLI input thread)
+      def push(text)
+        @inbox << Message.new(
+          channel_id: channel_id,
+          sender: :user,
+          content: text,
+          metadata: { chat_id: "console" }
+        )
+      end
+    end
+  end
+end

data/lib/kodo/channels/telegram.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Kodo
+  module Channels
+    class Telegram < Base
+      API_BASE = "https://api.telegram.org"
+
+      def initialize(bot_token:)
+        @bot_token = bot_token
+        @last_update_id = 0
+        @allowed_chat_ids = []  # empty = allow all (for now)
+        super(channel_id: "telegram")
+      end
+
+      def connect!
+        # Verify the bot token works
+        me = api_request("getMe")
+        bot_name = me.dig("result", "username")
+        Kodo.logger.info("Telegram connected as @#{bot_name}")
+        @running = true
+        self
+      rescue StandardError => e
+        raise Error, "Failed to connect Telegram: #{e.message}"
+      end
+
+      def disconnect!
+        @running = false
+        Kodo.logger.info("Telegram disconnected")
+      end
+
+      # Poll for new messages using long polling with a short timeout
+      # Returns Array<Kodo::Message>
+      def poll
+        return [] unless running?
+
+        params = {
+          offset: @last_update_id + 1,
+          timeout: 1,  # short poll — we're inside a heartbeat loop
+          allowed_updates: ["message"]
+        }
+
+        response = api_request("getUpdates", params)
+        updates = response.dig("result") || []
+
+        messages = updates.filter_map do |update|
+          @last_update_id = update["update_id"]
+          parse_update(update)
+        end
+
+        messages
+      rescue StandardError => e
+        Kodo.logger.warn("Telegram poll error: #{e.message}")
+        []
+      end
+
+      def send_message(message)
+        chat_id = message.metadata[:chat_id] || message.metadata["chat_id"]
+        return unless chat_id
+
+        params = {
+          chat_id: chat_id,
+          text: message.content,
+          parse_mode: "Markdown"
+        }
+
+        # If replying to a specific message
+        if (reply_to = message.metadata[:reply_to_message_id] || message.metadata["reply_to_message_id"])
+          params[:reply_to_message_id] = reply_to
+        end
+
+        api_request("sendMessage", params)
+        Kodo.logger.debug("Sent Telegram message to chat #{chat_id}")
+      rescue StandardError => e
+        Kodo.logger.error("Telegram send error: #{e.message}")
+
+        # Retry without markdown if parse failed
+        if e.message.include?("parse")
+          params.delete(:parse_mode)
+          api_request("sendMessage", params) rescue nil
+        end
+      end
+
+      private
+
+      def parse_update(update)
+        msg = update["message"]
+        return nil unless msg && msg["text"]
+
+        # Skip if we're filtering chat IDs and this isn't allowed
+        if @allowed_chat_ids.any? && !@allowed_chat_ids.include?(msg["chat"]["id"])
+          return nil
+        end
+
+        sender_name = [msg.dig("from", "first_name"), msg.dig("from", "last_name")]
+          .compact.join(" ")
+
+        Message.new(
+          channel_id: channel_id,
+          sender: :user,
+          content: msg["text"],
+          timestamp: Time.at(msg["date"]),
+          metadata: {
+            chat_id: msg["chat"]["id"],
+            message_id: msg["message_id"],
+            sender_name: sender_name,
+            sender_username: msg.dig("from", "username"),
+            sender_id: msg.dig("from", "id")
+          }
+        )
+      end
+
+      def api_request(method, params = {})
+        uri = URI("#{API_BASE}/bot#{@bot_token}/#{method}")
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = true
+        http.read_timeout = 10
+
+        request = Net::HTTP::Post.new(uri)
+        request["Content-Type"] = "application/json"
+        request.body = JSON.generate(params)
+
+        response = http.request(request)
+        parsed = JSON.parse(response.body)
+
+        unless parsed["ok"]
+          raise Error, "Telegram API error: #{parsed["description"]}"
+        end
+
+        parsed
+      end
+    end
+  end
+end