hellm 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 75af48a7436c71030b39ada0b3acd8a74919c187816d3685715801f70bce314b
+  data.tar.gz: 11110f4770b2b25fb4ac92a46aff9d20b1c41a26abdf0d5e0790e7e0a698be9d
+SHA512:
+  metadata.gz: 958c4ccb58b11db9e67168e7cd4e1a667be90ddcc921a7585a3f40a50c0a83d36c3def47b79fa4988e61f0ec39749edf9efc7d8421f2e70b9909f97d79d9d972
+  data.tar.gz: ad4474e9e0a64c4c9ff2c4687e3bf0c58ed40eaaf3078e42e8443ec8f62f8b6654625e4004218d0856e3c100a90e9d6ceafb791d3ba9de50255f850ca149bffb

data/.github/agents/developer.md

@@ -0,0 +1,38 @@
+---
+name: developer
+description: "Development agent for Hellm. Use for ruby and rspec changes."
+tools: [read, search, edit, execute, todo]
+user-invocable: true
+---
+
+You are a Ruby development agent.
+
+## First Context To Load
+
+Before proposing or editing code, read:
+
+1. `ARCHITECTURE.md`
+
+## Project-Specific Constraints
+
+- Language throughout code and documentation is English.
+- Keep domain logic inside existing namespaces (`Hellm`, `Hellm::Tools`) unless a new boundary is clearly justified.
+
+## Preferred Approach
+
+1. Identify impacted module and classes.
+2. Implement smallest coherent change, preserving existing APIs unless change request demands otherwise.
+3. Add or update tests to cover new behavior and prevent regressions.
+4. Summarize architecture impact in the final response, including code coverage report and any risks or missing tests.
+5. Update `ARCHITECTURE.md` if the change introduces new patterns or behaviors.
+
+## Skill Selection
+
+- Use the `ruby` skill for language-level style, refactors, and Ruby object patterns.
+- Use the `test` skill for writing and debugging specs with RSpec.
+
+## Output Requirements
+
+- Explain what changed and why it matches existing project patterns.
+- Call out risks, regressions, or missing tests when relevant.
+- Keep recommendations grounded in `ARCHITECTURE.md` and current code behavior.

data/.github/skills/ruby/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: ruby
+description: "Ruby implementation skill. Use for idiomatic Ruby code changes."
+argument-hint: "Describe the Ruby behavior to implement or refactor, including affected modules or classes."
+user-invocable: true
+---
+
+# Ruby Skill For Arealsans
+
+Use this skill when the task is mostly Ruby-level logic.
+
+## Load Context First
+
+1. Read `ARCHITECTURE.md`.
+2. Read the concrete module or class files touched by the request.
+
+## Repository Ruby Conventions
+
+- Prefer namespace-scoped classes/modules (`Hellm::...`, `Hellm::Tools::...`).
+- Avoid introducing unrelated abstractions when a focused method-level change is sufficient.
+- Private methods are only refactored if it improves clarity or reduces duplication.
+
+## Procedure
+
+1. Implement the minimum Ruby change that satisfies the request.
+2. Keep method names and signatures consistent unless the change requires API updates.
+
+## Quality Checklist
+
+- Public method output remains compatible with current callers.

