askcii 0.3.0 → 0.4.0

data/README.md

@@ -1,92 +1,249 @@
 # Askcii
 
-A command-line application for interacting with multiple LLM providers in a terminal-friendly way. Supports OpenAI, Anthropic, Gemini, DeepSeek, OpenRouter, and Ollama with multi-configuration management.
+**Bring the power of Large Language Models to your command line—the Unix way.**
+
+Askcii is a terminal-native CLI tool that connects you to multiple LLM providers (OpenAI, Anthropic, Gemini, DeepSeek, OpenRouter, and Ollama) through a simple, composable interface. It's designed to integrate seamlessly into your existing Unix workflows, treating LLMs as just another filter in your pipeline.
+
+## Philosophy: Why CLI, Not TUI?
+
+In the Unix tradition, the most powerful tools are those that **compose**. They read from standard input, write to standard output, and can be chained together with pipes to create sophisticated workflows. Askcii embraces this philosophy completely.
+
+Unlike interactive TUI (Text User Interface) applications that take over your terminal with full-screen interfaces, Askcii is a **single-purpose filter**: it takes text in, sends it to an LLM, and streams the response back out. This simple design makes it infinitely more versatile.
+
+**What this means in practice:**
+
+- **Pipeable**: Chain it with `grep`, `awk`, `sed`, `jq`, and any other Unix tool
+- **Scriptable**: Use it in shell scripts, cron jobs, and automation workflows
+- **Composable**: Combine it with your existing toolchain without context switching
+- **Redirectable**: Save outputs to files, pipe to other commands, integrate into larger systems
+- **Session-aware**: Maintain conversation context across invocations when needed
+- **Privacy-first**: Run in private mode or use local models via Ollama for sensitive data
+
+Askcii doesn't try to be a chat application. It's a **Unix power tool** that puts LLM capabilities directly into your pipeline, where they belong.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+```bash
+gem install askcii
+```
+
+Or add to your Gemfile:
 
 ```ruby
 gem 'askcii'
 ```
 
-And then execute:
+## Quick Start
 
-    $ bundle install
+```bash
+# Simple prompt
+askcii 'Explain recursive functions in one sentence'
+
+# Pipe input from other commands
+git diff | askcii 'Review this code change'
 
-Or install it yourself as:
+# Chain with other tools
+curl -s https://api.github.com/repos/ruby/ruby | askcii 'Summarize this repo' | tee summary.txt
 
-    $ gem install askcii
+# Private session (no history)
+askcii -p 'What is my IP address showing?'
+```
 
 ## Usage
 
-### Basic Usage
+### Basic Patterns
 
 ```bash
-# Basic usage
+# Direct prompt
 askcii 'Your prompt here'
 
-# Pipe input from other commands
-echo 'Your context text' | askcii 'Analyze this text'
+# Standard input from pipe
+echo 'Context text' | askcii 'Analyze this'
 
-# File input
+# Read from file
 askcii 'Summarize this document' < document.txt
 
-# Private session (no conversation history saved)
-askcii -p 'Tell me a joke'
+# Redirect output to file
+askcii 'Write a bash script to backup /home' > backup.sh
 
-# Get the last response from your current session
-askcii -r
+# Chain multiple commands
+cat error.log | grep ERROR | askcii 'What are the common patterns?' | less
+```
+
+### Command-Line Options
 
-# Use a specific configuration
-askcii -m 2 'Hello using configuration 2'
 ```
+Usage: askcii [options] 'Your prompt here'
 
-### Session Management
+Options:
+  -p, --private         Private session (no conversation history saved)
+  -r, --last-response   Retrieve and output the last assistant response
+  -c, --configure       Launch configuration management interface
+  -m, --model ID        Use specific configuration by ID number
+  -h, --help            Show this help message
+```
+
+## Real-World Examples
+
+### Code Analysis & Development
 
 ```bash
-# Set a custom session ID to maintain conversation context
-ASKCII_SESSION="project-research" askcii 'What did we talk about earlier?'
+# Code review with detailed feedback
+git diff main..feature-branch | askcii 'Review these changes. Focus on security and performance.'
 
-# Generate a new session for each terminal session
-export ASKCII_SESSION=$(openssl rand -hex 16)
+# Explain unfamiliar code
+cat legacy_module.rb | askcii 'Explain what this code does and identify potential issues'
+
+# Generate unit tests
+askcii 'Write RSpec tests for a User model with email validation' > spec/user_spec.rb
+
+# Debug assistance
+tail -50 production.log | grep ERROR | askcii 'What are the root causes of these errors?'
+
+# Refactoring suggestions
+cat messy_controller.rb | askcii 'Suggest refactoring to improve this code'
+
+# Documentation generation
+ls -R lib/ | askcii 'Create a project structure overview' > STRUCTURE.md
 ```
 
