zuzu 0.0.1-java

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ae81f9e580d8c3e0efd863e9f56b6719a9cd08a092dc6b998ab8bf703ddae000
+  data.tar.gz: 287c409a0507b53f2f313da7fb2b00466180680641b36b81cc1d23b9046654db
+SHA512:
+  metadata.gz: 500c75552b9483fa2414a17971e3cce3d3c02f12ee0e02f63d723165e7ed1ba9c4b2f75b36d8520d4cbc52127331d11560e2bbca0eca4533e02c426e56e1e597
+  data.tar.gz: aa6f574afac309ef301b12632ee791521ee8ec287fcd4d933472c19cd7adc354e4d92c3f42871dc964ae343dde436ce0be01e6e83166ac7784f2389b9c3684db

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abhishek Parolkar
+
+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,374 @@
+# Zuzu
+
+**Local-first agentic desktop apps with JRuby.**
+
+Zuzu is a framework for building privacy-respecting AI desktop assistants that
+run entirely on your machine. No cloud APIs required — your data stays local.
+
+<video src="https://raw.githubusercontent.com/parolkar/zuzu/refs/heads/main/docs/demo/zuzu_quick_demo_01.mp4" controls width="100%"></video>
+[Quick Demo](https://raw.githubusercontent.com/parolkar/zuzu/refs/heads/main/docs/demo/zuzu_quick_demo_01.mp4)
+
+| Component | Technology |
+|-----------|------------|
+| Runtime | JRuby 10.0.3.0 (Java 21+) |
+| GUI | Glimmer DSL for SWT |
+| Database | SQLite via JDBC |
+| LLM | llamafile (local inference) |
+| Packaging | Warbler (.jar / .war) |
+
+## Quick Start
+
+### Prerequisites
+
+- **macOS** or **Linux** (Windows support is planned)
+- **Java 21+**
+- **rbenv** (recommended) or any JRuby version manager
+
+### One-Command Setup
+
+```bash
+git clone https://github.com/parolkar/zuzu.git
+cd zuzu
+bin/setup
+```
+
+`bin/setup` installs Java 21, JRuby 10.0.4.0, and all gem dependencies
+automatically. If you prefer manual setup, see [Manual Setup](#manual-setup)
+below.
+
+### Create Your First App
+
+When you run `bin/zuzu new` from the source tree, it automatically detects
+dev mode and points the scaffolded app's Gemfile at your local checkout
+(no published gem needed).
+
+```bash
+bin/zuzu new my_assistant
+cd my_assistant
+bundle install
+```
+
+Download a llamafile model:
+
+```bash
+mkdir -p models
+curl -L -o models/llava-v1.5-7b-q4.llamafile \
+  https://huggingface.co/Mozilla/llava-v1.5-7b-llamafile/resolve/main/llava-v1.5-7b-q4.llamafile
+chmod +x models/llava-v1.5-7b-q4.llamafile
+```
+
+Edit `app.rb` to point at your model:
+
+```ruby
+Zuzu.configure do |c|
+  c.app_name       = 'My Assistant'
+  c.llamafile_path = File.expand_path('models/llava-v1.5-7b-q4.llamafile', __dir__)
+  c.db_path        = File.expand_path('.zuzu/zuzu.db', __dir__)
+  c.port           = 8080
+end
+```
+
+Launch:
+
+```bash
+# macOS (SWT requires first-thread access):
+JRUBY_OPTS="-J-XstartOnFirstThread -J--enable-native-access=ALL-UNNAMED" bundle exec ruby app.rb
+
+# Linux:
+JRUBY_OPTS="-J--enable-native-access=ALL-UNNAMED" bundle exec ruby app.rb
+```
+
+You'll see a native desktop window with a file browser on the left and a chat
+interface on the right. The llamafile model starts automatically in the
+background.
+
+---
+
+## Manual Setup
+
+If `bin/setup` doesn't suit your workflow, follow these steps.
+
+### 1. Install Java 21+
+
+**macOS (Homebrew):**
+
+```bash
+brew install openjdk@21
+```
+
+Add to your shell profile (`~/.zshrc` or `~/.bash_profile`):
+
+```bash
+export JAVA_HOME=$(/usr/libexec/java_home -v 21)
+export PATH="$JAVA_HOME/bin:$PATH"
+```
+
+**macOS (SDKMAN):**
+
+```bash
+curl -s https://get.sdkman.io | bash
+source "$HOME/.sdkman/bin/sdkman-init.sh"
+sdk install java 21-tem
+```
+
+**Ubuntu / Debian:**
+
+```bash
+sudo apt-get update
+sudo apt-get install openjdk-21-jdk
+```
+
+Verify:
+
+```bash
+java -version
+# → openjdk version "21.x.x" ...
+```
+
+### 2. Install JRuby 10.0.4.0 via rbenv
+
+```bash
+# Install rbenv if needed
+brew install rbenv ruby-build   # macOS
+# or: https://github.com/rbenv/rbenv#installation
+
+rbenv install jruby-10.0.4.0
+rbenv local jruby-10.0.4.0
+ruby -v
+# → jruby 10.0.4.0 (ruby 3.x.x) ...
+```
+
+### 3. Install Gems
+
+```bash
+gem install bundler
+bundle install
+```
+
+---
+
+## Architecture
+
+```
+┌────────────────────────────────────────────────────┐
+│                   Zuzu App (SWT)                   │
+│  ┌──────────┐  ┌──────────────────────────────┐    │
+│  │ AgentFS  │  │       Chat Interface         │    │
+│  │  (files) │  │                              │    │
+│  │          │  │  User: How do I ...          │    │
+│  │  + docs/ │  │  Zuzu: Let me check ...      │    │
+│  │    a.txt │  │                              │    │
+│  └──────────┘  └──────────────────────────────┘    │
+│                ┌──────────────────────────────┐    │
+│                │ [  Type a message...  ] [Send]│    │
+│                └──────────────────────────────┘    │
+└──────────────────────────┬─────────────────────────┘
+                           │
+              ┌────────────▼────────────┐
+              │      Agent (ReAct)      │
+              │   ┌─────┐ ┌─────────┐  │
+              │   │Tools│ │ Memory  │  │
+              │   └──┬──┘ └────┬────┘  │
+              └──────┼─────────┼───────┘
+                     │         │
+              ┌──────▼─────────▼───────┐
+              │    SQLite (JDBC)       │
+              │  - fs_inodes/dentries  │
+              │  - messages            │
+              │  - kv_store            │
+              │  - tool_calls          │
+              └────────────────────────┘
+                           │
+              ┌────────────▼────────────┐
+              │   llamafile (local LLM) │
+              │   OpenAI-compat API     │
+              │   http://127.0.0.1:8080 │
+              └─────────────────────────┘
+```
+
+### Project Structure
+
+```
+zuzu/
+├── lib/zuzu/
+│   ├── config.rb             # Zuzu.configure { |c| ... }
+│   ├── store.rb              # JDBC SQLite — single connection wrapper
+│   ├── agent_fs.rb           # Virtual filesystem + KV store + audit log
+│   ├── memory.rb             # Conversation history
+│   ├── llm_client.rb         # HTTP client for llamafile
+│   ├── llamafile_manager.rb  # Subprocess lifecycle
+│   ├── tool_registry.rb      # Register / execute agent tools
+│   ├── agent.rb              # ReAct loop (think → act → observe)
+│   ├── app.rb                # Glimmer SWT desktop shell
+│   ├── tools/
+│   │   ├── file_tool.rb      # read_file, write_file, list_directory
+│   │   ├── shell_tool.rb     # run_command (allowlisted)
+│   │   └── web_tool.rb       # http_get
+│   └── channels/
+│       ├── base.rb           # Abstract channel interface
+│       ├── in_app.rb         # Desktop GUI (default)
+│       └── whatsapp.rb       # WhatsApp Cloud API webhook
+├── bin/
+│   ├── zuzu                  # CLI: new / start / console / version
+│   └── setup                 # One-command bootstrap
+├── templates/
+│   └── app.rb                # Scaffold template for `zuzu new`
+├── models/                   # Place llamafile models here
+├── Gemfile
+├── zuzu.gemspec
+├── Rakefile
+├── warble.rb                 # Warbler config for .jar packaging
+└── app.rb                    # Phase 1 standalone reference
+```
+
+---
+
+## Usage Guide
+
+### Custom Tools
+
+Register tools that the agent can call during conversations:
+
+```ruby
+Zuzu::ToolRegistry.register(
+  'lookup_weather',
+  'Get current weather for a city.',
+  {
+    type: 'object',
+    properties: { city: { type: 'string' } },
+    required: ['city']
+  }
+) do |args, agent_fs|
+  # Your logic here — call an API, read a file, etc.
+  "Weather in #{args['city']}: 22°C, sunny"
+end
+```
+
+The agent's ReAct loop will automatically discover and call your tools when
+relevant to the user's question.
+
+### WhatsApp Channel
+
+Enable WhatsApp so users can chat with your agent via their phone:
+
+```ruby
+Zuzu.configure do |c|
+  c.channels = ['whatsapp']
+end
+```
+
+Set environment variables:
+
+```bash
+export WHATSAPP_TOKEN="your_cloud_api_token"
+export WHATSAPP_PHONE_ID="your_phone_number_id"
+export WHATSAPP_PORT=9292   # optional, defaults to 9292
+```
+
+The WhatsApp channel starts a WEBrick webhook server that receives messages
+from the WhatsApp Cloud API and replies using the same agent.
+
+### Virtual Filesystem (AgentFS)
+
+The agent operates in a sandboxed SQLite-backed filesystem:
+
+```ruby
+store = Zuzu::Store.new
+fs    = Zuzu::AgentFS.new(store)
+
+fs.write_file('/notes/todo.txt', 'Buy groceries')
+fs.read_file('/notes/todo.txt')    # → "Buy groceries"
+fs.list_dir('/notes')              # → ["todo.txt"]
+fs.mkdir('/docs')
+fs.exists?('/notes/todo.txt')      # → true
+
+# Key-value store
+fs.kv_set('last_query', 'weather in Tokyo')
+fs.kv_get('last_query')            # → "weather in Tokyo"
+```
+
+### Packaging as .jar
+
+Use Warbler to create a standalone Java archive:
+
+```bash
+gem install warbler
+warble jar
+java -XstartOnFirstThread -jar zuzu-app.jar   # macOS
+java -jar zuzu-app.jar                        # Linux
+```
+
+---
+
+## Configuration Reference
+
+```ruby
+Zuzu.configure do |c|
+  c.app_name       = 'My Agent'           # Window title
+  c.llamafile_path = 'models/llava-v1.5-7b-q4.llamafile'   # Path to llamafile binary
+  c.db_path        = '.zuzu/zuzu.db'      # SQLite database location
+  c.port           = 8080                  # llamafile API port
+  c.model          = 'LLaMA_CPP'          # Model identifier
+  c.channels       = ['whatsapp']          # Extra channels to enable
+  c.log_level      = :info                 # :debug, :info, :warn, :error
+  c.window_width   = 860                   # Window width in pixels
+  c.window_height  = 620                   # Window height in pixels
+end
+```
+
+---
+
+## CLI Reference
+
+```
+zuzu new APP_NAME    Scaffold a new Zuzu application
+zuzu start           Launch the Zuzu app in the current directory
+zuzu console         Open an IRB session with Zuzu loaded
+zuzu version         Print the Zuzu version
+zuzu help            Show this message
+```
+
+---
+
+## Troubleshooting
+
+### macOS: "SWT main thread" error
+
+SWT on macOS requires the main thread. Always launch with:
+
+```bash
+JRUBY_OPTS="-J-XstartOnFirstThread -J--enable-native-access=ALL-UNNAMED" bundle exec ruby app.rb
+```
+
+### llamafile won't start
+
+- Ensure the file is executable: `chmod +x models/your-model.llamafile`
+- Check `models/llama.log` for errors.
+- Verify port 8080 isn't already in use: `lsof -i :8080`
+
+### "java.lang.ClassNotFoundException: org.sqlite.JDBC"
+
+Run `bundle install` to ensure `jdbc-sqlite3` is installed. The gem must be
+loaded before any database access.
+
+
+---
+
+## Philosophy
+
+- **Local-first.** Your data never leaves your machine.
+- **Minimal code.** The entire framework is ~800 lines of Ruby.
+- **No Docker.** Just Java, JRuby, and a single SQLite file.
+- **Channels built in.** Every app gets in-app chat and optional WhatsApp.
+- **Tools are Ruby blocks.** No YAML configs, no DSL ceremonies.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Author(s)
+
+**Abhishek Parolkar**
+- GitHub: [@parolkar](https://github.com/parolkar)

data/bin/setup

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# bin/setup — one-command bootstrap for Zuzu development.
+# Installs Java 21, JRuby, and gem dependencies.
+set -euo pipefail
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+step() { printf "\n${GREEN}▸ %s${NC}\n" "$1"; }
+warn() { printf "${YELLOW}⚠ %s${NC}\n" "$1"; }
+
+JRUBY_VERSION="10.0.3.0"
+
+# ── Java 21 ──────────────────────────────────────────────────────
+step "Checking Java 21+"
+if java -version 2>&1 | grep -q 'version "2[1-9]\|version "3'; then
+  echo "  Java 21+ found."
+else
+  warn "Java 21+ not found."
+  if [[ "$OSTYPE" == darwin* ]]; then
+    step "Installing Java 21 via Homebrew"
+    brew install openjdk@21
+    echo 'export JAVA_HOME=$(/usr/libexec/java_home -v 21)' >> ~/.zshrc
+    export JAVA_HOME=$(/usr/libexec/java_home -v 21)
+    export PATH="$JAVA_HOME/bin:$PATH"
+    echo "  Installed. Restart your shell or run: source ~/.zshrc"
+  elif [[ "$OSTYPE" == linux-gnu* ]]; then
+    step "Installing Java 21 via apt"
+    sudo apt-get update -qq && sudo apt-get install -y openjdk-21-jdk
+  else
+    echo "  Please install Java 21+ manually: https://adoptium.net"
+    exit 1
+  fi
+fi
+
+# ── rbenv + JRuby ────────────────────────────────────────────────
+step "Checking rbenv"
+if ! command -v rbenv &>/dev/null; then
+  warn "rbenv not found. Installing..."
+  if [[ "$OSTYPE" == darwin* ]]; then
+    brew install rbenv ruby-build
+  else
+    curl -fsSL https://github.com/rbenv/rbenv-installer/raw/HEAD/bin/rbenv-installer | bash
+    export PATH="$HOME/.rbenv/bin:$PATH"
+  fi
+  eval "$(rbenv init - bash 2>/dev/null || rbenv init - zsh 2>/dev/null || true)"
+fi
+
+step "Checking JRuby $JRUBY_VERSION"
+if rbenv versions --bare 2>/dev/null | grep -q "^jruby-${JRUBY_VERSION}$"; then
+  echo "  JRuby $JRUBY_VERSION already installed."
+else
+  step "Installing JRuby $JRUBY_VERSION (this may take a few minutes)"
+  rbenv install --skip-existing "jruby-${JRUBY_VERSION}"
+fi
+
+rbenv local "jruby-${JRUBY_VERSION}"
+eval "$(rbenv init - bash 2>/dev/null || rbenv init - zsh 2>/dev/null || true)"
+
+# ── Gems ─────────────────────────────────────────────────────────
+step "Installing gem dependencies"
+gem install bundler --conservative
+bundle install
+
+# ── Done ─────────────────────────────────────────────────────────
+step "Setup complete!"
+echo ""
+echo "  Ruby:  $(ruby -v)"
+echo "  Java:  $(java -version 2>&1 | head -1)"
+echo ""
+echo "  Next:  Download a llamafile model into models/"
+echo "         Then run:  bin/zuzu start"

data/bin/zuzu

@@ -0,0 +1,128 @@
+#!/usr/bin/env jruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+
+require 'fileutils'
+require 'zuzu'
+
+USAGE = <<~USAGE
+  Zuzu #{Zuzu::VERSION} — local-first agentic desktop framework
+
+  Usage:
+    zuzu new APP_NAME    Scaffold a new Zuzu application
+    zuzu start           Launch the Zuzu app in the current directory
+    zuzu package         Package the app as a standalone .jar
+    zuzu console         Open an IRB session with Zuzu loaded
+    zuzu version         Print the Zuzu version
+    zuzu help            Show this message
+USAGE
+
+# Detect whether we're running from the zuzu source tree (dev mode)
+# by checking if the gemspec exists alongside this script.
+ZUZU_ROOT   = File.expand_path('..', __dir__)
+DEV_MODE    = ENV['ZUZU_DEV'] || File.exist?(File.join(ZUZU_ROOT, 'zuzu.gemspec'))
+
+command = ARGV.shift
+
+case command
+when 'new'
+  app_name = ARGV.shift
+  abort 'Usage: zuzu new APP_NAME' unless app_name
+
+  app_dir = File.expand_path(app_name)
+  abort "Directory '#{app_name}' already exists." if File.exist?(app_dir)
+
+  template_src = File.expand_path('../templates/app.rb', __dir__)
+
+  FileUtils.mkdir_p(app_dir)
+  FileUtils.cp(template_src, File.join(app_dir, 'app.rb'))
+
+  # Generate Gemfile — uses local path when running from source tree,
+  # published gem when installed via `gem install zuzu`.
+  if DEV_MODE
+    zuzu_line = %(gem "zuzu", path: #{ZUZU_ROOT.inspect})
+  else
+    zuzu_line = %(gem "zuzu")
+  end
+
+  File.write(File.join(app_dir, 'Gemfile'), <<~GEMFILE)
+    # frozen_string_literal: true
+    source "https://rubygems.org"
+    #{zuzu_line}
+  GEMFILE
+
+  puts "Created new Zuzu app: #{app_name}/"
+  puts "  #{app_name}/app.rb"
+  puts "  #{app_name}/Gemfile"
+  puts ''
+  if DEV_MODE
+    puts "  (dev mode: Gemfile points to #{ZUZU_ROOT})"
+    puts ''
+  end
+  puts 'Next steps:'
+  puts "  cd #{app_name}"
+  puts '  bundle install'
+  puts '  # Download a llamafile model into models/'
+  puts '  zuzu start'
+
+when 'start'
+  entry = ['app.rb', 'lib/app.rb'].find { |f| File.exist?(f) }
+  abort 'No app.rb found. Run `zuzu start` from your app directory.' unless entry
+  load File.expand_path(entry)
+
+when 'package'
+  entry = ['app.rb', 'lib/app.rb'].find { |f| File.exist?(f) }
+  abort 'No app.rb found. Run `zuzu package` from your app directory.' unless entry
+
+  # Copy warble.rb from zuzu source if not already present
+  warble_config = 'warble.rb'
+  unless File.exist?(warble_config)
+    src = File.expand_path('../warble.rb', __dir__)
+    if File.exist?(src)
+      FileUtils.cp(src, warble_config)
+      puts "Copied warble.rb from zuzu source."
+    else
+      abort 'warble.rb not found. Please add it to your app directory.'
+    end
+  end
+
+  # Ensure warbler gem is available
+  warble_bin = `which warble 2>/dev/null`.strip
+  if warble_bin.empty?
+    puts 'Installing warbler gem...'
+    system('gem install warbler') || abort('Failed to install warbler.')
+    warble_bin = `which warble 2>/dev/null`.strip
+    abort 'warble binary not found after install. Try: gem install warbler' if warble_bin.empty?
+  end
+
+  puts 'Packaging app as zuzu-app.jar ...'
+  puts '  (this may take a minute)'
+  success = Bundler.with_unbundled_env { system(warble_bin, 'jar') }
+  if success
+    puts ''
+    puts 'Done! Created: zuzu-app.jar'
+    puts ''
+    puts 'Run it with:'
+    puts '  java -XstartOnFirstThread -jar zuzu-app.jar   # macOS'
+    puts '  java -jar zuzu-app.jar                        # Linux / Windows'
+  else
+    abort 'warble jar failed. Check output above for details.'
+  end
+
+when 'console'
+  require 'irb'
+  puts "Zuzu #{Zuzu::VERSION} console. Type `exit` to quit."
+  IRB.start(__FILE__)
+
+when 'version'
+  puts "zuzu #{Zuzu::VERSION}"
+
+when 'help', nil
+  puts USAGE
+
+else
+  warn "Unknown command: #{command}"
+  puts USAGE
+  exit 1
+end