hellm 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 11522217c18c262d67881d31f50efb136d43fb3f9465c3ed25cbf95659b927ef
-  data.tar.gz: bf00259cd39073946654e42e8c63a04fe95310fbd94b12d772929c7fc8194b5c
+  metadata.gz: 7e145f6843dcffe58f1bcd576ca4c945d2e9727caf765500cf228cbb44d77c9e
+  data.tar.gz: 6ce567f6e7d01083a5a9b21b2ef82476b17e1ccbac249c201291b436f15b6055
 SHA512:
-  metadata.gz: cf31d07cca0558b43e1fbbcaf338493e268352867e450b1f98cda732f8728fe5685dbb6a10e23ccb749e7b323d59e3673e0bdaace0a2629c623c83013bb2355d
-  data.tar.gz: 48919c27642fba873c2d4348b933fc899bb3735e42e57590639c058cb835462727c3ac91861754ba279aebf4c82eae7d9e737884c4fbae486130e89534d8fea1
+  metadata.gz: 4cfd84c50054e316c6e402f9360599bca016e3f1b8f36db599bd97f1ffe8a4bc951b110c6c462b7e9846a7485fe6394c74c72fac41391795c24e1bdbcf807322
+  data.tar.gz: 268ad8d66f1a59e8583a46d09b06efa1114d68c6c9e182b998bb818da6e2a1b24b6519494da34695c5aba6c4d71b95bfd9563b41b9280a27935ee62240480786

data/ARCHITECTURE.md

@@ -23,8 +23,8 @@ Main source folders:
 
 ```mermaid
 flowchart TD
-  A[CLI: bin/hellm] --> B[Hellm.build_agent]
-  B --> C[Hellm::Builder]
+  A[CLI: bin/hellm] --> B[Hellm.open_project]
+  B --> C[Hellm::Project]
   C --> D[Load agents from .hellm/agents]
   C --> E[Load skills from .hellm/skills/**/SKILL.md]
   C --> F[Register builtin tools in Registry]
@@ -45,14 +45,14 @@ Location: lib/hellm.rb
 
 Responsibilities:
 - Stores global API key fallback from OPENAI_API_KEY
-- Builds an agent through Hellm::Builder
+- Builds an agent through Hellm::Project
 - Exposes logger and log-level integration with Langchain
 
 Design notes:
 - Global mutable state is limited to logger and API key.
 - Agent construction delegates to Builder to keep orchestration out of the top-level API.
 
-### Hellm::Builder
+### Hellm::Project
 
 Location: lib/hellm/builder.rb
 
@@ -76,7 +76,6 @@ Responsibilities:
 - Wraps Langchain::Assistant lifecycle and message exchange
 - Converts configured tool names to tool instances via Registry
 - Adds text and image input messages
-- Streams callbacks through StreamAdapter
 - Executes with retry logic for transient rate-limit errors
 
 Behavior details:
@@ -100,13 +99,13 @@ Location: lib/hellm/skill.rb
 Responsibilities:
 - Value object representing skill metadata and markdown content
 
-### Hellm::StreamAdapter
+### Hellm::Sesstion
 
-Location: lib/hellm/stream_adapter.rb
+Location: lib/hellm/session.rb
 
 Responsibilities:
-- Callback interface for streamed assistant messages and tool calls
-- Base implementation is intentionally empty and intended for customization
+- Callback interface for streamed assistant messages
+- Base implementation is intended for customization
 
 ## Tooling Architecture
 
@@ -121,7 +120,6 @@ Responsibilities:
 - Creates and registers sub-agent tools
 
 Key implications:
-- Tool instances are shared after first creation.
 - Custom tools should avoid mutable request-specific state.
 
 ### Hellm::Tools::SkillTool
@@ -178,10 +176,10 @@ Project configuration is stored in a `.hellm` directory with the following struc
 ## Extension Points
 
 Supported extension seams:
-- Register additional tools via Hellm::Tools::Registry.instance.add
+- Register additional tools via Hellm::Tools::Registry#add
 - Add new agents by placing markdown files in .hellm/agents
 - Add new skills by placing SKILL.md files in .hellm/skills
-- Provide a custom StreamAdapter implementation for telemetry or UI streaming
+- Provide a custom Session implementation for telemetry/UI streaming/restorability/resumeability
 
 ## Known Risks And Gaps
 

data/README.md

@@ -51,8 +51,8 @@ The framework provides the following tools for agents to use:
 | ------------- | ----------------------- | ------------------------------------------------------- |
 | `calculator`  |                         | a simple calculator for basic arithmetic operations.    |
 | `webfetch`    | `web`                   | fetches web pages or other content from URLs.           |
-| `websearch`   | `web`                   | performs web searches and returns search results.       |
-| `web`         |                         | combines web fetching and web searching capabilities.   |
+| `websearch`   | `web`                   | performs web searches and returns search results. utilizes [Brave Search API](https://brave.com/search/api/), which needs environment variable BRAVE_API_KEY to be set to a valid API key. |
+| `web`         |                         | combines `webfetch` and `websearch` capabilities.       |
 
 
 ### Custom Tools
@@ -60,7 +60,9 @@ The framework provides the following tools for agents to use:
 Custom tools can be defined using `Langchain::ToolDefinition`, like it is described in the [Langchain documentation](https://github.com/patterns-ai-core/langchainrb#creating-custom-tools). Such tools need to be registered in `Hellm` before they can be used by agents:
 
 ```ruby