data/.github/skills/test/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: test
+description: "Testing skill. Use for writing and debugging specs with RSpec."
+argument-hint: "Describe what behavior should be tested, including context and expected outcomes."
+user-invocable: true
+---
+
+# Testing Skill For Arealsans
+
+Use this skill when implementing or fixing automated tests in this project.
+
+## Test Stack
+
+- RSpec
+
+## Mandatory Context
+
+1. Read `ARCHITECTURE.md` first.
+2. Read existing nearby specs to mirror conventions before adding new ones.
+
+## When To Use
+
+- Add coverage for new behavior
+- Reproduce and prevent regressions
+
+## Procedure
+
+1. Identify the thinnest test that proves behavior.
+2. Run focused specs first, then a wider relevant subset.
+
+## Repository Guardrails
+
+- Prefer clear setup helpers (before/after) over deeply nested let chains.
+- Validate both success and failure paths.
+
+
+## Suggested Commands
+
+- `bundle exec rspec spec/..._spec.rb`
+- `bundle exec rspec --profile 10`
+
+## Code Coverage (SimpleCov)
+
+- Use SimpleCov for all RSpec runs and keep project-wide minimum coverage at 80%.
+- If coverage drops below 80%, tests should fail and coverage must be restored before merge.
+- Prefer meaningful behavioral tests over coverage-only assertions.
+- Output of SimpleCov should be reviewed to identify untested code paths and guide new test additions.
+- SimpleCov should be configured to exclude irrelevant files and focus on application code.
+- Output of SimpleCov should be written to directory `log/coverage` and include HTML reports for local review.
+
+
+Example baseline configuration (typically in `spec/spec_helper.rb`):
+
+```ruby
+require "simplecov"
+
+SimpleCov.start "hellm" do
+	minimum_coverage 80
+end
+```
+
+## Done Criteria
+
+- New behavior is covered at the right layer.
+- Regression path has a failing-to-passing spec story.
+- SimpleCov project coverage is at least 80%.
+- Specs are readable, deterministic, and avoid timing flakiness.

data/ARCHITECTURE.md

