askcii 0.2.0 → 0.4.0

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

data/completions/askcii.zsh

@@ -0,0 +1,27 @@
+#compdef askcii
+
+_askcii() {
+    local -a opts
+    opts=(
+        '-p[Start a private session]'
+        '--private[Start a private session]'
+        '-r[Output the last response]'
+        '--last-response[Output the last response]'
+        '-c[Manage configurations]'
+        '--configure[Manage configurations]'
+        '-m[Use specific configuration ID]:config_id:'
+        '--model[Use specific configuration ID]:config_id:'
+        '-v[Show detailed information]'
+        '--verbose[Show detailed information]'
+        '--session[Use specific session name]:session_name:'
+        '--list-sessions[List all available sessions]'
+        '--history[Show current session history]'
+        '--clear-history[Clear current session history]'
+        '-h[Show help message]'
+        '--help[Show help message]'
+    )
+
+    _arguments -s $opts '*:prompt text:'
+}
+
+_askcii "$@"

data/lib/askcii/application.rb

@@ -1,11 +1,20 @@
 # frozen_string_literal: true
 
 require_relative 'cli'
-require_relative 'configuration_manager'
-require_relative 'chat_session'
+require_relative 'commands/base_command'
+require_relative 'commands/help_command'
+require_relative 'commands/configure_command'
+require_relative 'commands/last_response_command'
+require_relative 'commands/chat_command'
+require_relative 'commands/list_sessions_command'
+require_relative 'commands/history_command'
+require_relative 'commands/clear_history_command'
 
 module Askcii
+  # Main application controller that routes to appropriate commands
   class Application
+    attr_reader :cli
+
     def initialize(args = ARGV.dup)
       @cli = CLI.new(args)
     end
@@ -13,58 +22,98 @@ module Askcii
     def run
       @cli.parse!
 
-      if @cli.show_help?
-        puts @cli.help_message
-        exit 0
-      end
-
-      if @cli.configure?
-        ConfigurationManager.new.run
-        exit 0
-      end
-
+      # Handle usage display
       if @cli.show_usage?
-        puts @cli.usage_message
+        puts Commands::HelpCommand.new(@cli).execute
         exit 1
       end
 
-      selected_config = determine_configuration
-      configure_llm(selected_config)
-
-      chat_session = ChatSession.new(@cli.options, selected_config)
-      chat_session.handle_last_response if @cli.last_response?
-
-      input = read_stdin_input
-      chat_session.execute_chat(@cli.prompt, input)
+      # Determine and execute the appropriate command
+      command = determine_command
+      command.execute
+    rescue ConfigurationError => e
+      $stderr.puts "Configuration Error: #{e.message}"
+      $stderr.puts "Run 'askcii -c' to configure providers."
+      exit 1
+    rescue ValidationError => e
+      $stderr.puts "Validation Error: #{e.message}"
+      exit 1
+    rescue SessionError => e
+      $stderr.puts "Session Error: #{e.message}"
+      exit 1
+    rescue => e
+      $stderr.puts "Error: #{e.message}"
+      $stderr.puts e.backtrace.join("\n") if @cli.verbose?
+      exit 1
     end
 
     private
 
+    # Determines which command to execute based on CLI flags
+    # @return [Commands::BaseCommand]
+    def determine_command
+      return Commands::HelpCommand.new(@cli) if @cli.help?
+      return Commands::ConfigureCommand.new(@cli) if @cli.configure?
+      return Commands::ListSessionsCommand.new(@cli) if @cli.list_sessions?
+      return Commands::HistoryCommand.new(@cli) if @cli.history?
+      return Commands::ClearHistoryCommand.new(@cli) if @cli.clear_history?
+      return Commands::LastResponseCommand.new(@cli) if @cli.last_response?
+
+      # Default to chat command
+      config = determine_configuration
+      configure_llm(config)
+      Commands::ChatCommand.new(@cli, config)
+    end
+
+    # Determines which configuration to use based on CLI flags and defaults
+    # @return [Hash] Configuration hash
     def determine_configuration
+      # Priority 1: Explicit configuration ID from CLI
       if @cli.model_config_id
         config = Askcii::Config.get_configuration(@cli.model_config_id)
-        return config if config
+        return symbolize_keys(config) if config
+        $stderr.puts "Warning: Configuration ID #{@cli.model_config_id} not found, using default"
       end
 
+      # Priority 2: Default configuration from database
       config = Askcii::Config.current_configuration
