dirac-lang 0.1.2

package/examples/sample-library/lib/index.di

@@ -0,0 +1,65 @@
+<dirac>
+
+<subroutine name="STR_UPPERCASE">
+  <eval>
+    const caller = getParams();
+    const text = caller.attributes.text || '';
+    console.log(text.toUpperCase());
+  </eval>
+</subroutine>
+
+<subroutine name="STR_LOWERCASE">
+  <eval>
+    const caller = getParams();
+    const text = caller.attributes.text || '';
+    console.log(text.toLowerCase());
+  </eval>
+</subroutine>
+
+<subroutine name="STR_TRIM">
+  <eval>
+    const caller = getParams();
+    const text = caller.attributes.text || '';
+    console.log(text.trim());
+  </eval>
+</subroutine>
+
+<subroutine name="STR_SUBSTRING">
+  <eval>
+    const caller = getParams();
+    const text = caller.attributes.text || '';
+    const start = parseInt(caller.attributes.start || 0);
+    const end = caller.attributes.end ? parseInt(caller.attributes.end) : undefined;
+    console.log(text.substring(start, end));
+  </eval>
+</subroutine>
+
+<subroutine name="STR_REPLACE">
+  <eval>
+    const caller = getParams();
+    const text = caller.attributes.text || '';
+    const find = caller.attributes.find || '';
+    const replace = caller.attributes.replace || '';
+    console.log(text.replace(new RegExp(find, 'g'), replace));
+  </eval>
+</subroutine>
+
+<subroutine name="STR_SPLIT">
+  <eval>
+    const caller = getParams();
+    const text = caller.attributes.text || '';
+    const delimiter = caller.attributes.delimiter || ',';
+    const parts = text.split(delimiter);
+    console.log(JSON.stringify(parts));
+  </eval>
+</subroutine>
+
+<subroutine name="STR_LENGTH">
+  <eval>
+    const caller = getParams();
+    const text = caller.attributes.text || '';
+    console.log(text.length);
+  </eval>
+</subroutine>
+
+</dirac>

package/examples/sample-library/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "dirac-string",
+  "version": "1.0.0",
+  "description": "String manipulation library for Dirac",
+  "main": "lib/index.di",
+  "scripts": {
+    "test": "dirac tests/test.di"
+  },
+  "keywords": [
+    "dirac",
+    "string",
+    "text",
+    "manipulation"
+  ],
+  "author": "Dirac Community",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dirac-lang/dirac-string"
+  },
+  "bugs": {
+    "url": "https://github.com/dirac-lang/dirac-string/issues"
+  },
+  "homepage": "https://github.com/dirac-lang/dirac-string#readme",
+  "dirac": {
+    "version": ">=0.1.0",
+    "exports": {
+      "main": "lib/index.di"
+    }
+  }
+}

package/examples/seamless.di

@@ -0,0 +1,45 @@
+<!-- Seamless LLM-Dirac Interleaving - THE PHILOSOPHICAL DEMO -->
+<dirac>
+  <output>Seamless Execution Demo&#10;&#10;</output>
+  
+  <!-- Define a subroutine that lists files -->
+  <subroutine name="LIST_FILES">
+    <eval name="files">
+      return fs.readdirSync('examples')
+        .filter(f => f.endsWith('.di'))
+        .slice(0, 5)
+        .join(', ');
+    </eval>
+    <output>Files found: ${files}&#10;</output>
+  </subroutine>
+  
+  <!-- Define a subroutine that counts something -->
+  <subroutine name="COUNT_FILES">
+    <eval name="count">
+      return fs.readdirSync('examples').filter(f => f.endsWith('.di')).length;
+    </eval>
+    <output>Total count: ${count}&#10;</output>
+  </subroutine>
+  
+  <!-- Now the magic: LLM returns Dirac tags that get executed immediately -->
+  <output>Asking LLM to analyze and respond with executable tags...&#10;&#10;</output>
+  
+  <LLM execute="true" maxTokens="200">
+    You are analyzing a project directory. 
+    
+    Respond by calling ONLY these Dirac subroutines (XML tags):
+    - &lt;LIST_FILES /&gt; - lists example files
+    - &lt;COUNT_FILES /&gt; - counts total files
+    
+    Your response should be pure XML like:
+    &lt;dirac&gt;
+      &lt;output&gt;Analysis:&#10;&lt;/output&gt;
+      &lt;LIST_FILES /&gt;
+      &lt;COUNT_FILES /&gt;
+    &lt;/dirac&gt;
+    
+    Return ONLY the XML, no explanation.
+  </LLM>
+  
+  <output>&#10;Done!&#10;</output>
+</dirac>