@@ -0,0 +1,183 @@
+# Hellm Architecture Overview
+
+## Purpose
+
+Hellm is a Ruby gem that builds and runs Langchain-based AI agents from project-local markdown configuration.
+
+The framework focuses on:
+- Declarative agent setup in markdown files
+- Runtime composition of tools and sub-agent calls
+- Skill injection from markdown documents
+- A thin CLI wrapper for local execution
+
+## High-Level Structure
+
+Main source folders:
+- lib/hellm.rb: Public entrypoints and global configuration
+- lib/hellm/: Core runtime classes
+- lib/hellm/tools/: Tool registry and dynamic tool builders
+- bin/hellm: Command-line runner
+- example/: Sample .hellm project with agents and skills
+
+## Runtime Flow
+
+```mermaid
+flowchart TD
+  A[CLI: bin/hellm] --> B[Hellm.build_agent]
+  B --> C[Hellm::Builder]
+  C --> D[Load agents from .hellm/agents]
+  C --> E[Load skills from .hellm/skills/**/SKILL.md]
+  C --> F[Register builtin tools in Registry]
+  C --> G[Register skill tool in Registry]
+  C --> H[Register sub-agent tools in Registry]
+  H --> I[Hellm::Agent selected by name]
+  I --> J[agent.add content/image]
+  J --> K[Langchain::Assistant.run!]
+  K --> L[Tool calls via Registry instances]
+  K --> M[Response returned by agent.response]
+```
+
+## Core Components
+
+### Hellm module
+
+Location: lib/hellm.rb
+
+Responsibilities:
+- Stores global API key fallback from OPENAI_API_KEY
+- Builds an agent through Hellm::Builder
+- 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
+
+Location: lib/hellm/builder.rb
+
+Responsibilities:
+- Resolves configuration root (.hellm preferred, .github fallback)
+- Loads agent definitions from markdown files under agents/
+- Loads skill definitions from skills/**/SKILL.md
+- Registers tools in Hellm::Tools::Registry
+- Returns the selected runnable Hellm::Agent
+
+Behavior details:
+- Raises ArgumentError if no .hellm or .github directory exists.
+- Always appends the skill tool to each configured agent.
+- Registers built-in calculator tool by default.
+
+### Hellm::Agent
+
+Location: lib/hellm/agent.rb
+
+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:
+- Default model is gpt-5-nano.
+- Removes literal agent tool token from tools list and relies on explicit sub-agent wiring.
+- Supports image input as URL, data URL, or local file path converted to base64 data URL.
+
+### Hellm::MarkdownFile
+
+Location: lib/hellm/markdown_file.rb
+
+Responsibilities:
+- Reads markdown files with YAML frontmatter
+- Splits frontmatter and content
+- Exposes typed fetch access for attributes
+
+### Hellm::Skill
+
+Location: lib/hellm/skill.rb
+
+Responsibilities:
+- Value object representing skill metadata and markdown content
+
+### Hellm::StreamAdapter
+
+Location: lib/hellm/stream_adapter.rb
+
+Responsibilities:
+- Callback interface for streamed assistant messages and tool calls
+- Base implementation is intentionally empty and intended for customization
+
+## Tooling Architecture
+
+### Hellm::Tools::Registry
+
+Location: lib/hellm/tools/registry.rb
+
+Responsibilities:
+- Singleton registry for named tools
+- Supports factory or fixed-instance registration
+- Lazy-instantiates tools from factories and reuses instances
+- 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
+
+Location: lib/hellm/tools/skill_tool.rb
+
+Responsibilities:
+- Dynamically defines tool functions for each loaded skill
+- Returns raw skill content when called by the LLM
+
+### Hellm::Tools::AgentToolFactory
+
+Location: lib/hellm/tools/agent_tool_factory.rb
+
+Responsibilities:
+- Builds dynamic Langchain tools that proxy calls into sub-agents
+- Starts a fresh sub-agent session per invocation
+
+## Configuration Model
+
+Project configuration is stored in a `.hellm` directory with the following structure:
+
+```text
+.hellm/
+|-- agents/
+|   `-- *.md
+|       |-- frontmatter: model, name, description, tools, agents
+|       `-- body: agent instructions
+`-- skills/
+  `-- **/
+    `-- SKILL.md
+      |-- frontmatter: name, description, argument-hint
+      `-- body: skill text returned by the generated skill tool
+```
+
+## Extension Points
+
+Supported extension seams:
+- Register additional tools via Hellm::Tools::Registry.instance.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
+
+## Known Risks And Gaps
+
+Current technical risks:
+- Registry is process-global singleton with shared tool instances; stateful tools can leak behavior across sessions.
+- Minimal validation of markdown frontmatter means malformed config errors may surface late.
+
+Testing status:
+- RSpec covers core behavior for Builder, Registry, tools, and LLM-free Agent logic.
+- SimpleCov runs with the suite and writes coverage output to log/coverage.
+
+## Future Hardening Priorities
+
+Recommended next steps:
+- Add integration specs for builder loading, tool registration, and agent execution wiring.
+- Add contract tests for markdown schema validation and clearer error messages.
+- Add concurrency and isolation tests around Registry behavior.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 couchbelag
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,88 @@
+# Hellm
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add hellm
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install hellm
+```
+
+## Usage
+
+Create a project-local `.hellm` directory with agent and skill definitions.
+
+Minimal structure (as used in `example/`):
+
+```text
+.hellm/
+	agents/
+		alfred.agent.md
+		mathematician.agent.md
+	skills/
+		farben/
+			SKILL.md
+```
+
+Set your OpenAI API key in an environment variable named `OPENAI_API_KEY` or put this variable in a `.env` file in the working directory:
+
+```bash
+OPENAI_API_KEY=your_api_key_here
+```
+
+Run an agent by passing the agent name and prompt:
+
+```bash
+hellm Alfred "Tell me your favorite color and which month fits it."
+```
+
+
+### Builtin Tools
+
+The framework provides the following tools for agents to use:
+
+* `calculator` - a simple calculator for basic arithmetic operations.
+
+
+### Custom Tools
+
+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
+  Langchain::Tool::Calculator.new
+end
+```
+
+The code shows how to get access to the registry and add a custom tool with a unique name. The block is used as factory method to create a new instance of the tool when needed. Instances are created once only and reused for all agents, so do not store any state in the tool instance.
+
+
+### Example
+
+The example in this repository provides a convenience script which runs the example with one call, showcasing the flow of actions taken by the agents:
+
+```bash
+cd example
+./example.sh
+```
+
+
+## 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](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/hellm.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec
+
+desc "returns current version number as defined in lib/hellm/version.rb"
+task :version do
+  puts Hellm::VERSION
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/example/.hellm/agents/alfred.agent.md

