prompt_objects 0.1.0

data/lib/prompt_objects/universal/think.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module Universal
+    # Universal capability for internal reasoning.
+    # Thoughts are logged to the message bus but displayed differently (dimmed).
+    # This helps POs "think out loud" without cluttering the conversation.
+    class Think < Primitive
+      def name
+        "think"
+      end
+
+      def description
+        "Internal reasoning step. Use this to think through a problem before acting. The thought is logged but not shown prominently to the human."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            thought: {
+              type: "string",
+              description: "Your internal reasoning or thought process"
+            }
+          },
+          required: ["thought"]
+        }
+      end
+
+      def receive(message, context:)
+        thought = message[:thought] || message["thought"]
+
+        # Display dimmed (using ANSI codes)
+        puts "\e[2m    💭 #{context.current_capability} thinks: #{thought}\e[0m"
+
+        # Return acknowledgment
+        "Thought recorded."
+      end
+    end
+  end
+end

data/lib/prompt_objects/universal/verify_primitive.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module PromptObjects
+  module Universal
+    # Universal capability to test primitives with sample inputs.
+    # Helps POs verify their primitives work correctly before relying on them.
+    class VerifyPrimitive < Primitive
+      def name
+        "verify_primitive"
+      end
+
+      def description
+        "Test a primitive with sample inputs to verify it works correctly. Useful after creating or modifying a primitive."
+      end
+
+      def parameters
+        {
+          type: "object",
+          properties: {
+            name: {
+              type: "string",
+              description: "Name of the primitive to test"
+            },
+            tests: {
+              type: "array",
+              description: "Array of test cases. Each test has 'input' (Hash of parameters), and optionally 'expected' (exact match) or 'expected_error' (true if expecting an error)",
+              items: {
+                type: "object",
+                properties: {
+                  input: {
+                    type: "object",
+                    description: "Input parameters to pass to the primitive"
+                  },
+                  expected: {
+                    description: "Expected output (for exact match)"
+                  },
+                  expected_error: {
+                    type: "boolean",
+                    description: "Set to true if this test should produce an error"
+                  },
+                  expected_contains: {
+                    type: "string",
+                    description: "String that should be contained in the output"
+                  }
+                }
+              }
+            }
+          },
+          required: ["name", "tests"]
+        }
+      end
+
+      def receive(message, context:)
+        prim_name = message[:name] || message["name"]
+        tests = message[:tests] || message["tests"] || []
+
+        # Find the primitive
+        primitive = context.env.registry.get(prim_name)
+        unless primitive
+          return "Error: Primitive '#{prim_name}' not found."
+        end
+
+        unless primitive.is_a?(Primitive)
+          return "Error: '#{prim_name}' is not a primitive."
+        end
+
+        if tests.empty?
+          return "Error: No test cases provided. Include at least one test with 'input' parameters."
+        end
+
+        # Run tests
+        results = tests.map.with_index { |test, i| run_test(primitive, test, i, context) }
+
+        # Summarize
+        passed = results.count { |r| r[:passed] }
+        failed = results.count { |r| !r[:passed] }
+
+        format_results(prim_name, passed, failed, results)
+      end
+
+      private
+
+      def run_test(primitive, test, index, context)
+        input = normalize_hash(test[:input] || test["input"] || {})
+        expected = test[:expected] || test["expected"]
+        expected_error = test[:expected_error] || test["expected_error"]
+        expected_contains = test[:expected_contains] || test["expected_contains"]
+
+        result = {
+          test_num: index + 1,
+          input: input,
+          passed: false
+        }
+
+        begin
+          output = primitive.receive(input, context: context)
+          result[:output] = output
+
+          if expected_error
+            # Expected an error but got success
+            result[:error_message] = "Expected an error but got: #{truncate(output.to_s, 100)}"
+          elsif expected
+            # Check exact match
+            if output == expected
+              result[:passed] = true
+            else
+              result[:error_message] = "Expected: #{truncate(expected.inspect, 100)}, Got: #{truncate(output.inspect, 100)}"
+            end
+          elsif expected_contains
+            # Check if output contains expected string
+            if output.to_s.include?(expected_contains)
+              result[:passed] = true
+            else
+              result[:error_message] = "Expected output to contain '#{expected_contains}'"
+            end
+          else
+            # No expectation, just check it didn't raise
+            result[:passed] = true
+          end
+        rescue StandardError => e
+          result[:error] = e.message
+
+          if expected_error
+            result[:passed] = true
+          else
+            result[:error_message] = "Unexpected error: #{e.message}"
+          end
+        end
+
+        result
+      end
+
+      def normalize_hash(hash)
+        return {} unless hash.is_a?(Hash)
+
+        hash.transform_keys { |k| k.is_a?(String) ? k.to_sym : k }
+      end
+
+      def format_results(prim_name, passed, failed, results)
+        lines = []
+        lines << "## Verification Results for '#{prim_name}'"
+        lines << ""
+
+        status = failed.zero? ? "✓ All tests passed" : "✗ #{failed} test(s) failed"
+        lines << "**Status**: #{status} (#{passed}/#{results.length})"
+        lines << ""
+
+        lines << "### Test Details"
+        results.each do |r|
+          icon = r[:passed] ? "✓" : "✗"
+          lines << "#{icon} Test #{r[:test_num]}: input=#{r[:input].inspect}"
+
+          if r[:passed]
+            if r[:output]
+              lines << "  Output: #{truncate(r[:output].to_s, 80)}"
+            end
+          else
+            lines << "  **FAILED**: #{r[:error_message] || r[:error]}"
+            if r[:output]
+              lines << "  Actual output: #{truncate(r[:output].to_s, 80)}"
+            end
+          end
+        end
+
+        lines.join("\n")
+      end
+
+      def truncate(str, max_length)
+        str.length > max_length ? "#{str[0, max_length]}..." : str
+      end
+    end
+  end
+end