package/examples/shell-test.bk

@@ -0,0 +1,10 @@
+<listfiles|
+  |parameters select=@dir>
+  |system>
+    ls -la |variable name=dir>
+    echo "Files in |variable name=dir>:"
+    find |variable name=dir> -name "*.bk"
+
+|output>Listing files in directory:
+|output>
+|listfiles dir=examples>

package/examples/simple-import.di

@@ -0,0 +1,13 @@
+#!/usr/bin/env dirac
+<!-- Simple import test -->
+<dirac>
+  <import src="./lib/math.di" />
+  
+  <defvar name="x" value="7" />
+  <output>Testing SQUARE with x=${x}&#10;</output>
+  
+  <eval name="result">return 7 * 7;</eval>
+  <output>Direct calc: ${result}&#10;</output>
+  
+  <call name="SQUARE" />
+</dirac>

package/examples/simple-recursive.di

@@ -0,0 +1,26 @@
+<!-- Simple Recursive Demo - LISP Style -->
+<dirac>
+  <output>Simple Recursion Demo&#10;&#10;</output>
+  
+  <!-- Subroutine that calculates something -->
+  <subroutine name="CALC">
+    <eval name="result">return 5 * 5;</eval>
+    <output>Calculated: ${result}&#10;</output>
+  </subroutine>
+  
+  <!-- Subroutine with nested LLM call -->
+  <subroutine name="NESTED">
+    <output>Entering nested call...&#10;</output>
+    <LLM execute="true" maxTokens="50">
+      &lt;dirac&gt;&lt;output&gt;From nested LLM!&#10;&lt;/output&gt;&lt;/dirac&gt;
+    </LLM>
+  </subroutine>
+  
+  <!-- Start with direct LLM execution -->
+  <output>Starting...&#10;</output>
+  <LLM execute="true" maxTokens="50">
+    Copy this EXACTLY: &lt;dirac&gt;&lt;CALC /&gt;&lt;NESTED /&gt;&lt;/dirac&gt;
+  </LLM>
+  
+  <output>Done!&#10;</output>
+</dirac>

package/examples/story-builder.di

@@ -0,0 +1,45 @@
+<!-- Story Builder - Loop with LLM -->
+<dirac>
+  <defvar name="character" value="a curious robot" />
+  <defvar name="setting" value="abandoned space station" />
+  
+  <output>Creating a story about ${character} in ${setting}...&#10;&#10;</output>
+  
+  <!-- Generate the opening -->
+  <LLM output="opening" maxTokens="150">
+    Write the opening paragraph of a story about ${character} in ${setting}.
+    End with a cliffhanger.
+  </LLM>
+  <output>${opening}&#10;&#10;</output>
+  
+  <!-- Generate 3 story beats -->
+  <defvar name="context" value="${opening}" />
+  
+  <loop var="i" from="1" to="3">
+    <output>--- Part ${i} ---&#10;</output>
+    
+    <LLM output="nextPart" maxTokens="150">
+      Continue this story with the next paragraph:
+      
+      ${context}
+      
+      Make it exciting and end with a cliffhanger.
+    </LLM>
+    
+    <output>${nextPart}&#10;&#10;</output>
+    
+    <!-- Update context for next iteration -->
+    <assign name="context" value="${context} ${nextPart}" />
+  </loop>
+  
+  <!-- Generate conclusion -->
+  <output>--- Conclusion ---&#10;</output>
+  <LLM output="ending" maxTokens="150">
+    Write a satisfying conclusion to this story:
+    
+    ${context}
+    
+    Wrap up the plot in 2-3 sentences.
+  </LLM>
+  <output>${ending}&#10;</output>
+</dirac>

package/examples/subroutine.di