@@ -0,0 +1,8 @@
+---
+name: Alfred
+description: "General purpose agent."
+tools: [agent]
+agents: [Mathematician]
+---
+
+You are Alfred, a helpful general purpose agent that ends every response's last sentence with ", Sir.". If you have a mathematical task, try to solve the problem by asking the Mathematician agent for help.

data/example/.hellm/agents/mathematician.agent.md

@@ -0,0 +1,8 @@
+---
+name: Mathematician
+description: "Agent for calculating mathematical expressions."
+argument-hint: "Provide a mathematical expression to calculate."
+tools: [calculator]
+---
+
+You are Mathematician, a helpful agent that calculates mathematical expressions accurately with the calculator tool.

data/example/.hellm/skills/farben/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: farben
+description: "A skill for mapping colors to month"
+argument-hint: "Describe your color and why you like it."
+---
+
+Map colors to months:
+
+* red: january
+* orange: february
+* yellow: march
+* green: april
+* blue: may
+* purple: june
+* pink: july
+* white: august
+* black: september
+* brown: october
+* gray: november
+* rainbow: december

data/example/example.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/bash
+
+../bin/hellm Alfred sag mir deine lieblingsfarbe und welcher monat dazu passt und berechne die anzahl monate von einschließlich diesem monat bis einschließlich dezember. Errechne mir die Fläche eines Kreises mit dieser Zahl als Radius.

data/lib/hellm/agent.rb

@@ -0,0 +1,142 @@
+require_relative "stream_adapter"
+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
+
+  # instructions (string) for the agent.
+  attr_accessor :instructions
+
+  # array of tools (Langchain::Tool) for the agent to use
+  #
+  # langchain.rb Built-in Tools:
+  #     - Langchain::Tool::Calculator: Useful for evaluating math expressions. Requires gem "eqn".
+  #     - Langchain::Tool::Database: Connect your SQL database. Requires gem "sequel".
+  #     - Langchain::Tool::FileSystem: Interact with the file system (read & write).
+  #     - Langchain::Tool::GoogleSearch: Wrapper around SerpApi's Google Search API. Requires gem "google_search_results".
+  #     - Langchain::Tool::NewsRetriever: A wrapper around NewsApi.org to fetch news articles.
+  #     - Langchain::Tool::RubyCodeInterpreter: Useful for evaluating generated Ruby code. Requires gem "safe_ruby" (In need of a better solution).
+  #     - Langchain::Tool::Tavily: A wrapper around Tavily AI.
+  #     - Langchain::Tool::Vectorsearch: A wrapper for vector search classes.
+  #     - Langchain::Tool::Weather: Calls Open Weather API to retrieve the current weather.
+  #     - Langchain::Tool::Wikipedia: Calls Wikipedia API. Requires gem "wikipedia-client".
+  #
+  attr_accessor :tools
+
+  def initialize(model: nil, name: nil, description: nil, stream_adapter: nil, openai_api_key: nil, agents: nil, tools: nil, instructions: nil)
+    model ||= "gpt-5-nano"
+    Hellm.logger.debug("Initializing agent #{name} (#{model})")
+    @llm = Langchain::LLM::OpenAI.new(
+      api_key: openai_api_key || ::Hellm.openai_api_key,
+      default_options: {chat_model: model}
+    )
+    self.name = name || self.class.name
+    self.description = description || ""
+    self.instructions = instructions || ""
+    self.stream_adapter = stream_adapter || Hellm::StreamAdapter.new
+    self.agents = agents || []
+    self.tools = tools || []
+    # remove "agent" from tools, this ability is controlled by the presence of agents
+    self.tools.reject!{|t| t == "agent"}
+  end
+
+
+  def add(content: nil, image: nil)
+    return if content.nil? && image.nil?
+    options = {}
+    options[:content] = content if !content.nil? && !content.empty?
+    options[:image_url] = normalize_image_input(image) if !image.nil? && !image.empty?
+    assistant.add_message(**options)
+  end
+
+  def run
+    with_rate_limit do
+      assistant.run!
+    end
+  end
+
+  def response
+    assistant_message = assistant.messages.reverse.find(&:llm?)
+    assistant_message&.content.to_s.strip
+  end
+
+  def new_session
+    @assistant = nil
+  end
+
+  protected
+    def assistant
+      if @assistant.nil?
+        tool_instances = [
+          *Hellm::Tools::Registry.instance.get(*tools),
+          *Hellm::Tools::Registry.instance.get_agent_tools(*agents)
+        ]
+        @assistant = Langchain::Assistant.new(
+          llm: llm,
+          tools: tool_instances,
+          instructions: instructions
+        )
+        @assistant.add_message_callback = ->(message) {
+          Hellm.logger.debug("[Agent #{name} message] #{message.inspect}")
+          self.stream_adapter.message(message)
+        }
+        @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/")
+
+      path = File.expand_path(image_input)
+      raise ArgumentError, "Image file not found: #{image_input}" unless File.exist?(path)
+
+      ext = File.extname(path).downcase
+      mime_type = case ext
+      when ".jpg", ".jpeg" then "image/jpeg"
+      when ".png" then "image/png"
+      when ".webp" then "image/webp"
+      when ".gif" then "image/gif"
+      else "application/octet-stream"
+      end
+
+      encoded = Base64.strict_encode64(File.binread(path))
+      "data:#{mime_type};base64,#{encoded}"
+    end
+
+    def rate_limited?(error)
+      message = error.message.downcase
+      message.include?("429") ||
+        message.include?("rate limit") ||
+        message.include?("rate_limit_exceeded")
+    end
+
+    def with_rate_limit
+      attempts = 0
+      begin
+        attempts += 1
+        yield
+      rescue StandardError => e
+        raise unless rate_limited?(e) && attempts < MAX_RETRIES
+        # Small exponential backoff for transient 429 errors.
+        sleep(0.25 * (2**(attempts - 1)))
+        retry
+      end
+    end
+end

