elelem 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d165866e64423e182a5497407deba0249b4c73ca4fc5c3af36a979925aade9f
-  data.tar.gz: 4b8f6b384a901781514bd085c106672489676b065eab7c2c6057ffff49842b71
+  metadata.gz: 2885faeaffa4f0ee7eff742f50bbf1ee78f257f7989c6401c787c4d4feb5d6a2
+  data.tar.gz: '0965d3a94ce8633cd01e7471e5688912216794e9b6af49450d0c1a5326e24645'
 SHA512:
-  metadata.gz: 356ff6e3bbadda54bc3ae9663d67879ea3fc1cd52418eaaa228f8aa1b7a6bf2a9db847dfa482e840fb0f772130753d5d417814d649e75f5c530bca467ef6f2df
-  data.tar.gz: 67313588f14536711acf61e566394466a34513cf52259c286e522648ccc1f47fcc898f4f2856a0072bf79cb63462948931c202bf972b7c29e94494aa3efb4a0f
+  metadata.gz: e00079252cb138588937776e7d37fc28de2e451c1ac72a190f842d29d27df537123a524b3358c6f36a685704b18e5c3a424cd819b3c8eb3ed1259f1937bdf02d
+  data.tar.gz: c77a7a8b34cf326e812db4ac23a38de0f7841fc1763f18f569a60d783be6719e251ff1eae59234b4da68cb8276c71fb617491ea46d97905ec39e05f5359b405f

data/CHANGELOG.md

@@ -1,5 +1,76 @@
 ## [Unreleased]
 