-      return config if config
+      return symbolize_keys(config) if config
+
+      # Priority 3: Legacy environment variables or error
+      legacy_config = load_legacy_env_config
+      return symbolize_keys(legacy_config) if legacy_config
+
+      # No configuration available
+      raise ConfigurationError, "No configuration found. Run 'askcii -c' to configure."
+    end
+
+    # Loads legacy configuration from environment variables
+    # @return [Hash, nil]
+    def load_legacy_env_config
+      return nil unless ENV['ASKCII_API_KEY']
 
-      # Fallback to environment variables
       {
+        'provider' => 'openai',
         'api_key' => ENV['ASKCII_API_KEY'],
-        'api_endpoint' => ENV['ASKCII_API_ENDPOINT'],
-        'model_id' => ENV['ASKCII_MODEL_ID']
+        'api_endpoint' => ENV['ASKCII_API_ENDPOINT'] || ProviderConfig.default_endpoint('openai'),
+        'model_id' => ENV['ASKCII_MODEL_ID'] || 'gpt-3.5-turbo',
+        'name' => 'Legacy (from env vars)'
       }
     end
 
-    def configure_llm(selected_config)
-      Askcii.configure_llm(selected_config)
+    # Configures the LLM library with the selected configuration
+    # @param config [Hash] Configuration hash
+    def configure_llm(config)
+      Askcii.configure_llm(config)
     end
 
-    def read_stdin_input
-      return nil if $stdin.tty?
+    # Converts string keys to symbols for consistency
+    # @param hash [Hash] Hash with string keys
+    # @return [Hash] Hash with symbol keys
+    def symbolize_keys(hash)
+      return {} unless hash
 
-      $stdin.read
+      hash.transform_keys { |key| key.to_sym }
     end
   end
 end

data/lib/askcii/chat_factory.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module Askcii
+  # Factory for creating chat instances (private or persistent)
+  class ChatFactory
+    attr_reader :config, :private, :session_context
+
+    # @param config [Hash] Configuration with provider, api_key, model_id, etc.
+    # @param private [Boolean] Whether to create a private (non-persistent) chat
+    # @param session_context [String, nil] Session identifier for persistent chats
+    def initialize(config:, private: false, session_context: nil)
+      @config = config
+      @private = private
+      @session_context = session_context || generate_session_id
+    end
+
+    # Creates and returns a chat instance
+    # @return [RubyLLM::Chat] Chat instance ready for use
+    def create
+      private ? create_private_chat : create_persistent_chat
+    end
+
+    # Gets the system instruction from config or uses default
+    # @return [String] System instruction
+    def system_instruction
+      config[:system_instruction] ||
+        config['system_instruction'] ||
+        default_system_instruction
+    end
+
+    private
+
+    # Creates a private (ephemeral) chat with no database persistence
+    # @return [RubyLLM::Chat]
+    def create_private_chat
+      provider = config[:provider] || config['provider']
+      model_id = config[:model_id] || config['model_id']
+
+      RubyLLM.chat(
+        provider: provider.to_sym,
+        model_id: model_id,
+        assume_model_exists: true
+      )
+    end
+
+    # Creates a persistent chat backed by database
+    # @return [RubyLLM::Chat]
+    def create_persistent_chat
+      model_id = config[:model_id] || config['model_id']
+
+      # Find or create chat record
+      chat_record = Chat.find_or_create(context: session_context) do |chat|
+        chat.model_id = model_id
+      end
+
+      # Update model_id if it changed
+      if chat_record.model_id != model_id
+        chat_record.update(model_id: model_id)
+      end
+
+      # Convert to RubyLLM chat with history
+      chat_record.to_llm(config)
+    end
+
+    # Generates a unique session identifier
+    # @return [String] 32-character hex string
+    def generate_session_id
+      SecureRandom.hex(16)
+    end
+
+    # Default system instruction for terminal-friendly responses
+    # @return [String]
+    def default_system_instruction
+      'You are a command line application. Provide concise, terminal-friendly responses. ' \
+        'Assume technical proficiency. Minimize explanations unless requested.'
+    end
+  end
+end

data/lib/askcii/chat_session.rb

@@ -1,70 +1,97 @@
 # frozen_string_literal: true
 
-require 'securerandom'
+require_relative 'chat_factory'
 
 module Askcii
+  # Orchestrates chat execution with LLM providers
   class ChatSession
-    def initialize(options, selected_config)
-      @options = options
-      @selected_config = selected_config
+    attr_reader :config, :private, :session_context, :verbose
+
+    # @param config [Hash] Configuration with provider, api_key, model_id, etc.
+    # @param private [Boolean] Whether to create a private (non-persistent) chat
+    # @param session_context [String, nil] Session identifier for persistent chats
+    # @param verbose [Boolean] Whether to output verbose information
+    def initialize(config:, private: false, session_context: nil, verbose: false)
+      @config = config
+      @private = private
+      @session_context = session_context
+      @verbose = verbose
     end
 
