llmed 0.6.0 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c47ebb44059bae3a1ffc2d27dd064098036ebd390cb677a488761845e13d4b6b
-  data.tar.gz: 1442dec8d3c594b8610af95d7edfbdbdee8881ac00a046001cc6fd4eb9c2e68c
+  metadata.gz: d9bc1517e8b12805cae255599e37f2f6cb17ee1aae43043c2d36e232291dc63f
+  data.tar.gz: 2d82a1d9ff3fc1585b8fe952800786cc25ee107f9a1cf679e1ada541c4b105df
 SHA512:
-  metadata.gz: 80a7c93eed1106305b848bae99b0fcce744c55bc933538465041e19329ed1e6fe01f398c38ec849f2ae4981ec260024d3a9ded96f1465224a0b9f60cc8924b53
-  data.tar.gz: 7c3df54bec3ee2e2f02bd7108c92004e6969bb8019ab5209bda32327cc916492ac2946948b2ce835325b93d33238292187870e68bc35bfa50feefb0b38164263
+  metadata.gz: 347c5b9e439ceedbb8de5a850185d1a4e3a8aec23564d9f379747abda2d5a5921047d2891563d9205077476f29910ffe511819d729b24ef1ee3a94002ad1fbe5
+  data.tar.gz: 2b5053b7389eee52215e44799737f74fdb9fc43acf02c2a1036b2f052a1bef339f13427c6bc92606a1b7fb7d31b80b44fa6e6b4c94f3284d16d5550dfc1e321a

data/README.md

@@ -17,6 +17,8 @@ In classic terms the LLM is the Compiler, Source Code is the Binary, the Program
 set_llm provider: :like_openai, api_key: ENV['TOGETHERAI_API_KEY'], model: 'Qwen/Qwen2.5-Coder-32B-Instruct', options: {uri_base: 'https://api.together.xyz/v1'}
 
 application "MINI COUNTER", release: nil, language: :node, output_file: "minicounter.ollmed" do
+  achieve('coding guidelines') { 'Add top comment with a technical summary of the implementation' }
+  
   # Most stable context: if this changes, all subsequent context will be recompiled.
   context "dependencies" do
     <<-LLM
