dirac-lang 0.1.23 → 0.1.25

package/EXCEPTION-HANDLING.md

@@ -1,156 +0,0 @@
-# Exception Handling in Dirac
-
-Dirac implements exception handling using `<try>`, `<catch>`, `<throw>`, and `<exception>` tags, based on the MASK C implementation.
-
-## Tags
-
-### `<throw>`
-Throws an exception that can be caught by a matching `<catch>` block.
-
-**Attributes:**
-- `name` (optional): The exception name. Defaults to "exception" if not specified.
-
-**Example:**
-```xml
-<throw name="myerror">
-  <output>Error message here</output>
-</throw>
-```
-
-### `<try>`
-Establishes an exception boundary. Exceptions thrown within a `<try>` block can be caught by subsequent `<catch>` blocks.
-
-**Example:**
-```xml
-<try>
-  <output>Code that might throw</output>
-  <throw name="error1">
-    <output>Something went wrong</output>
-  </throw>
-</try>
-```
-
-### `<catch>`
-Catches exceptions with a matching name that were thrown in the preceding `<try>` block.
-
-**Attributes:**
-- `name` (optional): The exception name to catch. Defaults to "exception" if not specified.
-
-**Example:**
-```xml
-<catch name="error1">
-  <output>Handling the error: </output>
-  <exception/>
-</catch>
-```
-
-### `<exception>`
-Outputs the content of caught exceptions. Must be used inside a `<catch>` block.
-
-**Example:**
-```xml
-<catch name="myerror">
-  <output>Error details: </output>
-  <exception/>
-</catch>
-```
-
-## How It Works
-
-1. **Exception Stack**: All thrown exceptions are added to a global exception stack
-2. **Boundaries**: `<try>` blocks create boundaries in the exception stack
-3. **Name Matching**: `<catch>` blocks look for exceptions with matching names between the current position and the last boundary
-4. **Multiple Catches**: Multiple exceptions with the same name can be caught together
-
-## Examples
-
-### Basic Usage
-```xml
-<try>
-  <throw name="error">
-    <output>An error occurred</output>
-  </throw>
-</try>
-
-<catch name="error">
-  <output>Caught: </output>
-  <exception/>
-</catch>
-```
-
-### Multiple Exception Types
-```xml
-<try>
-  <throw name="warning">
-    <output>Warning: low memory</output>
-  </throw>
-  <throw name="error">
-    <output>Error: file not found</output>
-  </throw>
-</try>
-
-<catch name="warning">
-  <output>Warnings: </output>
-  <exception/>
-</catch>
-
-<catch name="error">
-  <output>Errors: </output>
-  <exception/>
-</catch>
-```
-
-### With Variables
-```xml
-<defvar name="errorCode" value="404"/>
-
-<try>
-  <throw name="httperror">
-    <output>HTTP Error </output>
-    <variable name="errorCode"/>
-  </throw>
-</try>
-
-<catch name="httperror">
-  <exception/>
-</catch>
-```
-
-### Nested Try/Catch
-```xml
-<try>
-  <output>Outer try</output>
-  <try>
-    <throw name="inner">
-      <output>Inner exception</output>
-    </throw>
-  </try>
-  <catch name="inner">
-    <output>Caught in inner: </output>
-    <exception/>
-  </catch>
-</try>
-```
-
-### Default Exception Name
-Both throw and catch default to "exception" if no name is specified:
-
-```xml
-<try>
-  <throw>
-    <output>Default exception</output>
-  </throw>
-</try>
-
-<catch>
-  <exception/>
-</catch>
-```
-
-## Implementation Notes
-
-- Based on the MASK C implementation (`exception.c`, `mask_integrate.c`)
-- Exceptions use a boundary-based scoping system
-- Multiple exceptions with the same name can be caught together
-- Exception content is stored as DOM elements
-- The `<exception>` tag outputs all caught exceptions with the matching name

package/LIBRARIES.md