-### Command Line Options
+### Data Processing & Analysis
+
+```bash
+# CSV to JSON conversion
+cat users.csv | askcii 'Convert this CSV to JSON array format' > users.json
+
+# Log analysis and summarization
+tail -1000 /var/log/nginx/access.log | askcii 'Summarize traffic patterns and anomalies'
+
+# Data extraction from unstructured text
+curl -s https://example.com/article | askcii 'Extract all email addresses and URLs as a list'
+
+# SQL query generation
+askcii 'Write a PostgreSQL query to find duplicate users by email' >> queries.sql
 
+# API response analysis
+curl -s https://api.service.com/status | jq . | askcii 'Is this API healthy? Explain the metrics.'
 ```
-Usage: askcii [options] 'Your prompt here'
 
-Options:
-  -p, --private         Start a private session and do not record
-  -r, --last-response   Output the last response
-  -c, --configure       Manage configurations
-  -m, --model ID        Use specific configuration ID
-  -h, --help            Show help
+### System Administration
+
+```bash
+# Server health check summary
+df -h && free -h && uptime | askcii 'Assess system health and recommend actions'
+
+# Parse and explain complex configs
+cat /etc/nginx/nginx.conf | askcii 'Explain this configuration and suggest optimizations'
+
+# Security audit
+find . -name "*.sh" -exec cat {} \; | askcii 'Review these shell scripts for security issues'
+
+# Quick command help
+askcii 'Show me tar command examples for incremental backups'
+
+# Incident analysis
+journalctl --since "1 hour ago" | askcii 'Identify any critical system events'
+```
+
+### Documentation & Writing
+
+```bash
+# Generate README sections
+askcii 'Write installation instructions for a Ruby gem' >> README.md
+
+# Meeting notes to action items
+cat meeting_transcript.txt | askcii 'Extract action items with owners as markdown checklist'
+
+# Explain technical concepts
+askcii 'Explain OAuth2 flow in simple terms' > oauth_explainer.md
+
+# Create Git commit messages
+git diff --staged | askcii 'Write a conventional commit message' | pbcopy
+```
+
+### Session-Based Conversations
+
+```bash
+# Named session for ongoing work
+export ASKCII_SESSION="database-migration"
+askcii 'I need to migrate from MySQL to PostgreSQL'
+askcii 'What about handling JSON columns?' # Remembers context
+askcii 'Show migration script for users table' > migrate_users.sql
+
+# Project-specific session
+ASKCII_SESSION="feature-auth" askcii 'How should I implement 2FA?'
+ASKCII_SESSION="feature-auth" askcii 'Show me the code for TOTP generation'
+
+# Retrieve last response (useful when output scrolled away)
+askcii -r | less
+```
+
+### Multi-Provider Workflows
+
+```bash
+# Use Claude for creative content
+askcii -m 1 'Write a technical blog post intro about WebAssembly' > blog_draft.md
+
+# Use GPT-4 for code generation
+askcii -m 2 'Create a Python class for rate limiting' > rate_limiter.py
+
+# Use local Ollama for private/sensitive data
+cat proprietary_data.txt | askcii -m 3 -p 'Analyze this confidential report'
+
+# Use DeepSeek for cost-effective tasks
+find . -name "*.rb" | xargs wc -l | askcii -m 4 'Summarize codebase statistics'
+```
+
+### Advanced Compositions
+
+```bash
+# Multi-stage pipeline
+cat research_papers.txt | \
+  askcii 'Extract key findings' | \
+  askcii 'Group by topic' | \
+  askcii 'Create a bibliography' > bibliography.md
+
+# Watch and analyze in real-time
+tail -f app.log | grep --line-buffered ERROR | while read line; do
+  echo "$line" | askcii -p 'Explain this error briefly'
+done
+
+# Batch processing with parallel
+find . -name "*.java" | parallel -j4 "cat {} | askcii 'Rate code quality 1-10' | echo {}: "
+
+# Interactive script integration
+#!/bin/bash
+context=$(cat context.txt)
+while true; do
+  read -p "Question: " question
+  echo "$context" | askcii "$question"
+done
 ```
 
 ## Configuration Management
 