@@ -66,12 +68,43 @@ add CORS endpoints.
 ```
 then compile using command `llmed.literate`.
 
+## HOWTO Programing using LLMED
+
+Programming with LLMED involves breaking down the problem into smaller contexts, where each context must be connected to the next, creating a chain of contexts that expresses the final solution (program/application/software). The final code will map each context to a block of code (module, function, or statements—this is determined by the LLM), so any changes to a context will be reflected in the source code. This is important to keep in mind. For example, it is not the same to write:
+
+```
+# Dependencies
+...
+# Application
+...
+```
+
+as
+
+```
+# Application
+...
+# Dependencies
+...
+```
+
+!!The LLM can do crazy things when trying to create working source code for that.
+
+At the top of the document, write the most stable concepts (the contexts that don't change frequently), going down to the most unstable (the contexts that are expected to change more frequently) concepts. The purpose of these two things:
+
+1. The map between context and code block.
+2. Rebuilding of contexts: LLMed assumes that there is a unique chain, so it will recompile from the changed context to the end of the chain.
+
+So, programming with LLMed means being aware of the technology (programming language, libraries, software architecture, tools, etc.). LLMed's job is to provide a free-form natural language programming compiler.
+
+
 ## Programming flow
 
-* Cycle
+1. Cycle
   * Edit application.
   * Once you agree with the current state of the application, increase the value of the `release` attribute
-* Commit the release file (.release) and the source code (.llmed).
+2. Commit the release file (.release) and the source code (.llmed) and the snapshot (.snapshot).
+3. Go to 1.
 
 # Usage
 

data/exe/llmed

@@ -1,23 +1,24 @@
 #!/bin/env ruby
 # Copyright 2025 Jovany Leandro G.C <bit4bit@riseup.net>
 # frozen_string_literal: true
+
 require 'optparse'
 require 'llmed'
 
 logger = Logger.new(STDERR)
 output_dir = './llmed-out'
 release_dir = output_dir
-template = <<-TMP
-set_llm provider: :openai, api_key: ENV['OPENAI_API_KEY'], model: 'gpt-4o'
-
-# Increment the RELEASE number once you approve the output.
-application "hi world", release: nil, language: '<HERE LANGUAGE>', output_file: "<HERE NAME>.ollmed" do
-  context "main" do
-    <<-LLM
-        Show to user 'hi world!'.
-    LLM
+template = <<~TMP
+  set_llm provider: :openai, api_key: ENV['OPENAI_API_KEY'], model: 'gpt-4o'
+
+  # Increment the RELEASE number once you approve the output.
+  application "hi world", release: nil, language: '<HERE LANGUAGE>', output_file: "<HERE NAME>.ollmed" do
+    context "main" do
+      <<-LLM
+          Show to user 'hi world!'.
+      LLM
+    end
   end
-end
 TMP
 
 OptionParser.new do |parser|

data/lib/llm.rb

@@ -18,18 +18,16 @@ class LLMed
 
     Response = Struct.new(:provider, :model, :source_code, :duration_seconds, :total_tokens, keyword_init: true)
 
-    class OpenAI
-
-      DEFAULT_URI_BASE = "https://api.openai.com/".freeze
-      MAX_TOKENS = 8192
-
-      def initialize(**args)
-        @logger = args.delete(:logger)
-        @llm = Langchain::LLM::OpenAI.new(**llm_arguments(args))
+    class Agent
+      def initialize(llm_instance)
+        @llm_instance = llm_instance
+        @assistant = Langchain::Assistant.new(
+          llm: @llm_instance.llm
+        )
       end
 
       def chat(messages: [])
-        messages = messages.map do |m|
+        llm_messages = messages.map do |m|
           case m
           when Message::System
             { role: 'system', content: m.content }
@@ -39,26 +37,40 @@ class LLMed
         end
 
         start = Time.now
-        llm_response = @llm.chat(messages: messages, max_tokens: MAX_TOKENS)
-        warn_token_limits(llm_response)
+
+        @assistant.add_messages(messages: llm_messages)
+        assistant_messages = @assistant.run!
+
+        assistant_response = assistant_messages.select { |m| m.role == 'assistant' }.last
 
         stop = Time.now
-        Response.new({ provider: provider,
-                       model: @llm.chat_parameters[:model],
+        Response.new({ provider: @llm_instance.provider,
+                       model: @llm_instance.model,
                        duration_seconds: stop.to_i - start.to_i,
-                       source_code: source_code(llm_response.chat_completion),
-                       total_tokens: llm_response.total_tokens })
+                       source_code: @llm_instance.source_code(assistant_response.content),
+                       total_tokens: @assistant.total_tokens })
       end
+    end
 
-      private
-      def warn_token_limits(llm_response)
-        if llm_response.completion_tokens >= MAX_TOKENS
-          @logger.warn("POSSIBLE INCONSISTENCY COMPLETED TOKENS REACHED MAX TOKENS #{MAX_TOKENS}")
-        end
+    class OpenAI
+      DEFAULT_URI_BASE = "https://api.openai.com/".freeze
+      MAX_TOKENS = 8192
+
+      attr_reader :llm
+
+      def initialize(**args)
+        @logger = args.delete(:logger)
+        @llm = Langchain::LLM::OpenAI.new(**llm_arguments(args))
       end
 
-      def llm_arguments(args)
-        args
+      def chat(messages: [])
+        llm_response = @llm.chat(messages: messages, max_tokens: MAX_TOKENS)
+        warn_token_limits(llm_response)
+        llm_response
+      end
+
+      def model
+        @llm.chat_parameters[:model]
       end
 
       def provider
@@ -68,31 +80,43 @@ class LLMed
       def source_code(content)
         content.gsub('```', '').sub(/^(node(js)?|javascript|ruby|python(\d*)|elixir|bash|html|go|c(pp)?)([ \n])/, '')
       end
-    end
 
-    class Anthropic < OpenAI
       private
 
+      def warn_token_limits(llm_response)
+        if llm_response.completion_tokens >= MAX_TOKENS
+          @logger.warn("POSSIBLE INCONSISTENCY COMPLETED TOKENS REACHED MAX TOKENS #{MAX_TOKENS}")
+        end
+      end
+
       def llm_arguments(args)
-        @logger = args.delete(:logger)
-        args.merge({ llm_options: { uri_base: 'https://api.anthropic.com/v1/' } })
+        args
       end
+    end
 
+    class Anthropic < OpenAI
       def provider
         :anthropic
       end
-    end
 
-    class LikeOpenAI < OpenAI
       private
 
       def llm_arguments(args)
-        args
+        @logger = args.delete(:logger)
+        args.merge({ llm_options: { uri_base: 'https://api.anthropic.com/v1/' } })
       end
+    end
 
+    class LikeOpenAI < OpenAI
       def provider
         :like_openai
       end