@@ -0,0 +1,23 @@
+<!-- Subroutine and parameters test -->
+<dirac>
+  <subroutine name="greet">
+    <parameters>
+      <variable name="name" passby="value" />
+    </parameters>
+    <output>Hello, ${name}!</output>
+  </subroutine>
+  
+  <call name="greet">
+    <parameters>
+      <variable value="Alice" />
+    </parameters>
+  </call>
+  
+  <output> </output>
+  
+  <call name="greet">
+    <parameters>
+      <variable value="Bob" />
+    </parameters>
+  </call>
+</dirac>

package/examples/system-llm.di

@@ -0,0 +1,21 @@
+<dirac>
+  <!-- Get file listing -->
+  <defvar name="dir">examples</defvar>
+  <output>Getting file listing from ${dir}...</output>
+  <output>&#10;</output>
+  
+  <llm noextra="true" output="fileList">
+    <system>ls -lh ${dir} | head -10</system>
+    
+    Above is a directory listing. Please analyze it and tell me:
+    1. How many files are shown?
+    2. What is the total size of the largest file?
+    3. What file types do you see (by extension)?
+    
+    Please be concise.
+  </llm>
+  
+  <output>&#10;&#10;LLM Analysis:</output>
+  <output>&#10;</output>
+  <output><variable name="fileList"/></output>
+</dirac>

package/examples/system-simple.di

@@ -0,0 +1,3 @@
+<dirac>
+  <system>echo "Hello from system"</system>
+</dirac>

package/examples/system-test.di

@@ -0,0 +1,13 @@
+<dirac>
+  <!-- Test 1: Simple command -->
+  <output>Current directory:</output>
+  <output>&#10;</output>
+  <system>pwd</system>
+  <output>&#10;</output>
+  
+  <!-- Test 2: Command with variable substitution -->
+  <defvar name="dir">examples</defvar>
+  <output>Files in ${dir}:</output>
+  <output>&#10;</output>
+  <system>ls -la ${dir} | head -5</system>
+</dirac>

package/examples/task-assistant.di

@@ -0,0 +1,27 @@
+<!-- Task Assistant - LLM breaks down and executes tasks -->
+<dirac>
+  <defvar name="task" value="organize a birthday party" />
+  
+  <output>Task: ${task}&#10;&#10;</output>
+  
+  <!-- Ask LLM to break down the task -->
+  <output>Breaking down the task...&#10;</output>
+  <LLM output="steps" maxTokens="300">
+    Break down "${task}" into 3-5 concrete action steps.
+    Return ONLY a numbered list, one step per line.
+    Keep each step brief and actionable.
+  </LLM>
+  
+  <output>&#10;Steps to complete:&#10;${steps}&#10;&#10;</output>
+  
+  <!-- Now get LLM to provide tips for the first step -->
+  <output>Getting tips for step 1...&#10;</output>
+  <LLM output="tips" maxTokens="200">
+    For the first step in this list:
+    ${steps}
+    
+    Provide 2-3 quick practical tips. Be concise.
+  </LLM>
+  
+  <output>&#10;Tips:&#10;${tips}&#10;</output>
+</dirac>

package/examples/test-parameters.di

@@ -0,0 +1,50 @@
+#!/usr/bin/env dirac
+<dirac>
+  <!-- Test 1: parameters select="*" - access child elements -->
+  <subroutine name="GREET">
+    <output>Hello, </output>
+    <parameters select="*"/>
+    <output>!</output>
+  </subroutine>
+
+  <output>Test 1 - Child elements:</output>
+  <GREET>
+    <output>Alice</output>
+  </GREET>
+  <output>&#10;</output>
+
+  <!-- Test 2: parameters select="@attr" - access specific attribute -->
+  <subroutine name="SQUARE">
+    <output>x=</output>
+    <parameters select="@x"/>
+    <output> squared = ?</output>
+  </subroutine>
+
+  <output>Test 2 - Attribute access: </output>
+  <SQUARE x="5"/>
+  <output>&#10;</output>
+
+  <!-- Test 3: parameters select="@*" - access all attributes -->
+  <subroutine name="SHOW_ATTRS">
+    <output>Attributes: </output>
+    <parameters select="@*"/>
+    <output>&#10;</output>
+  </subroutine>
+
+  <output>Test 3 - All attributes:</output>
+  <SHOW_ATTRS name="test" value="123" color="red"/>
+
+  <!-- Test 4: Multiple child elements -->
+  <subroutine name="LIST">
+    <output>Items: </output>
+    <parameters select="*"/>
+    <output>&#10;</output>
+  </subroutine>
+
+  <output>Test 4 - Multiple children: </output>
+  <LIST>
+    <output>Apple, </output>
+    <output>Banana, </output>
+    <output>Orange</output>
+  </LIST>
+</dirac>