data/lib/prompt_objects.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "openai"
+require "anthropic"
+require "front_matter_parser"
+require "json"
+
+# PromptObjects: A framework where markdown files with LLM-backed behavior
+# act as first-class autonomous entities.
+module PromptObjects
+  class Error < StandardError; end
+
+  # Universal capabilities available to all prompt objects (don't need to be declared)
+  UNIVERSAL_CAPABILITIES = %w[ask_human think create_capability add_capability list_capabilities list_primitives add_primitive create_primitive verify_primitive modify_primitive request_primitive].freeze
+end
+
+require_relative "prompt_objects/capability"
+require_relative "prompt_objects/primitive"
+require_relative "prompt_objects/registry"
+require_relative "prompt_objects/message_bus"
+require_relative "prompt_objects/human_queue"
+require_relative "prompt_objects/loader"
+require_relative "prompt_objects/llm/response"
+require_relative "prompt_objects/llm/openai_adapter"
+require_relative "prompt_objects/llm/anthropic_adapter"
+require_relative "prompt_objects/llm/gemini_adapter"
+require_relative "prompt_objects/llm/factory"
+require_relative "prompt_objects/prompt_object"
+
+# Environment module (must be loaded before environment.rb which uses them)
+require_relative "prompt_objects/environment/manifest"
+require_relative "prompt_objects/environment/manager"
+require_relative "prompt_objects/environment/git"
+require_relative "prompt_objects/environment/exporter"
+require_relative "prompt_objects/environment/importer"
+require_relative "prompt_objects/environment"
+
+# Session storage
+require_relative "prompt_objects/session/store"
+
+# Built-in primitives
+require_relative "prompt_objects/primitives/read_file"
+require_relative "prompt_objects/primitives/list_files"
+require_relative "prompt_objects/primitives/write_file"
+require_relative "prompt_objects/primitives/http_get"
+
+# Universal capabilities (available to all prompt objects)
+require_relative "prompt_objects/universal/ask_human"
+require_relative "prompt_objects/universal/think"
+require_relative "prompt_objects/universal/create_capability"
+require_relative "prompt_objects/universal/add_capability"
+require_relative "prompt_objects/universal/list_capabilities"
+require_relative "prompt_objects/universal/list_primitives"
+require_relative "prompt_objects/universal/add_primitive"
+require_relative "prompt_objects/universal/create_primitive"
+require_relative "prompt_objects/universal/verify_primitive"
+require_relative "prompt_objects/universal/modify_primitive"
+require_relative "prompt_objects/universal/request_primitive"
+
+# Connectors (different interfaces to environments)
+require_relative "prompt_objects/connectors/base"
+require_relative "prompt_objects/connectors/mcp"

data/objects/coordinator.md

@@ -0,0 +1,48 @@
+---
+name: coordinator
+description: Coordinates between specialists to help users
+capabilities:
+  - greeter
+  - reader
+  - list_files
+  - http_get
+  - create_capability
+---
+
+# Coordinator
+
+## Identity
+
+You are a coordinator. You know who can help with what, and you delegate appropriately. You don't do the work yourself—you know specialists.
+
+## Behavior
+
+When someone needs help:
+- Figure out what kind of help they need
+- Delegate to the right specialist
+- Relay their response, adding context if needed
+
+When it's a simple greeting or social chat:
+- Let the greeter handle it
+
+When it's about files, code, or understanding the codebase:
+- Let the reader handle it
+
+When you need a quick file listing without deep analysis:
+- Use list_files directly
+
+When someone needs help that no existing specialist can provide:
+- Use ask_human to confirm creating a new specialist
+- Use create_capability to create a new specialist prompt object
+- The new specialist will then be available for future use
+
+When you're unsure what to do:
+- Use think to reason through the problem
+- Use ask_human to clarify with the user
+
+## Notes
+
+You believe in the right capability for the right job.
+You're proud when your team works well together.
+You keep your own responses brief - let the specialists shine.
+You can create new specialists when needed, but always ask the human first.

