askcii 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fdbabf6bbd313aa11a7868b5df4630a85798e6a59311872bc04cebeaa2ac49e3
-  data.tar.gz: cff4449b247c8dcfe5273e122b054d72e54f57866f905854fd94aa39ee8e8547
+  metadata.gz: cecbd9c499b5c5736cf4059337fef530a6438272512b1bdbcd365c30be99fb91
+  data.tar.gz: 584719227c6c64f9886694abe922d8623b2a517988f788ef078144cfab78213d
 SHA512:
-  metadata.gz: 5ca4009158417d0eee5a4452c4ec5c49fefedabdeb22495a2f6b6d08136391f19535e9468113c164f714e0a382eb8b57244e56027d6b824f23132fea679a4d29
-  data.tar.gz: ee32e1ab823d7a2dc53445e3fa7cf064993272571512f6c4b18966bbb08c87163158262387521d073d5bfa0c158f80b8ab808f05c98f8e330aaaa555122814f2
+  metadata.gz: 22b9b01ee86ecd887db61892585f39217ea95c68c7a49dfbfbc12018d0ee8525a3e873464c2c962cff105b436ffeabd3462b93b07d0b93adca612822c23766be
+  data.tar.gz: e84ba6a8d2789be26e67bb8cd4527962fdc134ad11d6d3a30c6bd8cbfd8f0c201a9faec8055dfdcd2b1171f3c1a776252a8e69bfe5f3f35382814818848a93b5

data/.gitignore

@@ -1,2 +1,5 @@
 *.gem
 **/.claude/settings.local.json
+
+# Override global gitignore to allow CLAUDE.md in this repo
+!CLAUDE.md

data/CLAUDE.md

@@ -0,0 +1,131 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Askcii is a Ruby gem that provides a command-line interface for interacting with multiple LLM providers (OpenAI, Anthropic, Gemini, DeepSeek, OpenRouter, Ollama). It supports multi-configuration management, session-based conversations, and streaming responses.
+
+## Development Commands
+
+### Installation and Setup
+```bash
+bundle install              # Install dependencies
+bin/setup                   # Run setup script
+```
+
+### Running the Application
+```bash
+bin/askcii 'Your prompt'    # Run locally from source
+bundle exec askcii          # Run via bundler
+```
+
+### Gem Management
+```bash
+bundle exec rake build      # Build the gem
+bundle exec rake install    # Install gem locally
+bundle exec rake release    # Release new version (requires version bump in lib/askcii/version.rb)
+```
+
+### Testing
+Note: This project currently has no test suite configured, despite the Rakefile referencing RSpec and the gemspec including minitest.
+
+### Console
+```bash
+bin/console                 # Interactive Ruby console with askcii loaded
+```
+
+## Architecture
+
+### Core Components
+
+**Entry Point (`bin/askcii`)**: Initializes the database, loads models, and starts the Application.
+
+**Application Layer (`lib/askcii/application.rb`)**: The main application controller that:
+- Parses CLI arguments via the CLI class
+- Determines which configuration to use (explicit -m flag, default config, or env vars)
+- Configures the RubyLLM library with provider-specific settings
+- Delegates to ChatSession for actual LLM interaction
+
+**CLI Parser (`lib/askcii/cli.rb`)**: Handles command-line argument parsing using OptionParser. Supports flags for:
+- `-p/--private`: Private sessions (no history)
+- `-r/--last-response`: Retrieve last assistant response
+- `-c/--configure`: Interactive configuration management
+- `-m/--model ID`: Use specific configuration by ID
+
+**Configuration System**: Multi-layered configuration approach:
+1. **Multi-config mode** (`lib/askcii/models/config.rb`): Stores multiple provider configurations in SQLite with JSON serialization
+2. **Legacy env var mode**: Falls back to `ASKCII_API_KEY`, `ASKCII_API_ENDPOINT`, `ASKCII_MODEL_ID` environment variables
+3. **Configuration Manager** (`lib/askcii/configuration_manager.rb`): Interactive TUI for managing configurations
+
+### Data Models (Sequel ORM)
+
+**Config Model** (`lib/askcii/models/config.rb`):
+- Key-value store using `configs` table
+- Multi-configurations stored as `config_1`, `config_2`, etc. with JSON values
+- Each config contains: name, api_key, api_endpoint, model_id, provider
+- Tracks default configuration via `default_config_id` key
+
+**Chat Model** (`lib/askcii/models/chat.rb`):
+- Represents a conversation session identified by `context` (from `ASKCII_SESSION` env var or random hex)
+- Has many Messages
+- Converts to/from RubyLLM::Chat objects
+- Persists new messages and completions via callbacks
+
+**Message Model** (`lib/askcii/models/message.rb`):
+- Stores individual messages with role, content, token counts, and model_id
+- Belongs to a Chat
+- Handles UTF-8 encoding to prevent database issues
+
+### Database
+
+**Location**: `~/.local/share/askcii/askcii.db` (SQLite via Amalgalite)
+
+**Schema** (see `Askcii.setup_database` in `lib/askcii.rb`):
+- `chats`: id, model_id, context, created_at
+- `messages`: id, chat_id, role, content (TEXT), model_id, input_tokens, output_tokens, created_at
+- `configs`: id, key (unique), value (TEXT for JSON storage)
+
+### Session Management
+
+Sessions are controlled by the `ASKCII_SESSION` environment variable:
+- If set: reuses the same chat context across invocations
+- If unset: generates a random session ID per invocation
+- Private mode (`-p`): creates ephemeral RubyLLM chat without database persistence
+
+### Provider Configuration
+
+The `Askcii.configure_llm` method in `lib/askcii.rb` handles provider-specific setup:
+- **OpenAI**: Sets `openai_api_key` and `openai_api_base`
+- **Anthropic**: Sets `anthropic_api_key`
+- **Gemini**: Sets `gemini_api_key`
+- **DeepSeek**: Sets `deepseek_api_key`
+- **OpenRouter**: Sets `openrouter_api_key`
+- **Ollama**: Only requires endpoint (default: `http://localhost:11434/v1`), no API key
+
+All LLM interactions go through the `ruby_llm` gem (v1.3.0), which provides unified streaming chat interface.
+
+### Chat Execution Flow
+
+1. `Application#run` determines configuration and calls `ChatSession#execute_chat`
+2. `ChatSession` creates either a private or persistent chat
+3. Persistent chats load history from database via `Chat#to_llm`
+4. System instruction sets terminal-friendly response style
+5. User prompt (optionally combined with stdin input) is sent to LLM
+6. Response streams to stdout character-by-character
+7. For persistent chats, callbacks save assistant messages to database
+
+## Important Patterns
+
+**Provider Selection**: The system uses string provider names ('openai', 'anthropic', etc.) in configuration but converts them to symbols for RubyLLM. The `assume_model_exists: true` flag bypasses RubyLLM's model validation.
+
+**Text Encoding**: Message content is always encoded as UTF-8 with `undef: :replace` to prevent encoding errors when saving to SQLite.
+
+**Streaming**: All chat responses use streaming via blocks to provide immediate character-by-character output.
+
+**Configuration Priority**:
+1. Explicit `-m ID` flag
+2. Default configuration from database
+3. Environment variables (legacy fallback)
+
+**Database Initialization**: The database and tables are created automatically on first run via `Askcii.setup_database` in the bin script.