-    def handle_last_response
-      return unless @options[:last_response]
+    # Executes a chat session with the given prompt
+    # @param prompt [String] User prompt
+    # @param input [String, nil] Additional input to prepend to prompt
+    def execute_chat(prompt, input = nil)
+      validate_prompt!(prompt)
+      warn_large_input!(prompt, input)
+
+      chat = create_chat
+      full_prompt = build_prompt(prompt, input)
 
-      context = ENV['ASKCII_SESSION'] || SecureRandom.hex(8)
-      model_id = @selected_config['model_id']
-      chat_record = Askcii::Chat.find_or_create(context: context, model_id: model_id)
+      verbose_output "Sending prompt (#{full_prompt.bytesize} bytes)..."
 
-      last_message = chat_record.messages.where(role: 'assistant').last
-      if last_message
-        puts last_message.content
-        exit 0
-      else
-        puts 'No previous response found.'
-        exit 1
+      # Execute the chat with streaming
+      chat.ask(full_prompt) do |chunk|
+        print chunk.content
       end
+      puts '' # Ensure we end with a newline
     end
 
+    private
+
+    # Creates a chat instance using ChatFactory
+    # @return [RubyLLM::Chat]
     def create_chat
-      if @options[:private]
-        create_private_chat
-      else
-        create_persistent_chat
-      end
-    end
+      factory = ChatFactory.new(
+        config: config,
+        private: private,
+        session_context: session_context
+      )
 
-    def execute_chat(prompt, input = nil)
-      chat = create_chat
+      chat = factory.create
 
-      chat.with_instructions 'You are a command line application. Your responses should be suitable to be read in a terminal. Your responses should only include the necessary text. Do not include any explanations unless prompted for it.'
+      # Apply system instructions
+      chat.with_instructions(factory.system_instruction)
 
-      full_prompt = input ? "With the following text:\n\n#{input}\n\n#{prompt}" : prompt
+      verbose_output "Chat created (#{private ? 'private' : 'persistent'})"
 
-      chat.ask(full_prompt) do |chunk|
-        print chunk.content
-      end
-      puts ''
+      chat
     end
 
-    private
+    # Validates that the prompt is not empty
+    # @param prompt [String]
+    # @raise [ValidationError] if prompt is empty
+    def validate_prompt!(prompt)
+      raise ValidationError, "Prompt cannot be empty" if prompt.to_s.strip.empty?
+    end
 
-    def create_private_chat
-      provider_symbol = @selected_config['provider'] ? @selected_config['provider'].to_sym : :openai
-      model_id = @selected_config['model_id']
+    # Warns if input is very large
+    # @param prompt [String]
+    # @param input [String, nil]
+    def warn_large_input!(prompt, input)
+      combined = [input, prompt].compact.join("\n\n")
+      size_bytes = combined.bytesize
 
-      RubyLLM.chat(
-        model: model_id,
-        provider: provider_symbol,
-        assume_model_exists: true
-      )
+      return unless size_bytes > 1_000_000 # 1MB
+
+      size_kb = size_bytes / 1024
+      $stderr.puts "Warning: Input size is #{size_kb}KB. This may be slow or fail."
+    end
+
+    # Builds the full prompt by combining input and prompt
+    # @param prompt [String]
+    # @param input [String, nil]
+    # @return [String]
+    def build_prompt(prompt, input)
+      return prompt unless input
+
+      "With the following text:\n\n#{input}\n\n#{prompt}"
     end
 
-    def create_persistent_chat
-      context = ENV['ASKCII_SESSION'] || SecureRandom.hex(8)
-      model_id = @selected_config['model_id']
-      chat_record = Askcii::Chat.find_or_create(context: context, model_id: model_id)
-      chat_record.to_llm
+    # Outputs verbose information if verbose mode is enabled
+    # @param message [String]
+    def verbose_output(message)
+      $stderr.puts message if verbose
     end
   end
 end

data/lib/askcii/cli.rb

@@ -23,7 +23,11 @@ module Askcii
     end
 
     def show_usage?
-      @prompt.empty? && !configure? && !last_response?
+      @prompt.empty? && !configure? && !last_response? && !list_sessions? && !history? && !clear_history?
+    end
+
+    def help?
+      @options[:help]
     end
 
     def configure?