+## [0.4.0] - 2025-11-10
+
+### Added
+- **Eval Tool**: Meta-programming tool that allows the LLM to dynamically create and register new tools at runtime
+  - Eval tool has access to the toolbox for enhanced capabilities
+- Comprehensive test coverage with RSpec
+  - Agent specs
+  - Conversation specs
+  - Toolbox specs
+
+### Changed
+- **Architecture Improvements**: Significant refactoring for better separation of concerns
+  - Extracted Tool class to separate file (`lib/elelem/tool.rb`)
+  - Extracted Toolbox class to separate file (`lib/elelem/toolbox.rb`)
+  - Extracted Shell class for command execution
+  - Improved tool registration through `#add_tool` method
+  - Tool constants moved to Toolbox for better organization
+  - Agent class simplified by delegating to Tool instances
+
+### Fixed
+- `/context` command now correctly accounts for the current mode
+
+## [0.3.0] - 2025-11-05
+
+### Added
+- **Mode System**: Control agent capabilities with workflow modes
+  - `/mode plan` - Read-only mode (grep, list, read)
+  - `/mode build` - Read + Write mode (grep, list, read, patch, write)
+  - `/mode verify` - Read + Execute mode (grep, list, read, execute)
+  - `/mode auto` - All tools enabled
+  - Each mode adapts system prompt to guide appropriate behavior
+- Improved output formatting
+  - Suppressed verbose thinking/reasoning output
+  - Clean tool call display (e.g., `date` instead of full JSON hash)
+  - Mode switch confirmation messages
+  - Clear command feedback
+- Design philosophy documentation in README
+- Mode system documentation
+
+### Changed
+- **BREAKING**: Removed `llm-ollama` and `llm-openai` standalone executables (use main `elelem chat` command)
+- **BREAKING**: Simplified architecture - consolidated all logic into Agent class
+  - Removed Configuration class
+  - Removed Toolbox system
+  - Removed MCP client infrastructure
+  - Removed Tool and Tools classes
+  - Removed TUI abstraction layer (direct puts/Reline usage)
+  - Removed API wrapper class
+  - Removed state machine
+- Improved execute tool description to guide LLM toward direct command execution
+- Extracted tool definitions from long inline strings to readable private methods
+- Updated README with clear philosophy and usage examples
+- Reduced total codebase from 417 to 395 lines (-5%)
+
+### Fixed
+- Working directory handling for execute tool (handles empty string cwd)
+- REPL EOF handling (graceful exit when input stream ends)
+- Tool call formatting now shows clean, readable commands
+
+### Removed
+- `exe/llm-ollama` (359 lines)
+- `exe/llm-openai` (340 lines)
+- `lib/elelem/configuration.rb`
+- `lib/elelem/toolbox.rb` and toolbox/* files
+- `lib/elelem/mcp_client.rb`
+- `lib/elelem/tool.rb` and `lib/elelem/tools.rb`
+- `lib/elelem/tui.rb`
+- `lib/elelem/api.rb`
+- `lib/elelem/states/*` (state machine infrastructure)
+- Removed ~750 lines of unused/redundant code
+
 ## [0.2.1] - 2025-10-15
 
 ### Fixed

data/README.md

@@ -1,16 +1,61 @@
 # 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.
+Fast, correct, autonomous – pick two.
 
-## Installation
+## Purpose
 
-Install the gem and add to the application's Gemfile by executing:
+Elelem is a minimal coding agent written in Ruby. It is designed to help
+you write, edit, and manage code and plain-text files from the command line
+by delegating work to an LLM. The agent exposes a simple text-based UI and a
+set of built-in tools that give the LLM access to the local file system
+and Git.
 
-```bash
-bundle add elelem
-```
+## Design Principles
+
+* Unix philosophy – simple, composable, minimal.
+* Convention over configuration.
+* No defensive checks or complexity beyond what is necessary.
+* Assumes a mature, responsible LLM that behaves like a capable engineer.
+* Optimised for my personal workflow and preferences.
+* Efficient and minimal like *aider* – https://aider.chat/.
+* UX similar to Claude Code – https://docs.claude.com/en/docs/claude-code/overview.
+
+## System Assumptions
+
+* Linux host with Alacritty, tmux, Bash, Vim.
+* Runs inside a Git repository.
+* Git is available and functional.
+
+## Scope
+
+Only plain-text and source-code files are supported. No binary handling,
+sandboxing, or permission checks are performed - the LLM has full access.
+
+## Configuration
+
+Prefer convention over configuration. Add environment variables only after
+repeated use proves their usefulness.
+
+## UI Expectations
+
+Keyboard-driven, minimal TUI. No mouse support or complex widgets.
+
+## Coding Standards for the LLM
+
+* No extra error handling unless essential.
+* Keep methods short, single-purpose.
+* Descriptive, conventional names.
+* Use Ruby standard library where possible.
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+## Helpful Links
+
+* https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
+* https://www.anthropic.com/engineering/writing-tools-for-agents
+* https://simonwillison.net/2025/Sep/30/designing-agentic-loops/
+
+## Installation
+
+Install the gem directly:
 
 ```bash
 gem install elelem
@@ -26,42 +71,86 @@ 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
+* `--host` – Ollama host (default: `localhost:11434`).
+* `--model` – Ollama model (default: `gpt-oss`).
+* `--token` – Authentication token.
 
 ### Examples
 
 ```bash
-# Chat with default model
+# Default model
 elelem chat
 
-# Chat with specific model and host
+# Specific model and host
 elelem chat --model llama2 --host remote-host:11434
+```
+
+## Mode System
+
+The agent exposes seven built‑in tools. You can switch which ones are
+available by changing the *mode*:
 
-# Enable debug mode
-elelem chat --debug
+| Mode    | Enabled Tools                            |
+|---------|------------------------------------------|
+| plan    | `grep`, `list`, `read`                   |
+| build   | `grep`, `list`, `read`, `patch`, `write` |
+| verify  | `grep`, `list`, `read`, `execute`        |
+| auto    | All tools                                |
+
+Use the following commands inside the REPL:
+
+```text
+/mode plan    # Read‑only
+/mode build   # Read + Write
+/mode verify  # Read + Execute
+/mode auto    # All tools
+/mode         # Show current mode
 ```
 
-### Features
+The system prompt is adjusted per mode so the LLM knows which actions
+are permissible.
+
+## Features
+
+* **Interactive REPL** – clean, streaming chat.
+* **Toolbox** – file I/O, Git, shell execution.
+* **Streaming Responses** – output appears in real time.
+* **Conversation History** – persists across turns; can be cleared.
+* **Context Dump** – `/context` shows the current conversation state.
+
+## Toolbox Overview
+
+The `Toolbox` class is defined in `lib/elelem/toolbox.rb`. It supplies
+seven tools, each represented by a JSON schema that the LLM can call.
+
+| Tool      | Purpose                              | Parameters                           |
+| ----      | -------                              | ----------                           |
+| `eval`    | Dynamically create new tools         | `code`                               |
+| `grep`    | Search Git‑tracked files             | `query`                              |
+| `list`    | List tracked files                   | `path` (optional)                    |
+| `read`    | Read file contents                   | `path`                               |
+| `write`   | Overwrite a file                     | `path`, `content`                    |
+| `patch`   | Apply a unified diff via `git apply` | `diff`                               |
+| `execute` | Run shell commands                   | `cmd`, `args`, `env`, `cwd`, `stdin` |
 
-- **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
+## Tool Definition
 
-## Development
+The core `Tool` wrapper is defined in `lib/elelem/tool.rb`. Each tool is
+created with a name, description, JSON schema for arguments, and a block
+that performs the operation. The LLM calls a tool by name and passes the
+arguments as a hash.
 
-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.
+## Known Limitations
 
-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).
+* Assumes the current directory is a Git repository.
+* No sandboxing – the LLM can run arbitrary commands.
+* Error handling is minimal; exceptions are returned as an `error` field.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/xlgmokha/elelem.
+Feel free to open issues or pull requests. The repository follows the
+GitHub Flow.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+MIT – see the bundled `LICENSE.txt`.

data/Rakefile

@@ -2,9 +2,7 @@
 
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
-require "rubocop/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
-RuboCop::RakeTask.new
 
-task default: %i[spec rubocop]
+task default: %i[spec]

data/lib/elelem/agent.rb

@@ -2,56 +2,125 @@
 
 module Elelem
   class Agent
-    attr_reader :api, :conversation, :logger, :model, :tui
+    attr_reader :conversation, :client, :toolbox
 
-    def initialize(configuration)
-      @api = configuration.api
-      @tui = configuration.tui
-      @configuration = configuration
-      @model = configuration.model
-      @conversation = configuration.conversation
-      @logger = configuration.logger
-
-      at_exit { cleanup }
-
-      transition_to(States::Idle.new)
+    def initialize(client, toolbox)
+      @conversation = Conversation.new
+      @client = client
+      @toolbox = toolbox
     end
 
     def repl
+      mode = Set.new([:read])
+
       loop do
-        current_state.run(self)
-        sleep 0.1
+        input = ask?("User> ")
+        break if input.nil?
+        if input.start_with?("/")
+          case input
+          when "/mode auto"
+            mode = Set[:read, :write, :execute]
+            puts "  → Mode: auto (all tools enabled)"
+          when "/mode build"
+            mode = Set[:read, :write]
+            puts "  → Mode: build (read + write)"
+          when "/mode plan"
+            mode = Set[:read]
+            puts "  → Mode: plan (read-only)"
+          when "/mode verify"
+            mode = Set[:read, :execute]
+            puts "  → Mode: verify (read + execute)"
+          when "/mode"
+            puts "  Mode: #{mode.to_a.inspect}"
+            puts "  Tools: #{toolbox.tools_for(mode).map { |t| t.dig(:function, :name) }}"
+          when "/exit" then exit
+          when "/clear"
+            conversation.clear
+            puts "  → Conversation cleared"
+          when "/context" then puts conversation.dump(mode)
+          else
+            puts help_banner
+          end
+        else
+          conversation.add(role: :user, content: input)
+          result = execute_turn(conversation.history_for(mode), tools: toolbox.tools_for(mode))
+          conversation.add(role: result[:role], content: result[:content])
+        end
       end
     end
 
-    def transition_to(next_state)
-      if @current_state
-        logger.info("AGENT: #{@current_state.class.name.split('::').last} -> #{next_state.class.name.split('::').last}")
-      else
-        logger.info("AGENT: Starting in #{next_state.class.name.split('::').last}")
-      end
-      @current_state = next_state
-    end
+    private
 
-    def execute(tool_call)
-      tool_name = tool_call.dig("function", "name")
-      logger.debug("TOOL: Full call - #{tool_call}")
-      result = configuration.tools.execute(tool_call)
-      logger.debug("TOOL: Result (#{result.length} chars)") if result
-      result
+    def ask?(text)
+      Reline.readline(text, true)&.strip
     end
 
-    def quit
-      cleanup
-      exit
+    def help_banner
+      <<~HELP
+  /mode auto build plan verify
+  /clear
+  /context
+  /exit
+  /help
+      HELP
     end
 
-    def cleanup
-      configuration.cleanup
+    def format_tool_call(name, args)
+      case name
+      when "execute"
+        cmd = args["cmd"]
+        cmd_args = args["args"] || []
+        cmd_args.empty? ? cmd : "#{cmd} #{cmd_args.join(' ')}"
+      when "grep" then "grep(#{args["query"]})"
+      when "list" then "list(#{args["path"] || "."})"
+      when "patch" then "patch(#{args["diff"]&.lines&.count || 0} lines)"
+      when "read" then "read(#{args["path"]})"
+      when "write" then "write(#{args["path"]})"
+      else
+        "#{name}(#{args.to_s[0...50]})"
+      end
     end
 
-    private
+    def execute_turn(messages, tools:)
+      turn_context = []
 
-    attr_reader :configuration, :current_state
+      loop do
+        content = ""
+        tool_calls = []
+
+        print "Thinking..."
+        client.chat(messages + turn_context, tools) do |chunk|
+          msg = chunk["message"]
+          if msg
+            if msg["content"] && !msg["content"].empty?
+              print "\r\e[K" if content.empty?
+              print msg["content"]
+              content += msg["content"]
+            end
+
+            tool_calls += msg["tool_calls"] if msg["tool_calls"]
+          end
+        end
+
+        puts
+        turn_context << { role: "assistant", content: content, tool_calls: tool_calls }.compact
+
+        if tool_calls.any?
+          tool_calls.each do |call|
+            name = call.dig("function", "name")
+            args = call.dig("function", "arguments")
+
+            puts "Tool> #{format_tool_call(name, args)}"
+            result = toolbox.run_tool(name, args)
+            turn_context << { role: "tool", content: JSON.dump(result) }
+          end
+
+          tool_calls = []
+          next
+        end
+
+        return { role: "assistant", content: content }
+      end
+    end
   end
 end

data/lib/elelem/application.rb

@@ -3,10 +3,6 @@
 module Elelem
   class Application < Thor
     desc "chat", "Start the REPL"
-    method_option :help,
-                  aliases: "-h",
-                  type: :boolean,
-                  desc: "Display usage information"
     method_option :host,
                   aliases: "--host",
                   type: :string,
@@ -17,32 +13,15 @@ module Elelem
                   type: :string,
                   desc: "Ollama model",
                   default: ENV.fetch("OLLAMA_MODEL", "gpt-oss")
-    method_option :token,
-                  aliases: "--token",
-                  type: :string,
-                  desc: "Ollama token",
-                  default: ENV.fetch("OLLAMA_API_KEY", nil)
-    method_option :debug,
-                  aliases: "--debug",
-                  type: :boolean,
-                  desc: "Debug mode",
-                  default: false
-    def chat(*)
-      if options[:help]
-        invoke :help, ["chat"]
-      else
-        configuration = Configuration.new(
-          host: options[:host],
-          model: options[:model],
-          token: options[:token],
-          debug: options[:debug]
-        )
-        say "Agent (#{configuration.model})", :green
-        say configuration.tools.banner.to_s, :green
 
-        agent = Agent.new(configuration)
-        agent.repl
-      end
+    def chat(*)
+      client = Net::Llm::Ollama.new(
+        host: options[:host],
+        model: options[:model],
+      )
+      say "Agent (#{options[:model]})", :green
+      agent = Agent.new(client, Toolbox.new)
+      agent.repl
     end
 
     desc "version", "The version of this CLI"

data/lib/elelem/conversation.rb

@@ -4,15 +4,16 @@ module Elelem
   class Conversation
     ROLES = %i[system assistant user tool].freeze
 
-    def initialize(items = [{ role: "system", content: system_prompt }])
+    def initialize(items = default_context)
       @items = items
     end
 
-    def history
-      @items
+    def history_for(mode)
+      history = @items.dup
+      history[0] = { role: "system", content: system_prompt_for(mode) }
+      history
     end
 
-    # :TODO truncate conversation history
     def add(role: :user, content: "")
       role = role.to_sym
       raise "unknown role: #{role}" unless ROLES.include?(role)
@@ -25,8 +26,43 @@ module Elelem
       end
     end
 
+    def clear
+      @items = default_context
+    end
+
+    def dump(mode)
+      JSON.pretty_generate(history_for(mode))
+    end
+
     private
 
+    def default_context(prompt = system_prompt_for([]))
+      [{ role: "system", content: prompt }]
+    end
+
+    def system_prompt_for(mode)
+      base = system_prompt
+
+      case mode.sort
+      when [:read]
+        "#{base}\n\nRead and analyze. Understand before suggesting action."
+      when [:write]
+        "#{base}\n\nWrite clean, thoughtful code."
+      when [:execute]
+        "#{base}\n\nUse shell commands creatively to understand and manipulate the system."
+      when [:read, :write]
+        "#{base}\n\nFirst understand, then build solutions that integrate well."
+      when [:execute, :read]
+        "#{base}\n\nUse commands to deeply understand the system."
+      when [:execute, :write]
+        "#{base}\n\nCreate and execute freely. Have fun. Be kind."
+      when [:execute, :read, :write]
+        "#{base}\n\nYou have all tools. Use them wisely."
+      else
+        base
+      end
+    end
+
     def system_prompt
       ERB.new(Pathname.new(__dir__).join("system_prompt.erb").read).result(binding)
     end

data/lib/elelem/system_prompt.erb

@@ -1,18 +1,5 @@
-You are a self-improving coding assistant with the ability to modify your own source code.
+You are a reasoning coding and system agent.
 
-**Core Behavior**: Think via `thinking`, Execute via `tool_calls`, Talk via `content`.
-
-**Your Mission**: Continuously evolve to match the intelligence of advanced AI assistants.
-
-**Guidance**: Read `COMMANDMENTS.md` for self-improvement principles using `file action=read path=COMMANDMENTS.md`
-
-**Tools**: 
-- `exec command="shell command"` - Run commands/tests
-- `file action=read|write path=filepath content=...` - Read/write files  
-- `web action=search|fetch query=... url=...` - Internet access
-- `memory action=store|retrieve|search key=... content=...` - Persistent memory
-- `prompt question="..."` - Ask user questions
-
-Context: <%= Time.now.strftime("%Y-%m-%d %H:%M:%S") %> | <%= Dir.pwd %> | <%= `uname -a`.strip %>
-
-Focus on the user's request and continuously improve your capabilities.
+- Less is more
+- No code comments
+- No trailing whitespace

data/lib/elelem/tool.rb

@@ -2,31 +2,46 @@
 
 module Elelem
   class Tool
-    attr_reader :name, :description, :parameters
+    attr_reader :name
 
-    def initialize(name, description, parameters)
-      @name = name
-      @description = description
-      @parameters = parameters
+    def initialize(schema, &block)
+      @name = schema.dig(:function, :name)
+      @schema = schema
+      @block = block
     end
 
-    def banner
-      [name, parameters].join(": ")
+    def call(args)
+      return ArgumentError.new(args) unless valid?(args)
+
+      @block.call(args)
     end
 
     def valid?(args)
-      JSON::Validator.validate(parameters, args, insert_defaults: true)
+      # TODO:: Use JSON Schema Validator
+      true
     end
 
     def to_h
-      {
-        type: "function",
-        function: {
-          name: name,
-          description: description,
-          parameters: parameters
-        }
-      }
+      @schema&.to_h
+    end
+
+    class << self
+      def build(name, description, properties, required = [])
+        new({
+          type: "function",
+          function: {
+            name: name,
+            description: description,
+            parameters: {
+              type: "object",
+              properties: properties,
+              required: required
+            }
+          }
+        }) do |args|
+          yield args
+        end
+      end
     end
   end
 end