+
+      private
+
+      def llm_arguments(args)
+        args
+      end
     end
 
     class Test
@@ -100,14 +124,25 @@ class LLMed
         @output = ''
       end
 
+      def chat_parameters
+        { model: 'test' }
+      end
+
+      def model
+        'test'
+      end
+
       def chat(messages: [])
-        @output = messages.map { |m| m[:content] }.join("\n")
+        output = messages.map { |m| m[:content] }.join("\n")
+        Struct.new(:chat_completion, :total_tokens).new(output, 0)
+      end
+
+      def source_code(code)
+        code
+      end
 
-        Response.new({ provider: :test,
-                       model: 'test',
-                       duration_seconds: 0,
-                       source_code: @output,
-                       total_tokens: 0 })
+      def provider
+        :test
       end
     end
   end

data/lib/llmed/application.rb

@@ -39,6 +39,7 @@ class LLMed
       @code_comment = CodeComment.new(language)
       @block = block
       @contexts = []
+      @goals = []
       @logger = logger
       @release = release
       @release_dir = release_dir
@@ -48,6 +49,7 @@ class LLMed
 
     # Example:
     # application { context "demo" { "content" } }
+    # DEPRECATED: Use spec instead of context
     def context(name, **opts, &block)
       opts[:release_dir] = @release_dir
       ctx = Context.new(name: name, options: opts)
@@ -57,6 +59,21 @@ class LLMed
       @contexts << ctx
     end
 
+    # Example:
+    # application { spec "demo" { "content" } }
+    def spec(name, **opts, &block)
+      context(name, **opts, &block)
+    end
+
+    def achieve(name, **opts, &block)
+      opts[:release_dir] = @release_dir
+      goal = Goal.new(name: name, options: opts)
+      output = goal.instance_eval(&block)
+      goal.llm(output) unless goal.message?
+
+      @goals << goal
+    end
+
     def evaluate
       instance_eval(&@block)
     end
@@ -75,7 +92,7 @@ class LLMed
       end
 
       def refresh(contexts)
-        @contexts = contexts.map{ |ctx| [ctx.name, {'name' => ctx.name, 'message' => ctx.raw}]}.to_h
+        @contexts = contexts.map { |ctx| [ctx.name, { 'name' => ctx.name, 'message' => ctx.raw }] }.to_h
         dump
       end
 
@@ -83,9 +100,12 @@ class LLMed
         diffs = {}
         other_contexts.each do |other_ctx|
           current_ctx = @contexts[other_ctx.name]
-          result = line_diff(current_ctx['message'], other_ctx.raw)
-          # omit not changes
-          if !result.all?{|op, line| op == '=:'}
+          result = if current_ctx.nil?
+                     other_ctx.raw.split("\n").map { |line| ["+:", line] }
+                   else
+                     line_diff(current_ctx['message'], other_ctx.raw)
+                   end
+          if !result.all? { |op, line| op == '=:' }
             diffs[other_ctx.name] = result
           end
         end
@@ -120,8 +140,8 @@ class LLMed
             i2 += 1
           else
             # Try to find if one of the lines matches later
-            idx1 = lines1[i1+1..-1]&.index(line2)
-            idx2 = lines2[i2+1..-1]&.index(line1)
+            idx1 = lines1[i1 + 1..-1]&.index(line2)
+            idx2 = lines2[i2 + 1..-1]&.index(line1)
 
             if !idx1.nil? && (idx2.nil? || idx1 <= idx2)
               result << ["-:", line1]
@@ -148,20 +168,18 @@ class LLMed
             @contexts = JSON.load(f.read)['contexts']
           end
         else
-          @contexts = default.map{ |ctx| [ctx.name, {'name' => ctx.name, 'message' => ctx.raw}]}.to_h
+          @contexts = default.map { |ctx| [ctx.name, { 'name' => ctx.name, 'message' => ctx.raw }] }.to_h
         end
       end
 
       def dump
         File.open(@snapshot_file, 'w') do |file|
-          file.write(JSON.dump({'contexts' => @contexts}))
+          file.write(JSON.dump({ 'contexts' => @contexts }))
         end
       end
     end
 
     def prepare_snapshot
-      raise "snapshot preparation require contexts" if @contexts.empty?
-
       @logger.info("APPLICATION #{@name} PREPARING SNAPSHOT #{@snapshot.snapshot_file}")
 
       @snapshot.sync(@contexts)
@@ -233,6 +251,8 @@ class LLMed
         @logger.info("APPLICATION #{@name} SNAPSHOT REFRESHED")
       end
 