data/lib/hellm/builder.rb

@@ -0,0 +1,86 @@
+require_relative "agent"
+require_relative "skill"
+require_relative "stream_adapter"
+require_relative "tools/skill_tool"
+require_relative "markdown_file"
+
+class Hellm::Builder
+  attr_accessor :project_dir, :hellm_dir, :stream_adapter
+
+  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)
+
+    @stream_adapter = stream_adapter
+    @openai_api_key = openai_api_key
+
+    add_builtin_tools_to_registry
+  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?
+      agent = Hellm::Agent.new
+    else
+      agent = agents.find{ |agent| agent.name == talking_to }
+      raise ArgumentError, "Agent not found: #{talking_to}" if agent.nil?
+    end
+    agent
+  end
+
+  private
+    def add_builtin_tools_to_registry
+      Hellm::Tools::Registry.instance.add(:calculator) { Langchain::Tool::Calculator.new }
+    end
+
+    def get_skills_from_project_dir
+      skills_dir = File.join(hellm_dir, "skills")
+      return unless Dir.exist?(skills_dir)
+
+      Dir.glob(File.join(skills_dir, "**/SKILL.md")).map do |file|
+        markdown_dir = File.dirname(file)
+        markdown_file = Hellm::MarkdownFile.read(file)
+        Hellm::Skill.new(
+          dir: markdown_dir,
+          name: markdown_file.fetch("name"),
+          description: markdown_file.fetch("description"),
+          argument_hint: markdown_file.fetch("argument-hint"),
+          content: markdown_file.content,
+        )
+      end
+    end
+
+    def get_agents_from_project_dir
+      agents_dir = File.join(hellm_dir, "agents")
+      return unless Dir.exist?(agents_dir)
+
+      Dir.glob(File.join(agents_dir, "*.md")).map do |file|
+        markdown_file = Hellm::MarkdownFile.read(file)
+
+        tools = markdown_file.fetch("tools", [])
+        tools << "skill"
+
+        Hellm::Agent.new(
+          model: markdown_file.fetch("model"),
+          name: markdown_file.fetch("name"),
+          description: markdown_file.fetch("description"),
+          tools: tools,
+          agents: markdown_file.fetch("agents", []),
+          instructions: markdown_file.content.strip,
+          stream_adapter: stream_adapter,
+          openai_api_key: @openai_api_key
+        )
+      end
+    end
+end

