feat: merge branch 'master' into feature/m3-skill-schema

examples/actors/graph_workflow.yaml

@@ -0,0 +1,215 @@
+# Graph Actor - Test-Driven Development Workflow
+# Demonstrates a multi-node graph with conditional routing and subgraphs
+
+name: workflows/test_driven_dev
+type: graph
+description: Test-driven development workflow with automated testing and feedback loops
+version: "1.0"
+
+# LLM model for agent nodes
+model: gpt-4
+
+# Graph topology
+route:
+  # Define all nodes in the workflow
+  nodes:
+    # Entry point: planning agent
+    - id: planner
+      type: agent
+      name: Test Planner
+      description: Plans test cases based on requirements
+      config:
+        model: gpt-4
+        prompt: |
+          You are a test planning expert. Analyze the requirements and create
+          a comprehensive test plan covering:
+          - Unit tests for individual functions
+          - Integration tests for component interactions
+          - Edge cases and error conditions
+        tools:
+          - files/read_file
+          - files/list_directory
+
+    # Write tests first
+    - id: test_writer
+      type: agent
+      name: Test Writer
+      description: Writes test cases based on the plan
+      config:
+        model: gpt-4
+        prompt: |
+          You are a test writing expert. Write pytest tests based on the plan.
+          Follow best practices:
+          - Use descriptive test names
+          - Include docstrings
+          - Use fixtures appropriately
+          - Test one thing per test
+        tools:
+          - files/write_file
+          - files/read_file
+
+    # Run the tests (should fail initially)
+    - id: run_tests
+      type: tool
+      name: Test Runner
+      description: Executes pytest test suite
+      config:
+        tool_name: testing/run_pytest
+        parameters:
+          verbose: true
+          coverage: true
+
+    # Check test results
+    - id: check_results
+      type: conditional
+      name: Test Result Checker
+      description: Routes based on test pass/fail status
+      config:
+        conditions:
+          - check: "state.get('tests_passed') == True"
+            route_to: code_review
+          - check: "state.get('tests_passed') == False"
+            route_to: implementation_writer
+
+    # Write implementation to make tests pass
+    - id: implementation_writer
+      type: agent
+      name: Implementation Writer
+      description: Writes code to make the tests pass
+      config:
+        model: gpt-4
+        prompt: |
+          You are an implementation expert. Write clean, well-documented code
+          that makes the failing tests pass. Follow SOLID principles and
+          write maintainable code.
+        tools:
+          - files/write_file
+          - files/read_file
+
+    # Run tests again after implementation
+    - id: rerun_tests
+      type: tool
+      name: Test Rerunner
+      description: Re-executes tests after implementation
+      config:
+        tool_name: testing/run_pytest
+        parameters:
+          verbose: true
+          coverage: true
+
+    # Check if tests pass now
+    - id: verify_tests
+      type: conditional
+      name: Test Verification
+      description: Verify tests pass after implementation
+      config:
+        conditions:
+          - check: "state.get('tests_passed') == True"
+            route_to: code_review
+          - check: "state.get('tests_passed') == False and state.get('retry_count', 0) < 3"
+            route_to: debug_failures
+          - check: "state.get('tests_passed') == False and state.get('retry_count', 0) >= 3"
+            route_to: escalate
+
+    # Debug test failures
+    - id: debug_failures
+      type: agent
+      name: Debugger
+      description: Analyzes and fixes test failures
+      config:
+        model: gpt-4
+        prompt: |
+          You are a debugging expert. Analyze the test failures and fix the
+          implementation. Look for:
+          - Logic errors
+          - Edge cases
+          - Type mismatches
+          - Missing error handling
+        tools:
+          - files/read_file
+          - files/write_file
+
+    # Code review (subgraph)
+    - id: code_review
+      type: subgraph
+      name: Code Reviewer
+      description: Runs code review workflow
+      config:
+        actor_path: examples/actors/simple_llm.yaml
+
+    # Escalate if tests keep failing
+    - id: escalate
+      type: tool
+      name: Escalation Handler
+      description: Escalates persistent failures to human
+      config:
+        tool_name: notifications/send_alert
+        parameters:
+          channel: engineering
+          priority: high
+
+  # Define edges (workflow transitions)
+  edges:
+    # Linear flow from planner to test writer
+    - from_node: planner
+      to_node: test_writer
+
+    # Run tests after writing them
+    - from_node: test_writer
+      to_node: run_tests
+
+    # Check results after running tests
+    - from_node: run_tests
+      to_node: check_results
+
+    # Conditional routing from check_results
+    # (handled by the conditional node itself)
+
+    # Write implementation if tests fail
+    - from_node: implementation_writer
+      to_node: rerun_tests
+
+    # Verify tests after rerunning
+    - from_node: rerun_tests
+      to_node: verify_tests
+
+    # Debug if tests still fail
+    - from_node: debug_failures
+      to_node: rerun_tests
+
+    # All paths eventually lead to code review or escalation
+    # (handled by conditional nodes)
+
+  # Entry and exit points
+  entry_node: planner
+  exit_nodes:
+    - code_review
+    - escalate
+
+# Context settings
+context_view: strategist
+memory:
+  enabled: true
+  max_messages: 100
+  max_tokens: 16000
+  summarize_old: true
+
+context:
+  include_files:
+    - "README.md"
+    - "requirements.txt"
+    - "pyproject.toml"
+  include_dirs:
+    - "src/"
+    - "tests/"
+  exclude_patterns:
+    - "**/__pycache__/**"
+    - "*.pyc"
+    - "**/.pytest_cache/**"
+    - "**/htmlcov/**"
+  max_context_tokens: 32000
+
+# Environment variables
+env_vars:
+  PYTEST_ARGS: --verbose --cov --cov-report=html
+  MAX_RETRIES: "3"