@@ -38,10 +42,30 @@ module Askcii
       @options[:private]
     end
 
+    def verbose?
+      @options[:verbose]
+    end
+
     def model_config_id
       @options[:model_config_id]
     end
 
+    def session
+      @options[:session]
+    end
+
+    def list_sessions?
+      @options[:list_sessions]
+    end
+
+    def history?
+      @options[:history]
+    end
+
+    def clear_history?
+      @options[:clear_history]
+    end
+
     def help_message
       option_parser.to_s
     end
@@ -50,8 +74,10 @@ module Askcii
       <<~USAGE
         Usage:
           askcii [options] 'Your prompt here'
-          echo 'Your prompt here' | askcii 'Your prompt here'
-          askcii 'Your prompt here' < prompt.txt
+          echo 'Your prompt here' | askcii                    # Use piped text as prompt
+          echo 'Context text' | askcii 'Your prompt here'     # Use piped text as context
+          askcii 'Your prompt here' < prompt.txt              # Use file content as context
+          cat prompt.txt | askcii                             # Use file content as prompt
           askcii -p (start a private session)
           askcii -r (to get the last response)
           askcii -c (manage configurations)
@@ -88,6 +114,26 @@ module Askcii
           @options[:model_config_id] = model_id
         end
 
+        opts.on('-v', '--verbose', 'Show detailed information during execution') do
+          @options[:verbose] = true
+        end
+
+        opts.on('--session NAME', 'Use specific session name') do |session|
+          @options[:session] = session
+        end
+
+        opts.on('--list-sessions', 'List all available sessions') do
+          @options[:list_sessions] = true
+        end
+
+        opts.on('--history', 'Show current session history') do
+          @options[:history] = true
+        end
+
+        opts.on('--clear-history', 'Clear current session history') do
+          @options[:clear_history] = true
+        end
+
         opts.on('-h', '--help', 'Show this help message') do
           @options[:help] = true
         end

data/lib/askcii/commands/base_command.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Askcii
+  module Commands
+    # Base class for all command implementations
+    class BaseCommand
+      attr_reader :cli, :config
+
+      # @param cli [CLI] Parsed CLI arguments
+      # @param config [Hash, nil] Configuration (if applicable)
+      def initialize(cli, config = nil)
+        @cli = cli
+        @config = config
+      end
+
+      # Executes the command
+      # @return [void]
+      def execute
+        raise NotImplementedError, "#{self.class} must implement #execute"
+      end
+
+      protected
+
+      # Prints error message to stderr and exits
+      # @param message [String] Error message
+      # @param exit_code [Integer] Exit code (default: 1)
+      def error!(message, exit_code: 1)
+        $stderr.puts "Error: #{message}"
+        exit exit_code
+      end
+
+      # Prints verbose output if verbose mode is enabled
+      # @param message [String] Message to print
+      def verbose(message)
+        $stderr.puts message if cli.verbose?
+      end
+
+      # Gets the session context from CLI or environment
+      # @return [String]
+      def session_context
+        cli.session || ENV['ASKCII_SESSION'] || SecureRandom.hex(16)
+      end
+    end
+  end
+end

data/lib/askcii/commands/chat_command.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Askcii
+  module Commands
+    # Executes a chat session with the LLM
+    class ChatCommand < BaseCommand
+      def execute
+        validate_config!
+        display_config_info if cli.verbose?
+
+        # Read from stdin if available
+        stdin_input = read_stdin_input
+
+        # Execute the chat
+        require_relative '../chat_session'
+        session = ChatSession.new(
+          config: config,
+          private: cli.private?,
+          session_context: session_context,
+          verbose: cli.verbose?
+        )
+
+        session.execute_chat(cli.prompt, stdin_input)
+      end
+
+      private
+
+      def validate_config!
+        return if config
+
+        error! "No configuration available. Run 'askcii -c' to configure."
+      end
+
+      def display_config_info
+        provider = config[:provider] || config['provider']
+        model_id = config[:model_id] || config['model_id']
+        config_name = config[:name] || config['name'] || 'Unnamed'
+
+        verbose "Using configuration: #{config_name}"
+        verbose "Provider: #{provider}"
+        verbose "Model: #{model_id}"
+        verbose "Session: #{session_context}"
+        verbose "Private mode: #{cli.private?}"
+      end
+
+      def read_stdin_input
+        return nil if $stdin.tty?
+
+        verbose "Reading from stdin..."
+        input = $stdin.read.strip
+        verbose "Read #{input.bytesize} bytes from stdin"
+        input.empty? ? nil : input
+      end
+    end
+  end
+end