003 hello world agent

.cursor/rules/gram-validation.mdc

@@ -0,0 +1,29 @@
+# Gram Syntax Validation Rules
+
+## Validation Requirement
+- **Always** validate gram notation syntax using `gram-lint` CLI tool
+- Run validation on any `.gram` file before considering it complete
+- All gram examples must pass `gram-lint` syntax checks
+
+## Usage
+```bash
+gram-lint path/to/file.gram
+```
+
+## When to Validate
+- Before committing changes to `.gram` files
+- When creating new gram examples in tests or documentation
+- When modifying existing gram notation
+- As part of code review process
+
+## Examples
+All gram syntax in these locations must be validated:
+- `specs/**/*.gram` - Specification examples
+- `docs/**/*.gram` - Documentation examples  
+- `tests/**/*.gram` - Test fixtures
+- Any inline gram notation in code comments or documentation
+
+## Integration
+- When writing or modifying gram notation, verify syntax with `gram-lint` to ensure correctness
+- All gram examples in code, tests, and documentation should pass `gram-lint` validation
+- If `gram-lint` reports errors, fix the syntax before proceeding

.cursor/rules/specify-rules.mdc

@@ -4,6 +4,7 @@ Auto-generated from all feature plans. Last updated: 2025-12-10
 
 ## Active Technologies
 - In-memory conversation context (no persistence required for initial implementation) (002-llm-agent)
+- In-memory tool registry and conversation context (no persistence required for initial implementation) (003-hello-world-agent)
 
 - Haskell / GHC 2024 (GHC2024 language standard) (001-foundation-setup)
 
@@ -23,6 +24,7 @@ tests/
 Haskell / GHC 2024 (GHC2024 language standard): Follow standard conventions
 
 ## Recent Changes
+- 003-hello-world-agent: Added Haskell / GHC 2024 (GHC2024 language standard)
 - 002-llm-agent: Added Haskell / GHC 2024 (GHC2024 language standard)
 
 - 001-foundation-setup: Added Haskell / GHC 2024 (GHC2024 language standard)

.github/workflows/haskell.yml

@@ -18,8 +18,8 @@ jobs:
     - uses: actions/checkout@v4
     - uses: actions/setup-haskell@v1
       with:
-        ghc-version: '8.10.3'
-        cabal-version: '3.2'
+        ghc-version: '9.10.3'
+        cabal-version: 'latest'
 
     - name: Cache
       uses: actions/cache@v3

DEVELOP.md

@@ -190,7 +190,7 @@ module AgentTest where
 
 import Test.Tasty
 import Test.Tasty.HUnit
-import PatternAgent.Agent
+import PatternAgent.Language.Core
 
 testAgentCreation :: TestTree
 testAgentCreation = testCase "Create agent" $ do
@@ -362,11 +362,15 @@ Use `haskell-tools.nvim` or `coc-haskell` with HLS.
 - **`PatternAgent.Core`**: Core type definitions (re-exports PatternAgent type)
 - **`PatternAgent.Types`**: Type aliases and supporting types
 - **`PatternAgent.Agent`**: Agent type and creation
-- **`PatternAgent.LLM`**: Standalone LLM API client
-- **`PatternAgent.Execution`**: Agent execution logic
-- **`PatternAgent.Context`**: Conversation context management
+- **`PatternAgent.Language.Core`**: Agent and Tool as Pattern Subject, creation, lenses
+- **`PatternAgent.Language.Schema`**: Schema validation
+- **`PatternAgent.Language.TypeSignature`**: Type signature parsing & JSON schema generation
+- **`PatternAgent.Language.Serialization`**: Gram ↔ Pattern conversion
+- **`PatternAgent.Runtime.Execution`**: Agent execution engine
+- **`PatternAgent.Runtime.ToolLibrary`**: ToolImpl and ToolLibrary
+- **`PatternAgent.Runtime.LLM`**: LLM API client
+- **`PatternAgent.Runtime.Context`**: Conversation context management
 - **`PatternAgent.Env`**: Environment variable loading from .env files
-- **`PatternAgent.Tool`**: Tool system (not yet implemented)
 
 ### Adding New Features
 

MINIMAL_GRAM_ISSUE.md

@@ -0,0 +1,56 @@
+# Minimal Example: Multiline Gram Parsing Issue
+
+## Issue Description
+
+When parsing gram notation with multiline format, a newline immediately after `} |` causes a parse error: "unexpected newline".
+
+## Minimal Failing Example
+
+```gram
+[test:Agent {
+  description: "test"
+} |
+  [tool:Tool {description: "test"} | (param::Text)==>(::String)]
+]
+```
+
+**Error**: `gram:3:4: unexpected newline expecting '"', ''', '(', '-', '@', '[', '`', '{', digit, space, or tab`
+
+The error occurs at position 3:4, which is the newline character immediately after `} |`.
+
+## Working Single-line Version
+
+```gram
+[test:Agent {description: "test"} | [tool:Tool {description: "test"} | (param::Text)==>(::String)]]
+```
+
+This single-line version parses successfully.
+
+## Test Code
+
+```haskell
+import qualified Gram
+import qualified Data.Text as T
+
+main = do
+  let gramMultiline = T.unlines
+        [ "[test:Agent {"
+        , "  description: \"test\""
+        , "} |"
+        , "  [tool:Tool {description: \"test\"} | (param::Text)==>(::String)]"
+        , "]"
+        ]
+
+  case Gram.fromGram (T.unpack gramMultiline) of
+    Right _ -> putStrLn "Success"
+    Left err -> putStrLn $ "Error: " ++ show err
+```
+
+## Expected Behavior
+
+The multiline format should parse successfully, as it's valid gram syntax according to `gram-lint`. The parser should handle newlines after `} |` when followed by pattern elements on subsequent lines.
+
+## Context
+
+This issue was discovered when writing tests for `pattern-agent` that parse agents with nested tools from gram notation. The example file `specs/003-hello-world-agent/examples/helloAgent.gram` uses the same multiline format and passes `gram-lint`, but fails when parsed programmatically with `Gram.fromGram`.
+

README.md

@@ -64,6 +64,56 @@ Areas under active exploration:
 
 Early development - establishing foundations through practical examples.
 
+## Running the CLI
+
+The pattern-agent CLI can be used to execute agents from gram files or interact directly with LLMs.
+
+### Building
+
+```bash
+cabal build
+```
+
+### Usage
+
+**Important:** When using `cabal exec pattern-agent`, you must use `--` to separate cabal's flags from pattern-agent's flags:
+
+```bash
+# Standard mode (direct LLM interaction)
+cabal exec pattern-agent -- "What is the capital of France?"
+
+# With debug output
+cabal exec pattern-agent -- --debug "What is the capital of France?"
+
+# Agent mode (load agent from gram file with tool support)
+cabal exec pattern-agent -- --agent examples/helloAgent.gram "Hello!"
+
+# Agent mode with debug
+cabal exec pattern-agent -- --agent examples/helloAgent.gram --debug "Hello!"
+```
+
+### Prerequisites
+
+Set the `OPENAI_API_KEY` environment variable:
+
+```bash
+export OPENAI_API_KEY=your-api-key-here
+```
+
+### After Installation
+
+If you install the executable:
+
+```bash
+cabal install --installdir=$HOME/.local/bin
+```
+
+You can then run it directly without `cabal exec`:
+
+```bash
+pattern-agent --agent examples/helloAgent.gram "Hello!"
+```
+
 ## Future Directions
 
 - Decomposition toolkit with factorization strategies