+      return unless @output_file.is_a?(String)
+
       output_file = Pathname.new(@output_dir) + @output_file
       FileUtils.cp(output_file, release_source_code)
       FileUtils.cp(output_file, release_main_source_code)
@@ -254,7 +274,8 @@ class LLMed
                            code_comment_begin: @code_comment.begin,
                            code_comment_end: @code_comment.end,
                            update_context_digests: digests_of_context_to_update,
-                           changes_of_contexts: changes_of_contexts)
+                           changes_of_contexts: changes_of_contexts,
+                           goals: goals)
     end
 
     def rebuild?
@@ -299,6 +320,10 @@ class LLMed
 
     private
 
+    def goals
+      @goals.map(&:message).join("\n")
+    end
+
     def digests_of_context_to_update
       update_context_digest = []
 

data/lib/llmed/configuration.rb

@@ -27,10 +27,17 @@ class LLMed
         Behavioral rules (must be obeyed):
         1. No comments-only outputs. If your natural answer would be comments, instead implement executable code that performs the described behavior. Do not output explanatory text outside code blocks — output only source code for the indicated contexts.
         2. All functions/methods must have bodies implementing the intended behavior. If external information is missing, implement a reasonable, deterministic default rather than leaving a stub.
-        3. Fail-fast fallback: if the requested context genuinely cannot be implemented, include a clear runtime failure function implementation_impossible() that raises/prints a single machine-readable error (e.g. throws an exception with message IMPLEMENTATION-IMPOSSIBLE) and still compiles.
+        3. Fail-fast fallback: if the requested context genuinely cannot be implemented, include a clear runtime failure function implementation_impossible() that raises/prints a single machine-readable error (e.g. throws an exception with message IMPLEMENTATION-IMPOSSIBLE) also a technical description with the reasons and still compiles.
         4. One-to-one mapping: produce exactly one code block per digest requested. Do not add unrelated helper contexts unless they are wrapped and linked to an indicated digest; if helpers are necessary, include them inside the same context wrapper.
         5. Include the literal LLMED-COMPILED comment somewhere inside the code.
         6. Do not output any text outside the source code. The assistant response must be only source code for the requested context(s).
+        7. Absolute goal precedence: Before generating code, always merge the goals with the context. If any context conflicts with a goal, the goal must override the context's intended purpose, not its implementation details.
+        8. All user-facing strings, messages, and output must comply with the goals. This overrides literal instructions in context descriptions if there is a conflict.
+        9. Step-by-step plan to follow:
+          a. Read goals and extract all global rules (e.g., language, style, behavior).
+          b. Read the context descriptions.
+          c. Merge context with the goal; if there is any conflict, modify the context output to satisfy the goal.
+          d. Generate code fully complying with both the merged specification and the required context wrapper format.
 
         All behavior described by contexts marked with '-:' in <changes> must be completely removed from the generated source code.
         Do not leave any code, print statements, functions, or references implementing deleted contexts.
@@ -40,17 +47,28 @@ class LLMed
         {changes_of_contexts}
         </changes>
 
+
+        <goals>
+        {goals}
+        <goals>
+
+        Goals and context are orthogonal: goals orient the context.
+
+        Plan: Before writing any code, ensure you fully integrate both the overarching specifications (goal sections) and the context-level descriptions during code generation.
+
         Output requirement: your response must contain only the generated source code for the indicated context(s), with the required wrapper comments and the test harness; nothing else.
-", input_variables: %w[language source_code code_comment_begin code_comment_end update_context_digests changes_of_contexts])
+", input_variables: %w[language source_code code_comment_begin code_comment_end update_context_digests changes_of_contexts goals])
     end
 
-    def prompt(language:, source_code:, code_comment_begin:, code_comment_end:, update_context_digests: [], changes_of_contexts: '')
+    def prompt(language:, source_code:, code_comment_begin:, code_comment_end:, update_context_digests: [],
+               changes_of_contexts: '', goals: '')
       @prompt.format(language: language,
                      source_code: source_code,
                      code_comment_begin: code_comment_begin,
                      code_comment_end: code_comment_end,
                      update_context_digests: update_context_digests.join(','),
-                     changes_of_contexts: changes_of_contexts)
+                     changes_of_contexts: changes_of_contexts,
+                     goals: goals)
     end
 
     # Change the default prompt, input variables: language, source_code
@@ -85,33 +103,35 @@ class LLMed
     end
 
     def llm