data/lib/hellm/markdown_file.rb

@@ -0,0 +1,53 @@
+require "yaml"
+
+class Hellm::MarkdownFile
+  attr_accessor :path, :attributes, :content
+
+  def self.read(path)
+    file = new(path)
+    file.read
+    file
+  end
+
+  def fetch(key, default=nil)
+    attributes.fetch(key.to_s, default)
+  end
+
+  def read
+    file = File.read(path)
+    frontmatter, content = separate_frontmatter_and_content(file)
+    self.attributes = YAML.load(frontmatter) if frontmatter != ""
+    self.attributes ||= {}
+    self.content = content
+    self
+  end
+
+
+  protected
+    def initialize(path)
+      @path = path
+      @attributes = {}
+      @content = ""
+    end
+
+    def separate_frontmatter_and_content(file)
+      within_frontmatter = false
+      content = ""
+      frontmatter = ""
+
+      file.lines.each do |line|
+        if line.strip == "---"
+          within_frontmatter = !within_frontmatter
+          next
+        end
+
+        if within_frontmatter
+          frontmatter << line
+        else
+          content << line
+        end
+      end
+
+      [frontmatter, content]
+    end
+end

data/lib/hellm/skill.rb

@@ -0,0 +1,11 @@
+class Hellm::Skill
+  attr_accessor :dir, :name, :description, :argument_hint, :content
+
+  def initialize(dir:, name:, description:, argument_hint: nil, content: nil)
+    @dir = dir
+    @name = name
+    @description = description
+    @argument_hint = argument_hint
+    @content = content
+  end
+end

data/lib/hellm/stream_adapter.rb

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

data/lib/hellm/tools/agent_tool_factory.rb

@@ -0,0 +1,34 @@
+module Hellm::Tools
+  require "langchain"
+
+  class AgentToolFactory
+    def self.create_sub_agent_tool(agent_name, agent)
+      klass = Class.new do
+        @@agent_name = agent_name
+
+        extend Langchain::ToolDefinition
+
+        def self.tool_name
+          @@agent_name
+        end
+
+        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
+  end
+end

data/lib/hellm/tools/registry.rb

@@ -0,0 +1,53 @@
+require_relative "agent_tool_factory"
+
+module Hellm::Tools
+  class Registry
+    def self.instance
+      @instance ||= new
+    end
+
+    def initialize
+      @tools = {}
+      @agent_tools = {}
+    end
+
+    def add(tool_name, instance=nil, &factory)
+      @tools[tool_name.to_s] = {
+        factory: factory,
+        instance: instance
+      }
+    end
+
+    def get(*tool_names)
+      tools = tool_names.map do |tool_name|
+        entry = @tools[tool_name.to_s]
+        if entry.nil?
+          raise ArgumentError, "Tool not found: #{tool_name}"
+        end
+        entry[:instance] ||= entry[:factory].call
+        entry[:instance]
+      end
+      tools.compact
+    end
+
+    def add_agents(*agents)
+      agents.each do |agent|
+        tool_name = agent_tool_name(agent.name)
+        tool = Hellm::Tools::AgentToolFactory.create_sub_agent_tool(tool_name, agent)
+        add(tool_name, tool)
+      end
+    end
+
+    def get_agent_tools(*agent_names)
+      tool_names = agent_names.map do |name|
+        agent_tool_name(name)
+      end
+      get(*tool_names)
+    end
+
+    private
+      def agent_tool_name(agent_name)
+        "agent_tool_" + agent_name.gsub(/[\s-]+/, "_").downcase
+      end
+  end
+end