-Hellm::Tools::Registry.instance.add(:calculator) do
+project = Hellm.open_project("/path/to/project")
+
+project.registry.add(:calculator) do
   Langchain::Tool::Calculator.new
 end
 ```

data/VERSION

@@ -1 +1 @@
-0.0.4
+0.0.5

data/lib/hellm/agent.rb

@@ -1,13 +1,10 @@
-require_relative "stream_adapter"
+require_relative "session"
 require_relative "tools/registry"
 require "base64"
 require "langchain"
 
 class Hellm::Agent
-  attr_accessor :name, :llm, :description, :agents
-
-  # @param stream_adapter [Hellm::StreamAdapter] an object that responds to `message` and `tool_call` for streaming messages and tool calls
-  attr_accessor :stream_adapter
+  attr_accessor :name, :llm, :description, :agents, :registry
 
   # instructions (string) for the agent.
   attr_accessor :instructions
@@ -28,7 +25,7 @@ class Hellm::Agent
   #
   attr_accessor :tools
 
-  def initialize(model: nil, name: nil, description: nil, stream_adapter: nil, openai_api_key: nil, agents: nil, tools: nil, instructions: nil)
+  def initialize(model: nil, name: nil, description: nil, session: nil, openai_api_key: nil, agents: nil, tools: nil, instructions: nil, registry: nil)
     model ||= "gpt-5-nano"
     Hellm.logger.debug("Initializing agent #{name} (#{model})")
     @llm = Langchain::LLM::OpenAI.new(
@@ -38,9 +35,11 @@ class Hellm::Agent
     self.name = name || self.class.name
     self.description = description || ""
     self.instructions = instructions || ""
-    self.stream_adapter = stream_adapter || Hellm::StreamAdapter.new
+    self.session = session || Hellm::Session.new
     self.agents = agents || []
     self.tools = tools || []
+    self.registry = registry || Hellm::Tools::Registry.new
+    @replaying_session = false
   end
 
 
@@ -64,15 +63,40 @@ class Hellm::Agent
   end
 
   def new_session
+    @session = nil
     @assistant = nil
   end
 
+  def session=(value)
+    @session = value
+    @replaying_session = true
+    @session.messages.each do |message|
+      attributes = {
+        role: fetch_indifferent(message, :role),
+        content: fetch_indifferent(message, :content),
+        image_url: fetch_indifferent(message, :image_url),
+        tool_calls: fetch_indifferent(message, :tool_calls),
+        tool_call_id: fetch_indifferent(message, :tool_call_id)
+      }
+      assistant.add_message(**attributes)
+    end
+    @replaying_session = false
+  end
+
+  def session
+    @session ||= Hellm::Session.new
+  end
+
   protected
+    def fetch_indifferent(hash, key)
+      hash[key.to_sym] || hash[key.to_s]
+    end
+
     def assistant
       if @assistant.nil?
         tool_instances = [
-          *Hellm::Tools::Registry.instance.get(*tools),
-          *Hellm::Tools::Registry.instance.get_agent_tools(*agents)
+          *self.registry.get(*tools),
+          *self.registry.get_agent_tools(*agents)
         ]
         @assistant = Langchain::Assistant.new(
           llm: llm,
@@ -81,24 +105,24 @@ class Hellm::Agent
         )
         @assistant.add_message_callback = ->(message) {
           Hellm.logger.debug("[Agent #{name} message] #{message.inspect}")
-          self.stream_adapter.message(message)
+          if @replaying_session != true
+            self.session.add_message({
+              agent: name,
+              role: message.role,
+              content: message.content,
+              image_url: message.image_url,
+              tool_calls: message.tool_calls,
+              tool_call_id: message.tool_call_id
+            })
+          end
         }
         @assistant.tool_execution_callback = ->(call_id, name, method, args) {
           Hellm.logger.debug("[Agent #{self.name} tool_call] call_id: #{call_id}, name: #{name}, method: #{method}, args: #{args}")
-          self.stream_adapter.tool_call(call_id, name, method, args)
         }
       end
       @assistant
     end
 
-    def build_instruction_preface(agent_tool)
-      preamble = "# Hints\n\n"
-      preamble = "#{preamble}You are an AI agent named #{name}. You have access to the following skills and sub-agents:\n\n"
-      preamble << agent_tool.instructions_for_agents(*agents)
-      preamble << "\n\n"
-      preamble
-    end
-
     def normalize_image_input(image_input)
       return image_input if image_input.start_with?("http://", "https://", "data:image/")
 

data/lib/hellm/{builder.rb → project.rb}

@@ -1,56 +1,61 @@
 require_relative "markdown_file"
-require_relative "stream_adapter"
+require_relative "session"
 require_relative "agent"
 require_relative "skill"
 require_relative "tools/skill_tool"
 require_relative "tools/web_fetch_tool"
 require_relative "tools/brave_search_tool"
+require_relative "tools/registry"
 
-class Hellm::Builder
-  attr_accessor :project_dir, :hellm_dir, :stream_adapter
+class Hellm::Project
+  attr_accessor :project_dir, :hellm_dir, :agents, :registry
 
   SUPPORTED_SKILL_ATTRIBUTEES = ["name", "description", "argument_hint"]
   SUPPORTED_AGENT_ATTRIBUTEES = ["model", "name", "description", "tools", "agents"]
 
-  def initialize(project_dir: nil, stream_adapter: nil, openai_api_key: nil)
-    @project_dir = project_dir
-    @hellm_dir = File.join(project_dir, ".hellm")
-    @hellm_dir = File.join(project_dir, ".github") if !Dir.exist?(@hellm_dir)
-    raise ArgumentError, "not found: #{project_dir}/.hellm" unless Dir.exist?(@hellm_dir)
+  def initialize(project_dir: nil, openai_api_key: nil)
+    self.registry = Hellm::Tools::Registry.new
+    self.project_dir = project_dir
+    self.hellm_dir = File.join(project_dir, ".hellm")
+    self.hellm_dir = File.join(project_dir, ".github") if !Dir.exist?(self.hellm_dir)
+    raise ArgumentError, "not found: #{project_dir}/.hellm" unless Dir.exist?(self.hellm_dir)
 
-    @stream_adapter = stream_adapter
     @openai_api_key = openai_api_key
-
     add_builtin_tools_to_registry
+    self.agents = build_project
   end
 
-  def build(talking_to: nil)
-    agents = get_agents_from_project_dir
-    skills = get_skills_from_project_dir
-    skill_tool = Hellm::Tools::SkillTool.new
-    skill_tool.add(*skills)
-    Hellm::Tools::Registry.instance.add(:skill, skill_tool)
-    Hellm::Tools::Registry.instance.add_agents(*agents)
-
-    if agents.empty?
+  def find_agent(name)
+    if self.agents.empty?
       agent = Hellm::Agent.new
     else
-      agent = agents.find{ |agent| agent.name == talking_to }
-      raise ArgumentError, "Agent not found: #{talking_to}" if agent.nil?
+      agent = self.agents.find{ |agent| agent.name == name }
+      raise ArgumentError, "Agent not found: #{name}" if agent.nil?
     end
     agent
   end
 
   private
+    def build_project
+      skills = build_skills_from_project_dir
+      skill_tool = Hellm::Tools::SkillTool.new
+      skill_tool.add(*skills)
+      self.registry.add(:skill, skill_tool)
+
+      agents = build_agents_from_project_dir(skill_tool)
+      self.registry.add_agents(*agents)
+      agents
+    end
+
     def add_builtin_tools_to_registry
-      Hellm::Tools::Registry.instance.add(:calculator) { Langchain::Tool::Calculator.new }
-      Hellm::Tools::Registry.instance.add(:bravesearch) { Hellm::Tools::BraveSearchTool.new }
-      Hellm::Tools::Registry.instance.add(:webfetch) { Hellm::Tools::WebFetchTool.new }
+      self.registry.add(:calculator) { Langchain::Tool::Calculator.new }
+      self.registry.add(:bravesearch) { Hellm::Tools::BraveSearchTool.new }
+      self.registry.add(:webfetch) { Hellm::Tools::WebFetchTool.new }
     end
 
-    def get_skills_from_project_dir
+    def build_skills_from_project_dir
       skills_dir = File.join(hellm_dir, "skills")
-      return unless Dir.exist?(skills_dir)
+      return [] unless Dir.exist?(skills_dir)
 
       Dir.glob(File.join(skills_dir, "**/SKILL.md")).map do |file|
         markdown_dir = File.dirname(file)
@@ -65,9 +70,9 @@ class Hellm::Builder
       end
     end
 
-    def get_agents_from_project_dir
+    def build_agents_from_project_dir(skill_tool)
       agents_dir = File.join(hellm_dir, "agents")
-      return unless Dir.exist?(agents_dir)
+      return [] unless Dir.exist?(agents_dir)
 
       Dir.glob(File.join(agents_dir, "*.md")).map do |file|
         markdown_file = Hellm::MarkdownFile.read(file)
@@ -82,8 +87,8 @@ class Hellm::Builder
           tools: tools,
           agents: markdown_file.fetch("agents", []),
           instructions: markdown_file.content.strip,
-          stream_adapter: stream_adapter,
-          openai_api_key: @openai_api_key
+          openai_api_key: @openai_api_key,
+          registry: self.registry
         )
       end
     end

data/lib/hellm/session.rb

@@ -0,0 +1,17 @@
+class Hellm::Session
+  def initialize(messages = [])
+    @messages = messages
+  end
+
+  def messages
+    @messages
+  end
+
+  def messages=(value)
+    @messages = value
+  end
+
+  def add_message(message)
+    @messages << message
+  end
+end

data/lib/hellm/tools/agent_tool_factory.rb

@@ -1,32 +1,31 @@
 module Hellm::Tools
   require "langchain"
 
+
   class AgentToolFactory
-    def self.create_sub_agent_tool(agent_name, agent)
-      klass = Class.new do
-        @@agent_name = agent_name
+    class AgentBase
+      extend Langchain::ToolDefinition
 
-        extend Langchain::ToolDefinition
+      def initialize(agent)
+        @agent = agent
+      end
 
-        def self.tool_name
-          @@agent_name
-        end
+      def run_agent(content: nil, image: nil)
+        @agent.new_session
+        @agent.add(content: content, image: image)
+        @agent.run
+        @agent.response
+      end
+    end
+
+    def self.create_sub_agent_tool(agent_name, agent)
+      klass = Class.new(AgentBase) do
+        define_singleton_method(:tool_name) { agent_name }
 
         define_function "run_agent", description: "Run the agent #{agent.name} and return its response.\n#{agent.description}" do
           property :content, type: "string", description: "Textual content to pass to the agent.", required: false
           property :image, type: "string", description: "Image URL or path to pass to the agent.", required: false
         end
-
-        def initialize(agent)
-          @agent = agent
-        end
-
-        def run_agent(content: nil, image: nil)
-          @agent.new_session
-          @agent.add(content: content, image: image)
-          @agent.run
-          @agent.response
-        end
       end
       klass.new(agent)
     end

data/lib/hellm/tools/registry.rb

@@ -3,20 +3,18 @@ require_relative "agent_tool_factory"
 module Hellm::Tools
   class Registry
     ALIASES = {
-      "default" => ["skill"],
+      "default" => ["skill", "calculator"],
       "web" => ["webfetch", "bravesearch"],
       "websearch" => ["bravesearch"],
       "agent" => [] # agent tools are dynamically generated from registered agents
     }
 
-
-    def self.instance
-      @instance ||= new
-    end
-
     def initialize
       @tools = {}
-      @agent_tools = {}
+    end
+
+    def available_tools
+      @tools.keys
     end
 
     def add(tool_name, instance=nil, &factory)

data/lib/hellm/tools/skill_tool.rb

@@ -4,6 +4,12 @@ module Hellm::Tools
   class SkillTool
     extend Langchain::ToolDefinition
 
+    attr_reader :skills
+
+    def initialize
+      @skills = []
+    end
+
     def add(*skills)
       skills.each do |skill|
         add_skill(skill)
@@ -12,6 +18,7 @@ module Hellm::Tools
 
     private
       def add_skill(skill)
+        @skills << skill
         skill_name = skill.name.gsub(/[\s-]+/, "_").downcase
         method_name = "get_skill_#{skill_name}"
         self.class.class_eval(

data/lib/hellm.rb

@@ -1,11 +1,10 @@
 # frozen_string_literal: true
 
 require_relative "hellm/version"
-require_relative "hellm/builder"
+require_relative "hellm/project"
 
 module Hellm
   class Error < StandardError; end
-  # Your code goes here...
 
   def self.openai_api_key=(key)
     @api_key = key  if !key.nil? && !key.empty?
@@ -15,10 +14,9 @@ module Hellm
     @api_key ||= ENV["OPENAI_API_KEY"]
   end
 
-  def self.build_agent(agent_name, project_dir, stream_adapter: nil, openai_api_key: nil)
+  def self.open_project(project_dir, openai_api_key: nil)
     self.openai_api_key = openai_api_key
-    builder = Hellm::Builder.new(project_dir: project_dir, stream_adapter: stream_adapter, openai_api_key: openai_api_key)
-    builder.build(talking_to: agent_name)
+    Hellm::Project.new(project_dir: project_dir, openai_api_key: openai_api_key)
   end
 
   def self.logger=(logger)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hellm
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors:
 - ubity UG
@@ -123,10 +123,10 @@ files:
 - lib/brave/search_api/client.rb
 - lib/hellm.rb
 - lib/hellm/agent.rb
-- lib/hellm/builder.rb
 - lib/hellm/markdown_file.rb
+- lib/hellm/project.rb
+- lib/hellm/session.rb
 - lib/hellm/skill.rb
-- lib/hellm/stream_adapter.rb
 - lib/hellm/tools/agent_tool_factory.rb
 - lib/hellm/tools/brave_search_tool.rb
 - lib/hellm/tools/registry.rb

data/lib/hellm/stream_adapter.rb

@@ -1,7 +0,0 @@
-class Hellm::StreamAdapter
-  def message(message)
-  end
-
-  def tool_call(call_id, name, method, args)
-  end
-end