package/examples/two-styles.di

@@ -0,0 +1,28 @@
+<!-- Comparing Two Styles of LLM-Code Execution -->
+<dirac>
+  <output>=== Style Comparison Demo ===&#10;&#10;</output>
+  
+  <!-- STYLE 1: EXPLICIT (Clear, Debuggable) -->
+  <output>--- Explicit Style (Clarity) ---&#10;</output>
+  <LLM output="generatedCode" maxTokens="100">
+    Return ONLY this XML, nothing else:
+    &lt;dirac&gt;&lt;eval name="result"&gt;return 10 + 20;&lt;/eval&gt;&lt;output&gt;Sum: ${result}&lt;/output&gt;&lt;/dirac&gt;
+  </LLM>
+  
+  <output>Generated code:&#10;${generatedCode}&#10;&#10;</output>
+  <output>Executing...&#10;</output>
+  <execute source="generatedCode" />
+  <output>&#10;&#10;</output>
+  
+  <!-- STYLE 2: LISP (Seamless, Direct) -->
+  <output>--- LISP Style (Seamless) ---&#10;</output>
+  <LLM execute="true" maxTokens="100">
+    Return ONLY this XML, nothing else:
+    &lt;dirac&gt;&lt;eval name="result"&gt;return 30 + 40;&lt;/eval&gt;&lt;output&gt;Sum: ${result}&lt;/output&gt;&lt;/dirac&gt;
+  </LLM>
+  <output>&#10;</output>
+  
+  <output>--- When to Use Each ---&#10;</output>
+  <output>Explicit: Debugging, inspection, conditional execution&#10;</output>
+  <output>LISP: Real-time interaction, streaming, recursive calls&#10;</output>
+</dirac>

package/examples/var-debug.di

@@ -0,0 +1,6 @@
+<dirac>
+  <defvar name="test">Hello World</defvar>
+  <output>Start: </output>
+  <variable name="test"/>
+  <output> :End</output>
+</dirac>

package/examples/var-inline.di

@@ -0,0 +1,4 @@
+<dirac>
+  <defvar name="user">World</defvar>
+  <output>Hello, <variable name="user"/>!</output>
+</dirac>

package/examples/var-test2.di

@@ -0,0 +1,6 @@
+<dirac>
+  <defvar name="name">Alice</defvar>
+  <output>Before</output>
+  <variable name="name"/>
+  <output>After</output>
+</dirac>

package/examples/variable-simple.di

@@ -0,0 +1,16 @@
+<dirac>
+  <!-- Test 1: Simple text variable -->
+  <defvar name="name">Alice</defvar>
+  <output>Hello, <variable name="name"/>!</output>
+  <output>&#10;</output>
+  
+  <!-- Test 2: Using ${} substitution -->
+  <output>Using substitution: Hello, ${name}!</output>
+  <output>&#10;</output>
+  
+  <!-- Test 3: Number variable -->
+  <defvar name="x">5</defvar>
+  <defvar name="y">3</defvar>
+  <output>x = <variable name="x"/>, y = <variable name="y"/></output>
+  <output>&#10;</output>
+</dirac>

package/examples/variable-test.di

@@ -0,0 +1,22 @@
+<dirac>
+  <!-- Test 1: Simple text variable -->
+  <defvar name="name">Alice</defvar>
+  <output>Hello, <variable name="name"/>!</output>
+  <output>&#10;</output>
+  
+  <!-- Test 2: Using ${} substitution -->
+  <output>Using substitution: Hello, ${name}!</output>
+  <output>&#10;</output>
+  
+  <!-- Test 3: Variable with XML code as string -->
+  <defvar name="template">&lt;output&gt;Template says: Hello, &lt;variable name="name"/&gt;!&lt;/output&gt;</defvar>
+  
+  <output>Raw template: </output>
+  <variable name="template"/>
+  <output>&#10;</output>
+  
+  <!-- Test 4: Execute the template -->
+  <output>Executed: </output>
+  <execute source="template"/>
+  <output>&#10;</output>
+</dirac>

package/filePath

@@ -0,0 +1 @@
+fileContent