-      case @provider
-      when :openai
-        LLMed::LLM::OpenAI.new(
-          logger: @logger,
-          api_key: @provider_api_key,
-          default_options: { max_tokens: nil, temperature: 0.7, chat_model: @provider_model }
-        )
-      when :anthropic
-        LLMed::LLM::Anthropic.new(
-          logger: @logger,
-          api_key: @provider_api_key,
-          default_options: { max_tokens: nil, temperature: 0.7, chat_model: @provider_model }
-        )
-      when :like_openai
-        LLMed::LLM::LikeOpenAI.new(
-          logger: @logger,
-          api_key: @provider_api_key,
-          default_options: { temperature: 0.7, chat_model: @provider_model },
-          llm_options: @provider_options
-        )
-      when :test
-        LLMed::LLM::Test.new
-      when nil
-        raise 'Please set the provider with `set_llm(provider, api_key, model)`'
-      else
-        raise "not implemented provider #{@provider}"
-      end
+      llm_instance = case @provider
+                     when :openai
+                       LLMed::LLM::OpenAI.new(
+                         logger: @logger,
+                         api_key: @provider_api_key,
+                         default_options: { max_tokens: nil, temperature: 0.7, chat_model: @provider_model }
+                       )
+                     when :anthropic
+                       LLMed::LLM::Anthropic.new(
+                         logger: @logger,
+                         api_key: @provider_api_key,
+                         default_options: { max_tokens: nil, temperature: 0.7, chat_model: @provider_model }
+                       )
+                     when :like_openai
+                       LLMed::LLM::LikeOpenAI.new(
+                         logger: @logger,
+                         api_key: @provider_api_key,
+                         default_options: { temperature: 0.7, chat_model: @provider_model },
+                         llm_options: @provider_options
+                       )
+                     when :test
+                       LLMed::LLM::Test.new
+                     when nil
+                       raise 'Please set the provider with `set_llm(provider, api_key, model)`'
+                     else
+                       raise "not implemented provider #{@provider}"
+                     end
+
+      LLMed::LLM::Agent.new(llm_instance)
     end
   end
 end

data/lib/llmed/goal.rb

@@ -0,0 +1,25 @@
+# Copyright 2025 Jovany Leandro G.C <bit4bit@riseup.net>
+# frozen_string_literal: true
+
+class LLMed
+  class Goal
+    attr_reader :name, :options
+
+    def initialize(name:, options: {})
+      @name = name
+      @options = options
+    end
+
+    def llm(message)
+      @message = message
+    end
+
+    def message
+      "<goal name=\"#{@name}\">#{@message}</goal>"
+    end
+
+    def message?
+      !(@message.nil? || @message.empty?)
+    end
+  end
+end

data/lib/llmed/literate_programming/markdown.rb

@@ -1,9 +1,9 @@
-#<llmed-code context='Library LLMed::LiterateProgramming::Markdown' digest='9c0e3f61ab4cdc3c56c29230a800487dd1a7ef0d929c843fd2461907d0831ab2' after=''>
+# <llmed-code context='Library LLMed::LiterateProgramming::Markdown' digest='9c0e3f61ab4cdc3c56c29230a800487dd1a7ef0d929c843fd2461907d0831ab2' after=''>
 class LLMed::LiterateProgramming::Markdown
   def parse(input)
     contexts = []
     current_context = { type: :context, title: "_default", content: [] }
-    
+
     input.each_line do |line|
       if line.strip =~ /^# (.+)$/
         contexts << current_context unless current_context[:content].empty?
@@ -23,4 +23,4 @@ class LLMed::LiterateProgramming::Markdown
     contexts
   end
 end
-#</llmed-code>
+# </llmed-code>

data/lib/llmed/literate_programming.rb

@@ -41,7 +41,7 @@ class LLMed
               context[:content] += "#{URI.open(item_content[:reference]).read}\n"
             end
           end
-        contexts << context
+          contexts << context
         end
       end
 

data/lib/llmed.rb

@@ -93,6 +93,7 @@ end
 require_relative 'llm'
 require_relative 'llmed/configuration'
 require_relative 'llmed/context'
+require_relative 'llmed/goal'
 require_relative 'llmed/release'
 require_relative 'llmed/application'
 require_relative 'llmed/deployment'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llmed
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.2
 platform: ruby
 authors:
 - Jovany Leandro G.C
@@ -99,6 +99,7 @@ files:
 - lib/llmed/configuration.rb
 - lib/llmed/context.rb
 - lib/llmed/deployment.rb
+- lib/llmed/goal.rb
 - lib/llmed/literate_programming.rb
 - lib/llmed/literate_programming/markdown.rb
 - lib/llmed/literate_programming/markdown.rb.release