dirac-lang 0.1.2

package/NAMESPACES.md

@@ -0,0 +1,366 @@
+# Tag Namespace Conflict Resolution
+
+## The Problem
+
+```xml
+<!-- Both dirac-http and dirac-rest define GET -->
+<import src="./node_modules/dirac-http/lib/index.di"/>
+<import src="./node_modules/dirac-rest/lib/index.di"/>
+
+<GET url="..."/>  <!-- Which GET? Conflict! -->
+```
+
+## Solution Options
+
+### Option 1: Library Prefixes (Convention)
+
+Libraries use consistent prefixes:
+
+```xml
+<!-- dirac-http uses HTTP_ prefix -->
+<subroutine name="HTTP_GET">...</subroutine>
+<subroutine name="HTTP_POST">...</subroutine>
+
+<!-- dirac-db uses DB_ prefix -->
+<subroutine name="DB_QUERY">...</subroutine>
+<subroutine name="DB_INSERT">...</subroutine>
+```
+
+**Pros:**
+- Simple, works today
+- No interpreter changes needed
+- Clear ownership: `HTTP_GET`, `DB_QUERY`
+- Searchable: "HTTP_*" shows all HTTP functions
+
+**Cons:**
+- Verbose: `<HTTP_GET/>` vs `<GET/>`
+- Convention-based (not enforced)
+
+**Recommendation: Use this NOW** ✅
+
+### Option 2: Import Aliases (Future Feature)
+
+```xml
+<!-- Import with alias -->
+<import src="./node_modules/dirac-http/lib/index.di" as="http"/>
+<import src="./node_modules/dirac-rest/lib/index.di" as="rest"/>
+
+<!-- Use with alias -->
+<http:GET url="..."/>
+<rest:GET endpoint="..."/>
+```
+
+**Pros:**
+- Clean syntax
+- Explicit disambiguation
+- User controls naming
+
+**Cons:**
+- Requires interpreter changes
+- XML namespace complexity
+
+### Option 3: Scoped Imports (Future Feature)
+
+```xml
+<!-- Import specific tags -->
+<import src="dirac-http" names="GET as HTTP_GET, POST as HTTP_POST"/>
+<import src="dirac-rest" names="GET as REST_GET"/>
+
+<HTTP_GET url="..."/>
+<REST_GET endpoint="..."/>
+```
+
+**Pros:**
+- Explicit control
+- No unused tags loaded
+- User-defined aliases
+
+**Cons:**
+- Verbose import statements
+- Requires interpreter support
+
+### Option 4: Implicit Namespacing (Future Feature)
+
+```xml
+<import src="dirac-http" scope="http"/>
+
+<!-- Tags automatically prefixed in scope -->
+<http>
+  <GET url="..."/>    <!-- Resolves to http:GET -->
+  <POST url="..."/>   <!-- Resolves to http:POST -->
+</http>
+```
+
+**Pros:**
+- Clean usage
+- Scoped context
+
+**Cons:**
+- Complex to implement
+- Unusual XML pattern
+
+### Option 5: Last Import Wins (Simple)
+
+```xml
+<import src="dirac-http/lib/index.di"/>
+<import src="dirac-rest/lib/index.di"/>
+
+<GET url="..."/>  <!-- Uses dirac-rest's GET (last imported) -->
+```
+
+**Pros:**
+- No changes needed
+- Works today
+
+**Cons:**
+- Unpredictable behavior
+- Hidden conflicts
+- Debugging nightmare
+
+❌ **Not recommended**
+
+## Recommended Approach
+
+### Phase 1: Convention (Now)
+
+**Establish naming conventions:**
+
+```
+Library Prefix Convention:
+- dirac-http    → HTTP_*     (HTTP_GET, HTTP_POST)
+- dirac-db      → DB_*       (DB_QUERY, DB_CONNECT)
+- dirac-crypto  → CRYPTO_*   (CRYPTO_SHA256, CRYPTO_AES)
+- dirac-string  → STR_*      (STR_UPPER, STR_LOWER)
+- dirac-math    → MATH_*     (MATH_SQRT, MATH_SIN)
+- dirac-json    → JSON_*     (JSON_PARSE, JSON_STRINGIFY)
+- dirac-xml     → XML_*      (XML_PARSE, XML_QUERY)
+```
+
+**Document in COMMUNITY.md:**
+```markdown
+## Naming Convention
+
+All library tags MUST use a prefix based on the library name:
+
+- Package name: `dirac-[domain]`
+- Tag prefix: `[DOMAIN]_`
+- Example: `dirac-http` → `HTTP_GET`, `HTTP_POST`
+
+This prevents naming conflicts between libraries.
+```
+
+**Enforce in template:**
+```xml
+<!-- lib/index.di -->
+<dirac>
+
+<!-- Replace MYLIB with your library name (uppercase) -->
+<subroutine name="MYLIB_FUNCTION1">
+  ...
+</subroutine>
+
+<subroutine name="MYLIB_FUNCTION2">
+  ...
+</subroutine>
+
+</dirac>
+```
+
+### Phase 2: Import Aliases (Future)
+
+Add `as` attribute to `<import>`:
+
+```xml
+<import src="./node_modules/dirac-http/lib/index.di" as="http"/>
+
+<!-- Interpreter translates http:GET to HTTP_GET internally -->
+<http:GET url="..."/>
+```
+
+**Implementation:**
+1. Parse `as` attribute in import tag
+2. Store alias → library mapping in session
+3. When resolving tags, check if tag contains `:`
+4. If yes, look up alias and resolve to prefixed name
+5. Fall back to direct name if no alias
+
+### Phase 3: Module System (Later)
+
+Full module system with explicit imports:
+
+```xml
+<module>
+  <import from="dirac-http">
+    <use name="GET" as="fetch"/>
+    <use name="POST"/>
+  </import>
+  
+  <import from="dirac-db">
+    <use name="QUERY"/>
+  </import>
+</module>
+
+<fetch url="..."/>        <!-- dirac-http's GET -->
+<POST url="..."/>         <!-- dirac-http's POST -->
+<QUERY sql="..."/>        <!-- dirac-db's QUERY -->
+```
+
+## Conflict Detection Tool
+
+Create a tool to check for conflicts:
+
+```bash
+dirac check-conflicts
+
+# Output:
+# Warning: Tag 'GET' defined in multiple libraries:
+#   - dirac-http (HTTP_GET)
+#   - dirac-rest (REST_GET)
+# Recommendation: Use prefixed names
+```
+
+## Real-World Examples
+
+### Example 1: HTTP + Database
+
+```xml
+<import src="dirac-http"/>
+<import src="dirac-db"/>
+
+<!-- Clear ownership with prefixes -->
+<HTTP_GET url="https://api.example.com/users"/>
+<DB_INSERT table="users" data="..."/>
+```
+
+### Example 2: Multiple String Libraries
+
+```xml
+<import src="dirac-string"/>
+<import src="dirac-regex"/>
+
+<!-- No conflict -->
+<STR_UPPER text="hello"/>
+<REGEX_MATCH pattern="[0-9]+" text="abc123"/>
+```
+
+### Example 3: Conflict Scenario (BAD)
+
+```xml
+<!-- Both define PARSE -->
+<import src="dirac-json"/>
+<import src="dirac-xml"/>
+
+<PARSE data="..."/>  <!-- Which one? -->
+```
+
+**Solution:**
+```xml
+<import src="dirac-json"/>
+<import src="dirac-xml"/>
+
+<JSON_PARSE data='{"key":"value"}'/>
+<XML_PARSE data="<root>...</root>"/>
+```
+
+## Standard Library Naming
+
+Core Dirac tags (built-in) have no prefix:
+- `<output>` - Built-in
+- `<eval>` - Built-in
+- `<if>` - Built-in
+- `<loop>` - Built-in
+
+All library tags MUST have prefixes:
+- `<HTTP_GET>` - From dirac-http
+- `<DB_QUERY>` - From dirac-db
+
+This makes it clear what's built-in vs library.
+
+## Migration Path
+
+For libraries already published without prefixes:
+
+1. **Deprecation warning:**
+```xml
+<subroutine name="GET">
+  <output>⚠️  Warning: GET is deprecated. Use HTTP_GET instead.</output>
+  <!-- ... actual implementation ... -->
+</subroutine>
+```
+
+2. **Alias old names:**
+```xml
+<!-- New prefixed name -->
+<subroutine name="HTTP_GET">
+  ...
+</subroutine>
+
+<!-- Old name calls new name -->
+<subroutine name="GET">
+  <HTTP_GET>
+    <parameters select="*"/>
+  </HTTP_GET>
+</subroutine>
+```
+
+3. **Semver major version:**
+- v1.x.x: `GET` (old, no prefix)
+- v2.0.0: `HTTP_GET` (new, with prefix)
+- v2.0.0: `GET` marked deprecated but still works
+
+## Validation Tool
+
+Add to `create-library.sh`:
+
+```bash
+# Check that all subroutines use proper prefix
+LIBNAME_UPPER=$(echo "$LIBNAME" | tr '[:lower:]' '[:upper:]')
+echo "Remember: All tags should be prefixed with ${LIBNAME_UPPER}_"
+echo "Example: ${LIBNAME_UPPER}_FUNCTION"
+```
+
+Add lint command:
+```bash
+dirac lint lib/index.di
+
+# Checks:
+# ✓ All subroutine names use library prefix
+# ✗ Found unprefixed subroutine: GET
+#   Should be: HTTP_GET
+```
+
+## Documentation
+
+Update all docs to show prefixed names:
+
+**Good:**
+```xml
+<import src="dirac-http"/>
+<HTTP_GET url="https://example.com"/>
+```
+
+**Bad:**
+```xml
+<import src="dirac-http"/>
+<GET url="https://example.com"/>  <!-- Don't do this! -->
+```
+
+## Summary
+
+**Now (Phase 1):**
+- ✅ Use prefix convention: `LIBNAME_FUNCTION`
+- ✅ Document in community guidelines
+- ✅ Update library template
+- ✅ Update all examples
+
+**Later (Phase 2):**
+- Add `as` attribute to imports
+- Support `prefix:TAG` syntax
+- Backward compatible
+
+**Future (Phase 3):**
+- Full module system
+- Explicit named imports
+- Conflict detection tools
+
+This gives us a working solution today while leaving room for syntactic sugar later.