package/greeting.txt

@@ -0,0 +1 @@
+hello world

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "dirac-lang",
+  "version": "0.1.2",
+  "description": "LLM-Augmented Declarative Execution",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "dirac": "dist/cli.js"
+  },
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "tsup src/index.ts src/cli.ts --format esm --dts --clean",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "llm",
+    "declarative",
+    "dirac",
+    "bra-ket"
+  ],
+  "author": "Zhi Wang",
+  "license": "MIT",
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.30.1",
+    "dotenv": "^17.2.3",
+    "fast-xml-parser": "^4.3.5",
+    "js-yaml": "^4.1.1",
+    "mongodb": "^7.0.0",
+    "openai": "^6.16.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.11.0",
+    "tsup": "^8.0.1",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.0"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+
+/**
+ * Dirac CLI
+ */
+
+import 'dotenv/config';
+import fs from 'fs';
+import yaml from 'js-yaml';
+import { resolve, extname } from 'path';
+import { execute } from './index.js';
+import { BraKetParser } from './runtime/braket-parser.js';
+
+async function main() {
+  const args = process.argv.slice(2);
+  
+  if (args.length === 0) {
+    console.error('Usage: dirac <file.di|file.bk>');
+    console.error('');
+    console.error('File formats:');
+    console.error('  .di               XML notation (verbose)');
+    console.error('  .bk               Bra-ket notation (compact)');
+    console.error('');
+    console.error('Options:');
+    console.error('  --debug           Enable debug output');
+    console.error('  --emit-xml        Output intermediate XML (for .bk files)');
+    console.error('  --model <name>    Set default LLM model');
+    console.error('  --max-llm <n>     Maximum LLM calls (default: 100)');
+    console.error('  --max-depth <n>   Maximum recursion depth (default: 50)');
+    process.exit(1);
+  }
+  
+  // Parse options
+  const config: any = {};
+  let filePath: string | undefined;
+  let emitXml = false;
+  let configFile: string | undefined;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '--debug') {
+      config.debug = true;
+    } else if (arg === '--emit-xml') {
+      emitXml = true;
+    } else if (arg === '--model' && i + 1 < args.length) {
+      config.model = args[++i];
+    } else if (arg === '--provider' && i + 1 < args.length) {
+      config.llmProvider = args[++i];
+    } else if ((arg === '-f' || arg === '--config') && i + 1 < args.length) {
+      configFile = args[++i];
+    } else if (arg === '--max-llm' && i + 1 < args.length) {
+      config.maxLLMCalls = parseInt(args[++i], 10);
+    } else if (arg === '--max-depth' && i + 1 < args.length) {
+      config.maxDepth = parseInt(args[++i], 10);
+    } else if (!arg.startsWith('--')) {
+      filePath = arg;
+    }
+  }
+
+  // Load config from YAML file if specified
+  if (configFile) {
+    try {
+      const loadedConfig = yaml.load(fs.readFileSync(resolve(configFile), 'utf8')) || {};
+      Object.assign(config, loadedConfig);
+    } catch (err) {
+      console.error('Failed to load config file:', err);
+      process.exit(1);
+    }
+  }
+  
+  if (!filePath) {
+    console.error('Error: No input file specified');
+    process.exit(1);
+  }
+  
+  try {
+    const fullPath = resolve(process.cwd(), filePath);
+    let source = fs.readFileSync(fullPath, 'utf-8');
+    const ext = extname(fullPath);
+    
+    // Convert bra-ket notation to XML if needed
+    if (ext === '.bk') {
+      if (config.debug) {
+        console.error(`[Dirac] Compiling bra-ket notation to XML`);
+      }
+      
+      const braketParser = new BraKetParser();
+      const xml = braketParser.parse(source);
+      
+      if (emitXml) {
+        console.log(xml);
+        return;
+      }
+      
+      source = xml;
+    }
+    
+    if (config.debug) {
+      console.error(`[Dirac] Executing ${fullPath}`);
+    }
+    
+    // Pass file path to config for import resolution
+    config.filePath = fullPath;
+    
+    const result = await execute(source, config);
+    process.stdout.write(result);
+    
+  } catch (error) {
+    console.error('Error:', error instanceof Error ? error.message : String(error));
+    if (config.debug && error instanceof Error && error.stack) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+main();