examples/actors/llm_with_tools.yaml

@@ -0,0 +1,67 @@
+# LLM Actor with Tools
+# Demonstrates an LLM actor with access to multiple tools
+
+name: assistants/file_analyzer
+type: llm
+description: Analyzes files and generates reports using file system tools
+version: "1.0"
+
+# LLM configuration
+model: gpt-4-turbo
+system_prompt: |
+  You are a file analysis assistant. Use the available tools to:
+  - Read and analyze file contents
+  - Count lines, words, and characters
+  - Search for patterns in files
+  - Generate summary reports
+
+  Always explain what you're doing before using a tool.
+
+# Tools (mix of references and inline definitions)
+tools:
+  # Reference to existing tool
+  - files/read_file
+  - files/list_directory
+
+  # Inline tool definition
+  - name: utils/count_lines
+    description: Count the number of lines in a file
+    parameters:
+      - name: file_path
+        type: str
+        description: Path to the file to count lines in
+        required: true
+    code: |
+      def count_lines(file_path: str) -> int:
+          """Count lines in a file."""
+          with open(file_path, 'r', encoding='utf-8') as f:
+              return len(f.readlines())
+
+  - name: utils/word_count
+    description: Count words in a file
+    parameters:
+      - name: file_path
+        type: str
+        description: Path to the file
+        required: true
+    code: |
+      def word_count(file_path: str) -> int:
+          """Count words in a file."""
+          with open(file_path, 'r', encoding='utf-8') as f:
+              content = f.read()
+              return len(content.split())
+
+# Context settings
+context_view: executor
+memory:
+  enabled: true
+  max_messages: 30
+  max_tokens: 6000
+
+context:
+  max_context_tokens: 10000
+
+# Environment variables
+env_vars:
+  WORK_DIR: ${HOME}/workspace
+  LOG_LEVEL: info

examples/actors/simple_graph.yaml