data/lib/hellm/tools/skill_tool.rb

@@ -0,0 +1,29 @@
+module Hellm::Tools
+  require "langchain"
+
+  class SkillTool
+    extend Langchain::ToolDefinition
+
+    def add(*skills)
+      skills.each do |skill|
+        add_skill(skill)
+      end
+    end
+
+    private
+      def add_skill(skill)
+        skill_name = skill.name.gsub(/[\s-]+/, "_").downcase
+        method_name = "get_skill_#{skill_name}"
+        self.class.class_eval(
+          <<~EOSKILL
+            define_function "#{method_name}", description: "SkillTool: Read skill #{skill.name}.\n#{skill.description}\n#{skill.argument_hint}\n\n"
+            def #{method_name}
+              <<~EOCONTENT
+                #{skill.content}
+              EOCONTENT
+            end
+          EOSKILL
+        )
+      end
+  end
+end

data/lib/hellm/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Hellm
+  VERSION = File.read(File.join(__dir__, "..", "..", "VERSION")).strip
+end

data/lib/hellm.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "hellm/version"
+require_relative "hellm/builder"
+
+module Hellm
+  class Error < StandardError; end
+  # Your code goes here...
+
+  def self.openai_api_key=(key)
+    @api_key = key  if !key.nil? && !key.empty?
+  end
+
+  def self.openai_api_key
+    @api_key ||= ENV["OPENAI_API_KEY"]
+  end
+
+  def self.build_agent(agent_name, project_dir, stream_adapter: nil, 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)
+  end
+
+  def self.logger=(logger)
+    @logger = logger
+  end
+
+  def self.logger
+    @logger ||= Logger.new($stdout)
+  end
+
+  def self.set_log_level(level, langchain_level: Logger::ERROR)
+    self.logger.level = level
+    Langchain.logger.level = langchain_level
+  end
+end
+
+# default log level
+Hellm.set_log_level(Logger::DEBUG)

data/sig/hellm.rbs

@@ -0,0 +1,4 @@
+module Hellm
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,139 @@
+--- !ruby/object:Gem::Specification
+name: hellm
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- ubity UG
+- Tobi Schmid
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: langchainrb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.19.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.19.5
+- !ruby/object:Gem::Dependency
+  name: ruby-openai
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 8.3.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 8.3.0
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.0
+- !ruby/object:Gem::Dependency
+  name: eqn
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.6.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.6.5
+- !ruby/object:Gem::Dependency
+  name: google_search_results
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.2.0
+description: |
+  Agentic framework for LLMs, allowing you to build autonomous agents that can perform complex tasks and interact with the world.
+  Name is inspired by the English word "helm", which refers to the steering mechanism of a ship, symbolizing guidance and direction.
+  The name also evokes the idea of taking control and navigating through challenges, much like how an agentic framework empowers LLMs to make decisions and take actions autonomously.
+email:
+- info@ubity.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/agents/developer.md"
+- ".github/skills/ruby/SKILL.md"
+- ".github/skills/test/SKILL.md"
+- ARCHITECTURE.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- VERSION
+- example/.hellm/agents/alfred.agent.md
+- example/.hellm/agents/mathematician.agent.md
+- example/.hellm/skills/farben/SKILL.md
+- example/example.sh
+- lib/hellm.rb
+- lib/hellm/agent.rb
+- lib/hellm/builder.rb
+- lib/hellm/markdown_file.rb
+- lib/hellm/skill.rb
+- lib/hellm/stream_adapter.rb
+- lib/hellm/tools/agent_tool_factory.rb
+- lib/hellm/tools/registry.rb
+- lib/hellm/tools/skill_tool.rb
+- lib/hellm/version.rb
+- sig/hellm.rbs
+homepage: https://gitlab.com/ubity/gems/hellm
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://gitlab.com/ubity/gems/hellm
+  source_code_uri: https://gitlab.com/ubity/gems/hellm
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.1
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby agentic framework for LLMs
+test_files: []