-Askcii supports multi-configuration management, allowing you to easily switch between different LLM providers and models.
+Askcii supports multiple provider configurations, allowing you to switch between different LLMs based on your needs—cost, privacy, capability, or speed.
 
-### Interactive Configuration
+### Interactive Configuration Setup
 
-Use the `-c` flag to access the configuration management interface:
+Launch the configuration manager:
 
 ```bash
 askcii -c
 ```
 
-This will show you a menu like:
+You'll see an interface like:
 
 ```
 Configuration Management
 =======================
 Current configurations:
-  1. GPT-4 [openai] (default)
-  2. Claude Sonnet [anthropic]
-  3. Gemini Pro [gemini]
-  4. Local Llama [ollama]
+  1. GPT-4 Turbo [openai] (default)
+  2. Claude 3.5 Sonnet [anthropic]
+  3. Gemini 2.0 Flash [gemini]
+  4. DeepSeek V3 [deepseek]
+  5. Mixtral [openrouter]
+  6. Llama 3.2 [ollama]
 
 Options:
   1. Add new configuration
@@ -97,127 +254,209 @@ Options:
 
 ### Supported Providers
 
-1. **OpenAI** - GPT models (gpt-4, gpt-3.5-turbo, etc.)
-2. **Anthropic** - Claude models (claude-3-sonnet, claude-3-haiku, etc.)
-3. **Gemini** - Google's Gemini models
-4. **DeepSeek** - DeepSeek models
-5. **OpenRouter** - Access to multiple models through OpenRouter
-6. **Ollama** - Local models (no API key required)
+| Provider | Use Case | API Key Required |
+|----------|----------|------------------|
+| **OpenAI** | GPT models (GPT-4, GPT-4 Turbo, GPT-3.5) | Yes |
+| **Anthropic** | Claude models (Opus, Sonnet, Haiku) | Yes |
+| **Gemini** | Google's Gemini models | Yes |
+| **DeepSeek** | Cost-effective DeepSeek models | Yes |
+| **OpenRouter** | Access 100+ models through one API | Yes |
+| **Ollama** | Local models (Llama, Mistral, etc.) | No |
 
-### Adding a New Configuration
+### Adding Configurations
 
-When adding a configuration, you'll be prompted for:
+When you add a new configuration, you provide:
 
-1. **Configuration name** - A friendly name for this configuration
-2. **Provider** - Choose from the supported providers
-3. **API key** - Your API key for the provider (not needed for Ollama)
-4. **API endpoint** - The API endpoint (defaults provided for each provider)
-5. **Model ID** - The specific model to use
+1. **Name**: Friendly identifier (e.g., "GPT-4 for Code")
+2. **Provider**: Choose from the supported list
+3. **API Key**: Your provider API key (except Ollama)
+4. **Endpoint**: API endpoint (defaults provided)
+5. **Model ID**: Specific model identifier
 
-Example for OpenAI:
+**Example: Adding OpenAI**
 ```
