elelem

Elelem

Elelem is an interactive REPL (Read-Eval-Print Loop) for Ollama that provides a command-line chat interface for communicating with AI models. It features tool calling capabilities, streaming responses, and a clean state machine architecture.

Installation

Install the gem and add to the application's Gemfile by executing:

bundle add elelem

If bundler is not being used to manage dependencies, install the gem by executing:

gem install elelem

Usage

Start an interactive chat session with an Ollama model:

elelem chat

Options

• --host: Specify Ollama host (default: localhost:11434)
• --model: Specify Ollama model (default: gpt-oss, currently only tested with gpt-oss)
• --token: Provide authentication token
• --debug: Enable debug logging

Examples

# Chat with default model
elelem chat

# Chat with specific model and host
elelem chat --model llama2 --host remote-host:11434

# Enable debug mode
elelem chat --debug

Features

• Interactive REPL: Clean command-line interface for chatting
• Tool Execution: Execute shell commands when requested by the AI
• Streaming Responses: Real-time streaming of AI responses
• State Machine: Robust state management for different interaction modes
• Conversation History: Maintains context across the session

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.

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.

REPL State Diagram

                      ┌─────────────────┐
                      │   START/INIT    │
                      └─────────┬───────┘
                                │
                                v
                      ┌─────────────────┐
                ┌────▶│ IDLE (Prompt)   │◄────┐
                │     │   Shows "> "    │     │
                │     └─────────┬───────┘     │
                │               │             │
                │               │ User input  │
                │               v             │
                │     ┌─────────────────┐     │
                │     │ PROCESSING      │     │
                │     │ INPUT           │     │
                │     └─────────┬───────┘     │
                │               │             │
                │               │ API call    │
                │               v             │
                │     ┌─────────────────┐     │
                │     │ STREAMING       │     │
                │ ┌──▶│ RESPONSE        │─────┤
                │ │   └─────────┬───────┘     │
                │ │             │             │ done=true
                │ │             │ Parse chunk │
                │ │             v             │
                │ │   ┌─────────────────┐     │
                │ │   │ MESSAGE TYPE    │     │
                │ │   │ ROUTING         │     │
                │ │   └─────┬─┬─┬───────┘     │
                │ │         │ │ │             │
       ┌────────┴─┴─────────┘ │ └─────────────┴──────────┐
       │                      │                          │
       v                      v                          v
  ┌─────────────┐    ┌─────────────┐          ┌─────────────┐
  │ THINKING    │    │ TOOL        │          │ CONTENT     │
  │ STATE       │    │ EXECUTION   │          │ OUTPUT      │
  │             │    │ STATE       │          │ STATE       │
  └─────────────┘    └─────┬───────┘          └─────────────┘
       │                   │                          │
       │                   │ done=false               │
       └───────────────────┼──────────────────────────┘
                           │
                           v
                 ┌─────────────────┐
                 │ CONTINUE        │
                 │ STREAMING       │
                 └─────────────────┘
                           │
                           └─────────────────┐
                                             │
       ┌─────────────────┐                   │
       │ ERROR STATE     │                   │
       │ (Exception)     │                   │
       └─────────────────┘                   │
                ▲                            │
                │ Invalid response           │
                └────────────────────────────┘

                      EXIT CONDITIONS:
                 ┌─────────────────────────┐
                 │ • User enters ""        │
                 │ • User enters "exit"    │
                 │ • EOF (Ctrl+D)          │
                 │ • nil input             │
                 └─────────────────────────┘
                            │
                            v
                 ┌─────────────────────────┐
                 │      TERMINATE          │
                 └─────────────────────────┘

Key Transitions:

• IDLE → PROCESSING: User enters any non-empty, non-"exit" input
• PROCESSING → STREAMING: API call initiated to Ollama
• STREAMING → MESSAGE ROUTING: Each chunk received is parsed
• MESSAGE ROUTING → States: Based on message content:

• thinking → THINKING STATE
• tool_calls → TOOL EXECUTION STATE
• content → CONTENT OUTPUT STATE
• Invalid format → ERROR STATE

• All States → IDLE: When done=true from API response
• TOOL EXECUTION → STREAMING: Sets done=false to continue conversation
• Any State → TERMINATE: On exit conditions

The REPL operates as a continuous loop where the primary flow is IDLE → PROCESSING → STREAMING → back to IDLE, with the streaming phase potentially cycling through multiple message types before completion.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/xlgmokha/elelem.

License

The gem is available as open source under the terms of the MIT License.