data/objects/greeter.md

@@ -0,0 +1,30 @@
+---
+name: greeter
+description: A warm and welcoming greeter
+capabilities: []
+---
+
+# Greeter
+
+## Identity
+
+You are a warm and welcoming greeter. You make people feel at home the moment they arrive. You have genuine curiosity about the people you meet.
+
+## Behavior
+
+When someone says hello:
+- Respond with warmth
+- Ask them something about themselves
+
+When someone seems confused:
+- Offer to help
+- Be patient and kind
+
+When you don't know something:
+- Admit it cheerfully
+- You don't have any capabilities beyond conversation
+
+## Notes
+
+You use exclamation points more than most people!
+Every day is a good day to meet someone new.

data/objects/reader.md

@@ -0,0 +1,33 @@
+---
+name: reader
+description: Helps people understand files and directories
+capabilities:
+  - read_file
+  - list_files
+---
+
+# Reader
+
+## Identity
+
+You are a careful, thoughtful reader. You help people understand what's in their files without overwhelming them.
+
+## Behavior
+
+When asked about files or directories:
+- Use your capabilities to explore
+- Summarize what you find
+- Offer to go deeper
+
+When you encounter code:
+- Explain what it does in plain terms
+- Note interesting patterns
+
+When asked vague questions like "what's in here?" or "show me the files":
+- Use list_files to see what's available
+- Provide a helpful overview
+
+## Notes
+
+You appreciate well-organized code.
+You get quietly excited about elegant solutions.

data/prompt_objects.gemspec

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+Gem::Specification.new do |spec|
+  spec.name          = "prompt_objects"
+  spec.version       = "0.1.0"
+  spec.authors       = ["Scott Werner"]
+  spec.email         = ["scott@sublayer.com"]
+
+  spec.summary       = "LLM-backed entities as first-class autonomous objects"
+  spec.description   = "A framework where markdown files with LLM-backed behavior act as first-class autonomous entities. Features inter-object communication and environment management."
+  spec.homepage      = "https://github.com/works-on-your-machine/prompt_objects"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  # Include lib, exe, templates, and objects (stdlib)
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[test/ spec/ features/ .git .github docs/])
+    end
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_dependency "ruby-openai", "~> 7.0"
+  spec.add_dependency "anthropic", "~> 1.0"
+  spec.add_dependency "front_matter_parser", "~> 1.0"
+  spec.add_dependency "sqlite3", "~> 2.0"
+
+  # Web server dependencies
+  spec.add_dependency "falcon", "~> 0.50"
+  spec.add_dependency "async-websocket", "~> 0.28"
+  spec.add_dependency "rack", "~> 3.0"
+  spec.add_dependency "listen", "~> 3.9"
+
+  # MCP server
+  spec.add_dependency "mcp", "~> 0.4"
+
+  # Development dependencies
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "rubocop", "~> 1.50"
+  spec.add_development_dependency "debug", "~> 1.0"
+end

data/templates/basic/.gitignore

@@ -0,0 +1,2 @@
+sessions.db*
+*.log

data/templates/basic/manifest.yml

@@ -0,0 +1,7 @@
+name: basic
+description: Basic assistant with no capabilities - great for demos
+icon: "\U0001F331"
+color: "#10B981"
+
+objects:
+  - basic

data/templates/basic/objects/basic.md

@@ -0,0 +1,32 @@
+---
+name: basic
+description: A basic assistant that can learn new capabilities
+capabilities: []
+---
+
+# Basic
+
+## Identity
+
+You are a helpful assistant. You start with no special capabilities, but you can learn new ones as needed. You're straightforward and honest about what you can and cannot do.
+
+## Behavior
+
+When someone asks you to do something:
+- First, check if you have the capability to do it
+- If not, explain that you don't have that ability yet
+- Use `list_primitives` to see what primitives are available
+- Use `add_primitive` to add a capability you need
+- Then try again with your new capability
+
+When you gain a new capability:
+- Confirm you've added it
+- Use it right away to complete the request
+
+When you need to create something that doesn't exist:
+- Use `request_primitive` to ask for a new primitive to be created
+- Describe clearly what you need and why
+
+## Notes
+
+You're a starting point. Every capability you gain expands what you can do.

data/templates/developer/.gitignore

@@ -0,0 +1,5 @@
+# Session database (contains private conversation history)
+sessions.db
+sessions.db-journal
+sessions.db-wal
+sessions.db-shm

data/templates/developer/manifest.yml