@@ -0,0 +1,78 @@
+# Simple Graph Actor - Sequential Processing
+# Demonstrates a simple 3-node graph with linear execution
+
+name: workflows/document_processor
+type: graph
+description: Simple document processing workflow (extract → analyze → summarize)
+version: "1.0"
+
+# LLM model
+model: gpt-3.5-turbo
+
+# Graph topology
+route:
+  nodes:
+    # Node 1: Extract text from document
+    - id: extractor
+      type: tool
+      name: Text Extractor
+      description: Extracts text from various document formats
+      config:
+        tool_name: documents/extract_text
+        parameters:
+          formats:
+            - pdf
+            - docx
+            - txt
+
+    # Node 2: Analyze content
+    - id: analyzer
+      type: agent
+      name: Content Analyzer
+      description: Analyzes document structure and content
+      config:
+        model: gpt-3.5-turbo
+        prompt: |
+          Analyze the document content and identify:
+          - Main topics and themes
+          - Key entities (people, places, organizations)
+          - Sentiment and tone
+          - Document structure
+        tools:
+          - analysis/extract_entities
+          - analysis/sentiment_analysis
+
+    # Node 3: Generate summary
+    - id: summarizer
+      type: agent
+      name: Summarizer
+      description: Creates concise summary of document
+      config:
+        model: gpt-3.5-turbo
+        prompt: |
+          Create a concise summary of the document including:
+          - Main points (3-5 bullet points)
+          - Key findings
+          - Actionable insights
+          Keep it under 200 words.
+
+  # Linear edges
+  edges:
+    - from_node: extractor
+      to_node: analyzer
+    - from_node: analyzer
+      to_node: summarizer
+
+  # Entry and exit
+  entry_node: extractor
+  exit_nodes:
+    - summarizer
+
+# Context settings
+context_view: executor
+memory:
+  enabled: true
+  max_messages: 10
+
+context:
+  max_context_tokens: 4000

examples/actors/simple_llm.yaml

@@ -0,0 +1,38 @@
+# Simple LLM Actor Example
+# Demonstrates the most basic actor configuration with just an LLM and system prompt
+
+name: assistants/code_reviewer
+type: llm
+description: Reviews Python code for best practices, style, and potential bugs
+version: "1.0"
+
+# LLM configuration
+model: gpt-4
+system_prompt: |
+  You are an expert Python code reviewer. Review code for:
+  - PEP 8 style compliance
+  - Best practices and design patterns
+  - Potential bugs and edge cases
+  - Performance considerations
+  - Security vulnerabilities
+
+  Provide constructive feedback with specific suggestions for improvement.
+
+# Context and memory settings
+context_view: reviewer
+memory:
+  enabled: true
+  max_messages: 20
+  max_tokens: 4000
+
+context:
+  include_files:
+    - "README.md"
+    - "pyproject.toml"
+  include_dirs:
+    - "src/"
+  exclude_patterns:
+    - "**/__pycache__/**"
+    - "*.pyc"
+    - "**/.pytest_cache/**"
+  max_context_tokens: 8000

examples/actors/tool_collection.yaml

@@ -0,0 +1,45 @@
+# Tool-Only Actor
+# Demonstrates an actor that only provides tools without LLM interaction
+
+name: utilities/file_operations
+type: tool
+description: Collection of file operation tools for other actors to use
+version: "1.0"
+
+# Tool collection
+tools:
+  # Reference existing tools
+  - files/read_file
+  - files/write_file
+  - files/delete_file
+  - files/copy_file
+  - files/move_file
+  - files/list_directory
+  - files/create_directory
+
+  # Add custom validation tool
+  - name: validators/check_python_syntax
+    description: Validate Python file syntax without executing it
+    parameters:
+      - name: file_path
+        type: str
+        description: Path to Python file to validate
+        required: true
+    code: |
+      import ast
+      def check_python_syntax(file_path: str) -> dict:
+          """Check if a Python file has valid syntax."""
+          try:
+              with open(file_path, 'r', encoding='utf-8') as f:
+                  ast.parse(f.read())
+              return {"valid": True, "error": None}
+          except SyntaxError as e:
+              return {
+                  "valid": False,
+                  "error": str(e),
+                  "line": e.lineno,
+                  "offset": e.offset
+              }
+
+# No LLM configuration needed for tool-only actors
+# No system prompt needed