-Enter configuration name: GPT-4 Turbo
-Provider (1-6): 1
-Enter OpenAI API key: sk-your-api-key-here
-Enter API endpoint (default: https://api.openai.com/v1): [press enter for default]
-Enter model ID: gpt-4-turbo-preview
+Name: GPT-4 Turbo
+Provider: 1 (OpenAI)
+API Key: sk-proj-xxxxxxxxxxxxx
+Endpoint: [leave blank for default]
+Model ID: gpt-4-turbo-preview
 ```
 
-Example for Ollama (local):
+**Example: Adding Ollama (Local)**
 ```
-Enter configuration name: Local Llama
-Provider (1-6): 6
-Enter API endpoint (default: http://localhost:11434/v1): [press enter for default]
-Enter model ID: llama3:8b
+Name: Local Llama
+Provider: 6 (Ollama)
+Endpoint: http://localhost:11434/v1
+Model ID: llama3.2:latest
 ```
 
 ### Using Configurations
 
 ```bash
-# Use the default configuration
+# Use default configuration
 askcii 'Hello world'
 
-# Use a specific configuration by ID
-askcii -m 2 'Hello using configuration 2'
+# Use specific configuration by ID
+askcii -m 2 'Use Claude for this'
 
-# List all configurations
-askcii -c
+# Switch default in config manager
+askcii -c  # Then select "Set default configuration"
 ```
 
-### Configuration Storage
-
-Configuration settings are stored in a SQLite database located at `~/.local/share/askcii/askcii.db`.
-
 ### Environment Variable Fallback
 
-You can still use environment variables as a fallback when no configurations are set up:
+For quick one-offs or CI/CD environments, use environment variables:
 
 ```bash
-ASKCII_API_KEY="your_api_key" askcii 'Hello!'
-ASKCII_API_ENDPOINT="https://api.example.com/v1" askcii 'Hello!'
-ASKCII_MODEL_ID="gpt-4" askcii 'Hello!'
+# Quick override
+ASKCII_API_KEY="sk-xxx" ASKCII_MODEL_ID="gpt-4" askcii 'Quick question'
+
+# In scripts
+export ASKCII_API_KEY="your_key"
+export ASKCII_API_ENDPOINT="https://api.openai.com/v1"
+export ASKCII_MODEL_ID="gpt-3.5-turbo"
+askcii 'Automated query'
 ```
 
-## Examples
+## Session Management
+
+Askcii maintains conversation context across invocations, but you control when and how.
 
-### Daily Workflow Examples
+### Session Contexts
+
+Sessions are identified by the `ASKCII_SESSION` environment variable:
 
 ```bash
-# Code review
-git diff | askcii 'Review this code change and suggest improvements'
+# Random session per terminal session (recommended)
+export ASKCII_SESSION=$(openssl rand -hex 16)
 
-# Log analysis
-tail -100 /var/log/app.log | askcii 'Summarize any errors or issues'
+# Named session for a specific project
+export ASKCII_SESSION="refactoring-auth-module"
+askcii 'What patterns should I use for the auth module?'
+askcii 'Show code for the JWT validator'  # Remembers previous context
 
-# Documentation
-askcii 'Explain how to set up a Redis cluster' > redis-setup.md
+# One-off session (no context retention)
+askcii 'Standalone question'  # Creates random session ID
 
-# Quick calculations
-askcii 'Calculate compound interest: $1000 at 5% for 10 years'
+# Private mode (no database storage at all)
+askcii -p 'What is 2+2?'  # No session, no history
+```
 
-# Text processing
-cat customers.csv | askcii 'Convert this CSV to JSON format'
+### Retrieving Responses
+
+```bash
+# Get last response from current session
+askcii -r
+
+# Useful in scripts
+last_response=$(askcii -r)
+echo "$last_response" | process_further.sh
+
+# Copy to clipboard
+askcii -r | pbcopy  # macOS
+askcii -r | xclip -selection clipboard  # Linux
 ```
 
-### Multi-Provider Usage
+### Privacy Considerations
 
 ```bash
-# Use Claude for creative writing
-askcii -m 1 'Write a short story about AI'
+# Private mode: no storage, no history
+askcii -p 'Analyze this sensitive data' < confidential.txt
 
-# Use GPT-4 for code analysis
-askcii -m 2 'Explain this Python function' < function.py
+# Use local Ollama for complete privacy
+askcii -m 6 'Process private information' < private.txt
 
-# Use local Ollama for private data
-askcii -m 3 -p 'Analyze this sensitive document' < confidential.txt
+# Session isolation
+ASKCII_SESSION="temp-$(date +%s)" askcii 'Temporary context'
 ```
 
-## Session Management
+## Data Storage
 
-Askcii maintains conversation history unless you use the private mode (`-p`). Sessions are identified by:
+- **Database**: `~/.local/share/askcii/askcii.db` (SQLite)
+- **Stored**: Conversations, messages, configurations
+- **Not stored**: Private mode sessions (`-p` flag)
 
-1. The `ASKCII_SESSION` environment variable
-2. A randomly generated session ID if not specified
+## Integration Examples
+
+### Git Hooks
 
 ```bash
-# Start a named session for a project
-export ASKCII_SESSION="project-alpha"
-askcii 'What is the project timeline?'
-askcii 'What are the main risks?' # This will have context from previous question
+# .git/hooks/pre-commit
+#!/bin/bash
+git diff --cached | askcii -p 'Any obvious issues with this commit?' | tee /dev/tty
+read -p "Proceed with commit? [y/N] " -n 1 -r
+echo
+[[ $REPLY =~ ^[Yy]$ ]] || exit 1
+```
 
-# Use private mode for one-off questions
-askcii -p 'What is the weather like?'
+### Vim Integration
 
-# Get the last response from current session
-askcii -r
+```vim
+" In ~/.vimrc - send selection to askcii
+vnoremap <leader>a :w !askcii 'Improve this code'<CR>
+```
+
+### Shell Aliases
+
+```bash
+# ~/.bashrc or ~/.zshrc
+alias explain='askcii "Explain this command:"'
+alias review='git diff | askcii "Review this code:"'
+alias commit-msg='git diff --staged | askcii -p "Write a commit message:" | head -1'
+alias tldr='askcii "Summarize in 3 bullets:"'
+```
+
+### Makefiles
+
+```makefile
+.PHONY: analyze
+analyze:
+	@find src/ -name "*.rb" -exec cat {} \; | askcii 'Code quality report' > analysis.txt
+	@echo "Analysis saved to analysis.txt"
 ```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+```bash
+# Setup
+git clone https://github.com/yourusername/askcii.git
+cd askcii
+bin/setup
+
+# Run locally
+bin/askcii 'Test prompt'
+
+# Run tests
+rake test
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+# Interactive console
+bin/console
+
+# Build and install locally
+bundle exec rake build
+bundle exec rake install
+```
+
+## Why Askcii?
+
+**Unix Philosophy**: Do one thing well. Askcii is a filter, not an application.
+
+**Provider Agnostic**: Switch between OpenAI, Anthropic, local models—same interface.
+
+**Session Awareness**: Maintain context when needed, forget when you don't.
+
+**Privacy First**: Private mode and local model support for sensitive workflows.
+
+**Scriptable**: Integrates into automation, cron jobs, CI/CD pipelines.
+
+**Composable**: Works with every other Unix tool you already know.
+
+**Terminal Native**: No context switching, no browser tabs, no GUI overhead.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+MIT License - See [LICENSE](https://opensource.org/licenses/MIT)
+
+---
+
+**Askcii**: Because the best interface is the one you're already using.

data/completions/README.md

@@ -0,0 +1,64 @@
+# Shell Completions
+
+This directory contains shell completion scripts for askcii.
+
+## Installation
+
+### Bash
+
+Add the following to your `~/.bashrc` or `~/.bash_profile`:
+
+```bash
+source /path/to/askcii/completions/askcii.bash
+```
+
+Or copy the completion file to your bash completions directory:
+
+```bash
+# On macOS with Homebrew:
+cp completions/askcii.bash $(brew --prefix)/etc/bash_completion.d/askcii
+
+# On Linux:
+sudo cp completions/askcii.bash /etc/bash_completion.d/askcii
+```
+
+### Zsh
+
+Add the following to your `~/.zshrc`:
+
+```zsh
+fpath=(~/path/to/askcii/completions $fpath)
+autoload -Uz compinit && compinit
+```
+
+Or copy the completion file to your zsh completions directory:
+
+```bash
+# Create completions directory if it doesn't exist
+mkdir -p ~/.zsh/completions
+
+# Copy the completion file
+cp completions/askcii.zsh ~/.zsh/completions/_askcii
+
+# Add to ~/.zshrc if not already present:
+# fpath=(~/.zsh/completions $fpath)
+# autoload -Uz compinit && compinit
+```
+
+## Features
+
+- Completes all command-line flags
+- Suggests configuration IDs after `-m` or `--model` flags (bash only)
+- Provides contextual help for each flag
+
+## Reload Shell
+
+After installation, reload your shell or source your configuration file:
+
+```bash
+# For bash
+source ~/.bashrc
+
+# For zsh
+source ~/.zshrc
+```

data/completions/askcii.bash

@@ -0,0 +1,29 @@
+# bash completion for askcii
+
+_askcii() {
+    local cur prev opts
+    COMPREPLY=()
+    cur="${COMP_WORDS[COMP_CWORD]}"
+    prev="${COMP_WORDS[COMP_CWORD-1]}"
+    opts="-p --private -r --last-response -c --configure -m --model -v --verbose --session --list-sessions --history --clear-history -h --help"
+
+    # Complete configuration IDs after -m/--model
+    if [[ ${prev} == "-m" || ${prev} == "--model" ]]; then
+        # Try to get configuration IDs from askcii
+        local configs=$(askcii -c 2>/dev/null | grep -oP '^\s+\d+\.' | tr -d ' .')
+        COMPREPLY=( $(compgen -W "${configs}" -- ${cur}) )
+        return 0
+    fi
+
+    # Complete session names after --session
+    if [[ ${prev} == "--session" ]]; then
+        # Could list available sessions here
+        return 0
+    fi
+
+    # Complete flags
+    COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
+    return 0
+}
+
+complete -F _askcii askcii