package/PROMOTION.md

@@ -0,0 +1,257 @@
+# Dirac: The Agentic Recursive Language for LLM-Augmented Computing
+
+## What is Dirac?
+
+Dirac is a **declarative execution language** specifically designed for the AI era, where large language models (LLMs) are not just tools, but active participants in code execution. It's named after physicist Paul Dirac and his bra-ket notation, reflecting its dual nature: bridging human-readable declarations with machine execution.
+
+## The Recursive LLM Paradigm
+
+Traditional programming languages separate code from AI. You write code, then separately call an LLM API. Dirac **eliminates this boundary**:
+
+```xml
+<llm execute="true">
+  Create a Dirac program that lists all .txt files, 
+  reads the first one, and summarizes it.
+</llm>
+```
+
+The LLM doesn't just respond—it **generates Dirac code that immediately executes**. The generated code can itself call LLMs, creating a **recursive chain** where AI and execution seamlessly interweave.
+
+## Agentic by Design
+
+Dirac treats LLMs as **autonomous agents** that can:
+
+- **Generate executable code** on-the-fly
+- **Make decisions** based on runtime data
+- **Invoke system commands** and process their output
+- **Call themselves recursively** to break down complex tasks
+- **Import and compose libraries** for modular problem-solving
+
+Example of an agentic workflow:
+
+```xml
+<llm output="fileList">
+  <system>ls -la</system>
+  Analyze these files and create Dirac code to process them.
+</llm>
+
+<execute source="fileList"/>  <!-- LLM-generated code runs here -->
+```
+
+
+## Neural-Symbolic AI: Bridging Symbolic Reasoning and Neural Networks
+
+Dirac is not just agentic—it’s also a natural fit for **neural-symbolic AI**. Its bra/ket-inspired knowledge representation allows you to express and connect symbolic logic and neural computation in a unified language.
+
+**Example: Aristotle’s Syllogism**
+
+- All humans are mortal.
+- Socrates is a human.
+- Therefore, Socrates is mortal.
+
+In Dirac’s bra/ket notation, this can be represented as:
+- `|mortal⟩⟨human|` (all humans are mortal)
+- `|human⟩⟨Socrates|` (Socrates is a human)
+
+When you ask `|Socrates⟩`, chaining these together yields `|mortal⟩`.
+
+From a **neural network** perspective, these bra/ket pairs are like matrices (or tensors), and the input `|Socrates⟩` is a vector. The network applies transformations—possibly nonlinear—to produce an output.
+
+From a **symbolic AI** perspective, these are like Dirac subroutines:
+```xml
+<subroutine name="human">
+  <mortal/>
+</subroutine>
+```
+Or, in Dirac’s shorthand:
+```
+<human|
+  |mortal>
+```
+
+**Dirac bridges these worlds:**  
+- As a symbolic language, it lets you define and chain logical relationships explicitly.
+- As a bridge to neural networks, it enables LLMs and other neural models to participate in these chains, providing generative, nonlinear reasoning when needed.
+
+Dirac is the missing link for building systems where **symbolic structure and neural intelligence work together**—making it ideal for the next generation of explainable, powerful AI.
+
+The LLM sees real system state, generates appropriate code, and that code executes—all in one flow.
+
+## Key Features
+
+### 1. **Seamless LLM Integration**
+LLMs are first-class citizens, not afterthoughts:
+```xml
+<llm>What is 2+2?</llm>  <!-- Direct output -->
+<llm output="result">Calculate 2+2</llm>  <!-- Store in variable -->
+<llm execute="true">Write a loop</llm>  <!-- Generate and execute code -->
+```
+
+### 2. **Declarative Simplicity**
+Express **what** you want, not **how** to do it:
+```xml
+<system>df -h</system>  <!-- Run shell command -->
+<llm>Summarize the disk usage above</llm>
+```
+
+### 3. **Recursive Composition**
+Programs can generate programs:
+```xml
+<subroutine name="analyze">
+  <llm execute="true">
+    Generate code to analyze <variable name="data"/>
+  </llm>
+</subroutine>
+```
+
+### 4. **Bra-Ket Notation** (Optional Compact Syntax)
+Inspired by quantum mechanics, our `.bk` format reduces verbosity:
+
+**XML (.di):**
+```xml
+<subroutine name="greet">
+  <parameters select="@name"/>
+  <output>Hello, <variable name="name"/>!</output>
+</subroutine>
+<greet name="World"/>
+```
+
+**Bra-Ket (.bk):**
+```
+<greet|
+  |parameters select=@name>
+  |output>Hello, |variable name=name>!
+
+|greet name=World>
+```
+
+### 5. **Library Ecosystem**
+Import and compose functionality with namespace-safe prefixes:
+```xml
+<import src="dirac-http"/>
+<HTTP_GET url="https://api.example.com"/>
+
+<import src="dirac-database"/>
+<DB_QUERY>SELECT * FROM users</DB_QUERY>
+```
+
+## Real-World Use Cases
+
+### System Administration
+```xml
+<llm execute="true">
+  <system>docker ps</system>
+  Analyze these containers and create Dirac code to 
+  restart any that are unhealthy.
+</llm>
+```
+
+### Data Analysis
+```xml
+<llm output="analysis">
+  <system>cat data.csv | head -20</system>
+  What patterns do you see? Generate Dirac code to process the full file.
+</llm>
+<execute source="analysis"/>
+```
+
+### Task Automation
+```xml
+<llm execute="true">
+  I need to backup all .js files modified today to ~/backup.
+  Write Dirac code to do this.
+</llm>
+```
+
+### Multi-Agent Workflows
+```xml
+<llm output="step1" execute="true">
+  Task: Analyze logs in /var/log. Generate code for this step.
+</llm>
+
+<llm execute="true">
+  Previous step output: <variable name="step1"/>
+  Now generate code to summarize findings and email the report.
+</llm>
+```
+
+## Why "Recursive" Matters
+
+In traditional programming, recursion means a function calling itself. In Dirac, **the entire execution model is recursive**:
+
+1. **Code generates code**: LLMs output Dirac programs
+2. **Programs invoke LLMs**: Those programs can ask LLMs for more code
+3. **Infinite depth**: This can continue to arbitrary depths (with safety limits)
+4. **Context flows**: Each layer has access to results from previous layers
+
+This creates a **self-extending** execution environment where the boundary between "prompt" and "program" dissolves.
+
+## Installation
+
+```bash
+npm install -g dirac-lang
+```
+
+## Quick Start
+
+**hello.di:**
+```xml
+<dirac>
+  <output>Hello, World!</output>
+</dirac>
+```
+
+**Run it:**
+```bash
+dirac hello.di
+```
+
+**With LLM (requires API key):**
+```bash
+export ANTHROPIC_API_KEY=your-key
+echo '<dirac><llm>Write a haiku about code</llm></dirac>' | dirac -
+```
+
+## Philosophy
+
+Dirac embraces three principles:
+
+1. **LLMs are co-pilots, not tools**: They execute alongside your code, not as external services
+2. **Declarative over imperative**: Say what you want, let AI figure out how
+3. **Composable intelligence**: Small, reusable pieces combine into powerful workflows
+
+## Future Vision
+
+We're building toward a world where:
+- **Natural language prompts** compile to executable Dirac
+- **AI-generated libraries** extend functionality on-demand  
+- **Self-improving programs** refactor themselves based on execution patterns
+- **Multi-model orchestration** lets different LLMs collaborate on subtasks
+
+## Community
+
+- **GitHub**: [wangzhi63/dirac](https://github.com/wangzhi63/dirac)
+- **npm**: [dirac-lang](https://www.npmjs.com/package/dirac-lang)
+- **License**: MIT
+- **Status**: Active development (v0.1.0)
+
+## Join the Movement
+
+Dirac is more than a language—it's a **paradigm shift** in how we think about code and AI. If you believe that:
+
+- Programming should be more **declarative**
+- LLMs should be **execution partners**, not API endpoints
+- Code should **generate code** dynamically
+- The future is **agentic** and **recursive**
+
+...then Dirac is for you.
+
+**Start building the future today.**
+
+```bash
+npm install -g dirac-lang
+```
+
+---
+
+*"In the quantum realm, a bra meets a ket to produce reality. In Dirac, a declaration meets an LLM to produce execution."*

package/QUICKSTART-LIBRARY.md

@@ -0,0 +1,93 @@
+# Quick Start: Publishing Your First Dirac Library
+
+## 5-Minute Guide
+
+### 1. Create Your Library (2 min)
+
+```bash
+mkdir dirac-mylibrary
+cd dirac-mylibrary
+```
+
+Create `lib/index.di`:
+```xml
+<dirac>
+<subroutine name="HELLO">
+  <eval>
+    const caller = getParams();
+    const name = caller.attributes.name || 'World';
+    console.log(`Hello, ${name}!`);
+  </eval>
+</subroutine>
+</dirac>
+```
+
+### 2. Add package.json (1 min)
+
+```bash
+npm init -y
+```
+
+Edit to add:
+```json
+{
+  "name": "dirac-mylibrary",
+  "main": "lib/index.di",
+  "keywords": ["dirac", "hello"]
+}
+```
+
+### 3. Test It (1 min)
+
+Create `test.di`:
+```xml
+<dirac>
+  <import src="./lib/index.di"/>
+  <HELLO name="Alice"/>
+</dirac>
+```
+
+Run:
+```bash
+dirac test.di
+```
+
+### 4. Publish (1 min)
+
+```bash
+npm login
+npm publish
+```
+
+Done! Others can now use:
+```bash
+npm install dirac-mylibrary
+```
+
+```xml
+<import src="./node_modules/dirac-mylibrary/lib/index.di"/>
+<HELLO name="World"/>
+```
+
+## Naming Convention
+
+- **dirac-[domain]** - Core functionality (e.g., `dirac-http`, `dirac-crypto`)
+- **@yourorg/dirac-[name]** - Organization packages
+- **dirac-contrib-[name]** - Community contributions
+
+## Where to Announce
+
+1. **npm** - Automatically indexed
+2. **GitHub** - Tag with `dirac-library` topic
+3. **Discord/Forum** - #library-showcase channel (coming soon)
+4. **awesome-dirac** - Submit PR to add your library
+5. **Twitter/X** - Use #DiracLang hashtag
+
+## Next Steps
+
+See [COMMUNITY.md](COMMUNITY.md) for full details on:
+- Quality standards
+- Best practices
+- Testing
+- Documentation
+- Community governance