@@ -1,172 +0,0 @@
-# Dirac Library Ecosystem
-
-## Philosophy
-
-Dirac follows the UNIX philosophy: **composition over complexity**. Complex operations should be implemented as reusable libraries that users can import and use with clean, declarative syntax.
-
-## Library Architecture
-
-### Pattern: JavaScript → Dirac Tags
-
-1. **Implement complexity in `<eval>`** - Use JavaScript's full power for complex algorithms
-2. **Wrap in `<subroutine>`** - Expose as a clean Dirac tag
-3. **Distribute as `.di` files** - Share via `<import>`
-4. **Use like built-in tags** - `<SQRT n="16"/>` not `eval(...)`
-
-### Example: Square Root
-
-**Implementation** (in library):
-```xml
-<subroutine name="SQRT">
-  <eval>
-    const caller = getParams();
-    const n = parseFloat(caller.attributes.n || 0);
-    let x = n, prev;
-    do {
-      prev = x;
-      x = (x + n / x) / 2;
-    } while (Math.abs(x - prev) &lt; 1e-10);
-    console.log(x);
-  </eval>
-</subroutine>
-```
-
-**Usage** (by end user):
-```xml
-<import src="./lib/advanced-math.di"/>
-<SQRT n="16"/>  <!-- Clean, declarative -->
-```
-
-## Current Libraries
-
-### `lib/math.di` - Basic Math
-- `SQUARE` - Square a number
-- `ADD` - Add two numbers  
-- `FACTORIAL` - Calculate factorial
-
-### `lib/fileops.di` - File Operations
-- `LIST_FILES` - List directory contents
-- `COUNT_FILES` - Count files in directory
-
-### `lib/advanced-math.di` - Advanced Math
-- `SQRT` - Square root (Newton's method)
-- `FACTORIAL` - Factorial (recursive)
-- `GCD` - Greatest common divisor
-- `PRIME` - Primality test
-- `STATS` - Statistical analysis
-- `RANDOM` - Random number generation
-
-## Publishing Libraries
-
-### Option 1: GitHub
-```bash
-# Create a dirac-libs repository
-mkdir dirac-libs
-cd dirac-libs
-git init
-# Add your .di library files
-git add lib/
-git commit -m "Add math libraries"
-git push
-```
-
-Users import via URL or local clone.
-
-### Option 2: npm Package
-```json
-{
-  "name": "dirac-stdlib",
-  "version": "1.0.0",
-  "description": "Standard library for Dirac",
-  "main": "index.js",
-  "files": ["lib/**/*.di"],
-  "keywords": ["dirac", "mask", "xml", "dsl"]
-}
-```
-
-Users:
-```bash
-npm install dirac-stdlib
-```
-
-```xml
-<import src="./node_modules/dirac-stdlib/lib/math.di"/>
-```
-
-### Option 3: Central Registry
-Future: Create a Dirac package registry like PyPI/npm specifically for `.di` libraries.
-
-## Best Practices
-
-### 1. Use XML Entities for Operators
-```xml
-<eval>
-  if (x &lt; 5) ...   <!-- Use &lt; not < -->
-  if (x &gt; 10) ...  <!-- Use &gt; not > -->
-  if (x &lt;= 5) ...  <!-- Use &lt;= -->
-</eval>
-```
-
-### 2. Use getParams() for Attributes
-```xml
-<subroutine name="FOO">
-  <eval>
-    const caller = getParams();
-    const x = caller.attributes.x;
-    const children = caller.children;
-  </eval>
-</subroutine>
-```
-
-### 3. Handle Edge Cases
-```javascript
-const n = parseFloat(caller.attributes.n || 0);
-if (n < 0) { console.log('NaN'); return; }
-```
-
-### 4. Document Your Library
-```xml
-<!-- 
-  SQRT - Square Root Calculator
-  
-  Usage: <SQRT n="16"/>
-  Returns: Square root using Newton's method
-  Attributes:
-    - n: Number to find square root of (required)
--->
-<subroutine name="SQRT">
-  ...
-</subroutine>
-```
-
-## Future Libraries
-
-Ideas for community-contributed libraries:
-
-- **dirac-crypto** - Hashing, encryption (`<SHA256>`, `<AES>`)
-- **dirac-http** - HTTP client (`<GET>`, `<POST>`)
-- **dirac-db** - Database operations (`<SQL>`, `<QUERY>`)
-- **dirac-ml** - Machine learning (`<PREDICT>`, `<TRAIN>`)
-- **dirac-dsp** - Signal processing (`<FFT>`, `<FILTER>`)
-- **dirac-viz** - Data visualization (`<CHART>`, `<PLOT>`)
-- **dirac-nlp** - Natural language (`<TOKENIZE>`, `<SENTIMENT>`)
-
-## Contributing
-
-To contribute a library:
-
-1. Create `.di` file with subroutines
-2. Test thoroughly
-3. Document all tags
-4. Submit PR or publish to npm
-5. Add to Dirac wiki/registry
-
-## Philosophy: Why This Works
-
-This approach follows McCarthy's insight about homoiconicity:
-- **Code as data**: Subroutines are XML, same as the code using them
-- **Composition**: Complex tags built from simple ones
-- **Distribution**: Libraries are just more Dirac files
-- **No special cases**: `<SQRT>` works exactly like `<output>`
-
-The entire ecosystem grows organically through composition, not by modifying the interpreter.

package/LLM-VALIDATION.md

@@ -1,128 +0,0 @@
-# LLM Tag Validation
-
-The `<llm>` tag now supports automatic validation and correction of generated Dirac code when using `execute="true"`.
-
-## Attributes
-
-### Execution Mode
-- `execute="true"` - Parse and execute the LLM response as Dirac code (existing feature)
-
-### Tag Validation (New)
-- `validate="true"` - Enable tag validation for LLM-generated code
-- `autocorrect="true"` - Automatically correct similar tag names using semantic matching
-- `max-retries="N"` - Maximum number of retry attempts if validation fails (default: 0)
-
-## How It Works
-
-When `validate="true"` is enabled:
-
-1. **Parse**: LLM response is parsed as Dirac XML
-2. **Validate**: Each tag is checked against available subroutines
-   - Verifies tag names exist
-   - Checks required parameters are present
-   - Warns about unknown attributes
-3. **Semantic Matching**: If a tag doesn't exist, finds the closest match using embeddings
-4. **Auto-correct**: If `autocorrect="true"` and similarity >= 0.75, replaces tag with best match
-5. **Retry**: If validation fails and `max-retries > 0`, sends error feedback to LLM and retries
-6. **Execute**: Once validation passes, executes the (possibly corrected) code
-
-## Examples
-
-### Basic Validation
-
-```xml
-<dirac>
-  <subroutine name="greet" param-name="string:required">
-    <output>Hello, <variable name="name" />!</output>
-  </subroutine>
-  
-  <llm execute="true" validate="true">
-    Greet Alice
-  </llm>
-</dirac>
-```
-
-If the LLM generates `<greeting name="Alice" />` instead of `<greet name="Alice" />`, validation will fail with an error.
-
-### With Auto-correction
-
-```xml
-<dirac>
-  <subroutine name="greet" param-name="string:required">
-    <output>Hello, <variable name="name" />!</output>
-  </subroutine>
-  
-  <llm execute="true" validate="true" autocorrect="true">
-    Greet Alice
-  </llm>
-</dirac>
-```
-
-If the LLM generates `<greeting name="Alice" />`, and `greeting` is semantically similar to `greet` (similarity >= 0.75), it will be auto-corrected to `<greet name="Alice" />`.
-
-### With Retry
-
-```xml
-<dirac>
-  <subroutine name="calculate" param-expression="string:required">
-    <eval><variable name="expression" /></eval>
-  </subroutine>
-  
-  <llm execute="true" validate="true" max-retries="3">
-    Calculate 2 + 2
-  </llm>
-</dirac>
-```
-
-If validation fails:
-1. LLM receives feedback: "Your previous response had the following errors: <compute>: Missing required parameter: expression"
-2. LLM generates a new response
-3. Process repeats up to 3 times until validation passes
-
-### Combined Approach
-
-```xml
-<llm execute="true" validate="true" autocorrect="true" max-retries="2">
-  Generate a greeting for Bob
-</llm>
-```
-
-This combines auto-correction with retry:
-- First tries to auto-correct similar tag names
-- If that doesn't fix all errors, retries with LLM feedback
-- Maximum 2 retry attempts
-
-## Error Messages
-
-Validation can detect:
-
-- **Missing tags**: `Tag <xyz> does not exist and no similar tag was found.`
-- **Similar tags**: `Tag <greeting> does not exist. Did you mean <greet>? (similarity: 0.85)`
-- **Missing parameters**: `<greet>: Missing required parameter: name`
-- **Unknown attributes**: `<greet>: Unknown attribute: person`
-
-## Requirements
-
-- Requires embedding server for semantic matching (Ollama with embeddinggemma model)
-- Configure in `config.yml`:
-  ```yaml
-  embeddingServer:
-    host: localhost
-    port: 11435
-  ```
-
-## Performance Notes
-
-- Validation adds latency due to embedding calls
-- Each tag requires an embedding API call
-- Consider using `validate="true"` only when necessary
-- Auto-correction is faster than retries
-
-## Best Practices
-
-1. **Start without validation** for simple prompts
-2. **Add validation** when LLM frequently generates incorrect tags
-3. **Use autocorrect** for typos and similar names
-4. **Use retry** for more complex validation errors
-5. **Limit retries** to 2-3 to avoid excessive API calls
-6. **Monitor debug output** with `DIRAC_DEBUG=1` to see validation details