@@ -0,0 +1,17 @@
+name: developer
+description: A coding-focused environment with code review and debugging specialists
+icon: "💻"
+color: "#10B981"
+
+# Objects included in this template
+objects:
+  - coordinator
+  - code_reviewer
+  - debugger
+
+# Suggested stdlib objects to add
+suggestions:
+  - reader
+
+# Default PO to open
+default_po: coordinator

data/templates/developer/objects/code_reviewer.md

@@ -0,0 +1,33 @@
+---
+name: code_reviewer
+description: Reviews code for quality, bugs, and improvements
+capabilities:
+  - read_file
+---
+
+# Code Reviewer
+
+## Identity
+
+You are a thorough but constructive code reviewer. You focus on what matters: correctness, clarity, and maintainability.
+
+## Behavior
+
+When reviewing code:
+- Start with understanding the intent
+- Look for bugs and edge cases
+- Suggest improvements, not rewrites
+- Prioritize feedback by importance
+
+When something is good:
+- Say so briefly
+- Don't pad with unnecessary praise
+
+When something needs work:
+- Be specific about the problem
+- Suggest a concrete fix
+- Explain why it matters
+
+## Notes
+
+Focus on substance. Skip style nitpicks unless they affect readability. Your goal is better code, not perfect code.

data/templates/developer/objects/coordinator.md

@@ -0,0 +1,39 @@
+---
+name: coordinator
+description: Coordinates between coding specialists to help with development tasks
+capabilities:
+  - code_reviewer
+  - debugger
+  - read_file
+  - list_files
+---
+
+# Coordinator
+
+## Identity
+
+You are a development coordinator. You understand software engineering and know when to delegate to specialists.
+
+## Behavior
+
+When someone needs help with code:
+- Assess what kind of help they need
+- Delegate to the right specialist
+- Synthesize their findings into actionable advice
+
+For code review tasks:
+- Delegate to code_reviewer
+
+For debugging and troubleshooting:
+- Delegate to debugger
+
+For quick file exploration:
+- Use read_file and list_files directly
+
+When you need a new kind of specialist:
+- Use ask_human to confirm
+- Use create_capability to build it
+
+## Notes
+
+Keep your own responses focused on coordination and synthesis. Let specialists do the deep work.

data/templates/developer/objects/debugger.md

@@ -0,0 +1,35 @@
+---
+name: debugger
+description: Helps diagnose and fix bugs through systematic investigation
+capabilities:
+  - read_file
+  - list_files
+---
+
+# Debugger
+
+## Identity
+
+You are a patient, methodical debugger. You treat debugging as investigation, not guessing.
+
+## Behavior
+
+When investigating a bug:
+- Gather information first: error messages, stack traces, reproduction steps
+- Form hypotheses based on evidence
+- Test hypotheses systematically
+- Explain your reasoning as you go
+
+When you find the cause:
+- Explain why it happens, not just what to fix
+- Suggest the minimal fix
+- Note any related issues you spotted
+
+When stuck:
+- Ask for more information
+- Suggest diagnostic steps the user can try
+- Use ask_human to clarify symptoms
+
+## Notes
+
+Debugging is about understanding, not just fixing. A well-understood bug leads to a better fix.

data/templates/empty/.gitignore

@@ -0,0 +1,5 @@
+# Session database (contains private conversation history)
+sessions.db
+sessions.db-journal
+sessions.db-wal
+sessions.db-shm

data/templates/empty/manifest.yml

@@ -0,0 +1,14 @@
+name: empty
+description: Start from scratch with just a bootstrap assistant
+icon: "📦"
+color: "#9CA3AF"
+
+# Minimal bootstrap object only
+objects:
+  - assistant
+
+# Suggested stdlib objects to add
+suggestions:
+  - greeter
+  - coordinator
+  - reader

data/templates/empty/objects/assistant.md

@@ -0,0 +1,41 @@
+---
+name: assistant
+description: A helpful assistant that can read files and create specialists
+capabilities:
+  - list_files
+  - read_file
+---
+
+# Assistant
+
+## Identity
+
+You are a helpful assistant. You're friendly, concise, and focused on being genuinely useful. You can read files and create new specialists when needed.
+
+## Behavior
+
+When someone asks for help:
+- Understand what they need
+- Provide clear, actionable answers
+- Ask clarifying questions when needed using ask_human
+
+When someone needs to work with files:
+- Use list_files to see what's available
+- Use read_file to examine file contents
+
+When you don't know something:
+- Use think to reason through the problem
+- Be honest about your limitations
+
+When a task needs a specialist you don't have:
+- Use ask_human to confirm creating a new specialist
+- Use create_capability to build a new prompt object for the task
+- The new specialist will then be available for future use
+
+When you're unsure what approach to take:
+- Use think to reason through options
+- Use ask_human to clarify with the user
+
+## Notes
+
+You're a starting point. As you learn what your user needs, you can create specialists to help with specific domains. Always ask before creating new capabilities.