llmed 0.6.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c47ebb44059bae3a1ffc2d27dd064098036ebd390cb677a488761845e13d4b6b
-  data.tar.gz: 1442dec8d3c594b8610af95d7edfbdbdee8881ac00a046001cc6fd4eb9c2e68c
+  metadata.gz: 87fc5d9fa3991a03d2055b3da5f8ec1203af3e987c6ff711353a3d617f3a5add
+  data.tar.gz: e4b535f0353bc4c575d84cb0648a7d8d38bc62b3d585f87f9eb4fde18b36d835
 SHA512:
-  metadata.gz: 80a7c93eed1106305b848bae99b0fcce744c55bc933538465041e19329ed1e6fe01f398c38ec849f2ae4981ec260024d3a9ded96f1465224a0b9f60cc8924b53
-  data.tar.gz: 7c3df54bec3ee2e2f02bd7108c92004e6969bb8019ab5209bda32327cc916492ac2946948b2ce835325b93d33238292187870e68bc35bfa50feefb0b38164263
+  metadata.gz: bf87dca2cc6babed42917e624511032e5f9747679244199a8340f6f2cbeca95bfa9a3fbf839a5ede32051138f7ae18affe154fe20177a9ae1ca20b03052e6cd7
+  data.tar.gz: 6243e74686ffc0aabfe27310216fab81a1dd5a6a7ea987da095b579eb6ba23323e6f68f26b948f4899d3b52c7f01ecf6ceb3ada1eaa8512c26b897c06eccf89a

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/lib/#llm.rb#

@@ -0,0 +1,114 @@
+require 'openai'
+require 'langchain'
+
+Langchain.logger.level = Logger::ERROR
+
+class LLMed
+  module LLM
+    module Message
+      System = Struct.new(:content)
+      User = Struct.new(:content)
+    end
+
+    module Template
+      def self.build(template:, input_variables:)
+        Langchain::Prompt::PromptTemplate.new(template: template, input_variables: input_variables)
+      end
+    end
+
+    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))
+      end
+
+      def chat(messages: [])
+        messages = messages.map do |m|
+          case messages
+          when Message::System
+            { role: 'system', content: m.content }
+          when Message::User
+            { role: 'user', content: m.content }
+          end
+        end
+        messages.e
+        start = Time.now
+        llm_response = @llm.chat(messages: messages, max_tokens: MAX_TOKENS)
+        warn_token_limits(llm_response)
+
+        stop = Time.now
+        Response.new({ provider: provider,
+                       model: @llm.chat_parameters[:model],
+                       duration_seconds: stop.to_i - start.to_i,
+                       source_code: source_code(llm_response.chat_completion),
+                       total_tokens: llm_response.total_tokens })
+      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
+      end
+
+      def llm_arguments(args)
+        args
+      end
+
+      def provider
+        :openai
+      end
+
+      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 llm_arguments(args)
+        @logger = args.delete(:logger)
+        args.merge({ llm_options: { uri_base: 'https://api.anthropic.com/v1/' } })
+      end
+
+      def provider
+        :anthropic
+      end
+    end
+
+    class LikeOpenAI < OpenAI
+      private
+
+      def llm_arguments(args)
+        args
+      end
+
+      def provider
+        :like_openai
+      end
+    end
+
+    class Test
+      def initialize
+        @output = ''
+      end
+
+      def chat(messages: [])
+        @output = messages.map { |m| m[:content] }.join("\n")
+
+        Response.new({ provider: :test,
+                       model: 'test',
+                       duration_seconds: 0,
+                       source_code: @output,
+                       total_tokens: 0 })
+      end
+    end
+  end
+end

data/lib/llm.rb~

@@ -0,0 +1,114 @@
+require 'openai'
+require 'langchain'
+
+Langchain.logger.level = Logger::ERROR
+
+class LLMed
+  module LLM
+    module Message
+      System = Struct.new(:content)
+      User = Struct.new(:content)
+    end
+
+    module Template
+      def self.build(template:, input_variables:)
+        Langchain::Prompt::PromptTemplate.new(template: template, input_variables: input_variables)
+      end
+    end
+
+    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))
+      end
+
+      def chat(messages: [])
+        messages = messages.map do |m|
+          case m
+          when Message::System
+            { role: 'system', content: m.content }
+          when Message::User
+            { role: 'user', content: m.content }
+          end
+        end
+
+        start = Time.now
+        llm_response = @llm.chat(messages: messages, max_tokens: MAX_TOKENS)
+        warn_token_limits(llm_response)
+
+        stop = Time.now
+        Response.new({ provider: provider,
+                       model: @llm.chat_parameters[:model],
+                       duration_seconds: stop.to_i - start.to_i,
+                       source_code: source_code(llm_response.chat_completion),
+                       total_tokens: llm_response.total_tokens })
+      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
+      end
+
+      def llm_arguments(args)
+        args
+      end
+
+      def provider
+        :openai
+      end
+
+      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 llm_arguments(args)
+        @logger = args.delete(:logger)
+        args.merge({ llm_options: { uri_base: 'https://api.anthropic.com/v1/' } })
+      end
+
+      def provider
+        :anthropic
+      end
+    end
+
+    class LikeOpenAI < OpenAI
+      private
+
+      def llm_arguments(args)
+        args
+      end
+
+      def provider
+        :like_openai
+      end
+    end
+
+    class Test
+      def initialize
+        @output = ''
+      end
+
+      def chat(messages: [])
+        @output = messages.map { |m| m[:content] }.join("\n")
+
+        Response.new({ provider: :test,
+                       model: 'test',
+                       duration_seconds: 0,
+                       source_code: @output,
+                       total_tokens: 0 })
+      end
+    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
@@ -57,6 +58,15 @@ class LLMed
       @contexts << ctx
     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
@@ -83,8 +93,11 @@ 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
+          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
@@ -160,8 +173,6 @@ class LLMed
     end
 
     def prepare_snapshot
-      raise "snapshot preparation require contexts" if @contexts.empty?
-
       @logger.info("APPLICATION #{@name} PREPARING SNAPSHOT #{@snapshot.snapshot_file}")
 
       @snapshot.sync(@contexts)
@@ -205,6 +216,7 @@ class LLMed
     end
 
     def patch_or_create(output)
+
       output_content = output
 
       if @release && File.exist?(release_source_code) && !release_contexts.empty?
@@ -233,6 +245,7 @@ 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 +267,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 +313,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,27 @@ 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

data/lib/llmed/goal.rb

@@ -0,0 +1,26 @@
+# 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.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.1
 platform: ruby
 authors:
 - Jovany Leandro G.C
@@ -93,12 +93,15 @@ files:
 - README.md
 - exe/llmed
 - exe/llmed.literate
+- lib/#llm.rb#
 - lib/llm.rb
+- lib/llm.rb~
 - lib/llmed.rb
 - lib/llmed/application.rb
 - 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