openagentflow 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AbdulRahman Elzahaby (egyjs) and OpenAgentFlow Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,262 @@
+<p align="center">
+  <img src="docs/assets/oaf-logo.svg" alt="OpenAgentFlow Logo" width="160"/>
+</p>
+
+# OpenAgentFlow
+
+**An Open, Portable Specification for Executable Multi-Agent Workflows**
+
+[![Tests: 163 Passing](https://img.shields.io/badge/tests-163%20passing-brightgreen.svg)](#testing--quality-assurance)
+[![Core Dependencies: 0](https://img.shields.io/badge/core%20dependencies-0-blue.svg)](#project-structure)
+[![Target Runtime: LangGraph](https://img.shields.io/badge/runtime-LangGraph%20Python-orange.svg)](#multi-llm--runtime-integration)
+[![LLM Providers: Gemini | OpenAI | Anthropic](https://img.shields.io/badge/LLMs-Gemini%20%7C%20OpenAI%20%7C%20Anthropic-purple.svg)](#multi-llm--runtime-integration)
+[![VS Code Extension](https://img.shields.io/badge/VS%20Code-Syntax%20Support-007ACC.svg?logo=visualstudiocode)](https://marketplace.visualstudio.com/items?itemName=OpenAgentFlow.openagentflow-support)
+[![Documentation](https://img.shields.io/badge/docs-complete-blue.svg)](docs/index.md)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> *What OpenAPI is for REST APIs, OpenAgentFlow (`.oaf`) is for AI agent workflows.*
+
+<p align="center">
+  <img src="docs/assets/demo.gif" alt="OpenAgentFlow Demo" width="800"/>
+</p>
+
+### ⚡ The 60-Second Example
+Define your multi-agent workflow in clean, human-readable `.oaf` text—completely decoupled from Python/Node boilerplate:
+
+```js
+workflow "Quick Summarize" {
+    
+    state {
+        source_text: string @required
+        extracted_points: string
+        summary: string
+    }
+
+    agent Extractor {
+        instructions: "Read the `source_text` and extract the most important facts into a concise bulleted list."
+        model: "gemini-2.0-flash"
+        inputs: [source_text]
+        outputs: [extracted_points]
+    }
+
+    agent Synthesizer {
+        instructions: "Take the extracted points and weave them into a clear, cohesive summary paragraph."
+        model: "gpt-4o"
+        inputs: [extracted_points]
+        outputs: [summary]
+    }
+
+    flow {
+        start -> Extractor 
+        Extractor -> Synthesizer
+        Synthesizer -> end
+    }
+}
+```
+
+Install the CLI globally and execute your workflow immediately (or clone our [Starter Repository](https://github.com/OpenAgentFlow/OpenAgentFlow-starter)):
+```bash
+# Option A: Save the block above to summarize.oaf and run directly
+npm install -g openagentflow
+oaf run summarize.oaf
+
+# Option B: Clone our official starter repository with pre-built workflows & inputs
+git clone https://github.com/OpenAgentFlow/OpenAgentFlow-starter.git my-agents
+cd my-agents && npm run setup && npm run triage
+```
+
+---
+
+## 🌟 Why OpenAgentFlow?
+
+Modern AI agent frameworks (like LangGraph, AutoGen, and CrewAI) each introduce distinct concepts, Python/Node boilerplate, and proprietary APIs. **OpenAgentFlow** introduces a neutral, human-readable authoring language (`.oaf`) that separates workflow definition from execution runtimes.
+
+### ✨ Key Features
+- **Write Once, Run Anywhere**: Define multi-agent topologies, state schemas, and agent instructions once in pure `.oaf` text and compile deterministically to production-ready Python code.
+- **Strict Semantic Validation**: Three-phase checking catches dead ends, unreachable agents, and missing fields *before* running expensive LLM calls.
+- **Zero-Config Multi-LLM**: Auto-detects and adapts to Gemini, OpenAI, and Anthropic endpoints without changing your `.oaf` code.
+- **4-Tier Env Hierarchy & Auth**: Seamlessly resolve API keys across CLI flags, local `.env` files, system variables, and global `~/.oaf/.env` credentials (`oaf auth`).
+- **Push-Model State Injection**: Inject JSON payloads (`--input data.json`) directly into workflows for easy backend/API integration.
+- **Zero Core Dependencies**: Pure Node.js compiler (`lexer`, `parser`, `validator`, `IR generator`, and `LangGraph adapter`).
+
+---
+
+## 🚀 Quick Start
+
+### Option 1: Using the Starter Repository (Recommended — 60 Seconds)
+The fastest way to start building executable multi-agent workflows without manual setup or missing file errors is using our official template repository:
+
+1. **Clone the Starter Project:**
+   ```bash
+   git clone https://github.com/OpenAgentFlow/OpenAgentFlow-starter.git my-agents
+   cd my-agents
+   ```
+
+2. **Run Automated Environment Setup:**
+   Our cross-platform setup script (`setup.js`) checks your system, creates your Python virtual environment (`venv`), installs LangGraph dependencies, and initializes your `.env` configuration automatically across Windows, macOS, and Linux:
+   ```bash
+   npm install
+   npm run setup
+   ```
+
+3. **Configure API Keys (`oaf auth`):**
+   Set your keys interactively via CLI (or edit the `.env` file generated in your project root):
+   ```bash
+   npx openagentflow auth
+   ```
+
+4. **Run Your First Workflow Live!**
+   Execute pre-built multi-agent topologies immediately:
+   ```bash
+   # Run Customer Support Triage Workflow with injected JSON state
+   npm run triage
+
+   # Or compile directly to a LangGraph Python application
+   npm run compile-triage
+   ```
+
+---
+
+### Option 2: Standalone Global CLI
+If you prefer creating workflows from scratch in your own workspace without cloning a template:
+
+1. **Install Prerequisites & CLI:**
+   Ensure **Node.js** (v18+) and **Python** (v3.10+) are installed, then install the CLI globally:
+   ```bash
+   npm install -g openagentflow
+   ```
+
+2. **Set Your API Keys (`oaf auth`):**
+   Configure credentials securely in `~/.oaf/.env` (`0o600` permissions):
+   ```bash
+   oaf auth
+   # Or set manually: export GOOGLE_API_KEY="your-key" / $env:GOOGLE_API_KEY="your-key"
+   ```
+
+3. **Set Up Python Runtime & Virtual Environment:**
+   To execute compiled `.oaf` workflows live via LangGraph against real LLM endpoints:
+   ```bash
+   # Create and activate Python virtual environment
+   python -m venv venv
+   source venv/bin/activate  # Windows PowerShell: .\venv\Scripts\Activate.ps1
+
+   # Install LangGraph and multi-provider LangChain drivers
+   pip install langgraph langchain-google-genai langchain-openai langchain-anthropic pydantic
+   ```
+
+4. **Create & Execute Workflows Live:**
+   Create a `.oaf` workflow file (e.g., `my-workflow.oaf`) along with your JSON data (`data.json`) and run:
+   ```bash
+   oaf run my-workflow.oaf --input data.json
+   ```
+
+> 📖 **For the full guide, see [Documentation](docs/index.md)**.
+
+---
+
+## 📖 Documentation
+
+The complete documentation is available in the `docs/` directory, including:
+* **[Language Reference](docs/language/oaf-language.md):** Complete `.oaf` syntax.
+* **[Formal Specs](spec/SPEC.md):** EBNF grammar, semantic rules, and IR schema.
+* **[API & CLI Ref](docs/cli/cli-reference.md):** Programmatic API and command-line flags.
+
+---
+
+## 📝 The `.oaf` Language at a Glance
+
+OpenAgentFlow provides a clean, declarative syntax for describing stateful multi-agent workflows:
+
+```oaf
+workflow "Quick Summarize" {
+
+    config {
+        max_iterations: 5
+        timeout_seconds: 60
+    }
+
+    state {
+        request: string
+        source_text: string
+        key_points: list[string]
+        summary: string
+    }
+
+    agent Analyst {
+        instructions: """
+        Analyze the request and source text.
+        Identify the most important facts.
+        """
+        model: "gpt-4"
+        temperature: 0.2
+        inputs: [request, source_text]
+        outputs: [key_points]
+    }
+
+    agent Writer {
+        instructions: """
+        Write a clear, concise summary from the key points.
+        """
+        model: "gpt-4"
+        temperature: 0.7
+        inputs: [key_points]
+        outputs: [summary]
+    }
+
+    flow {
+        start -> Analyst
+        Analyst -> Writer
+        Writer -> end
+    }
+}
+```
+
+---
+
+## ⚙️ Compilation & Execution Pipeline
+
+The OpenAgentFlow compiler transforms raw `.oaf` source code into validated Intermediate Representation (IR) JSON, which runtime adapters then transform into executable source code:
+
+```
+┌─────────────┐     ┌───────────┐     ┌────────────┐     ┌───────────────────┐
+│ Source Code │ ──▶ │   Lexer   │ ──▶ │   Parser   │ ──▶ │    AST (JSON)     │
+│  (.oaf file)│     │ (lexer.js)│     │(parser.js) │     │    (ast.js)       │
+└─────────────┘     └───────────┘     └────────────┘     └─────────┬─────────┘
+                                                                   │
+┌─────────────┐     ┌───────────┐     ┌────────────┐     ┌─────────▼─────────┘
+│  Execution  │ ◀── │ LangGraph │ ◀── │  Compiler  │ ◀── │ Semantic Validator│
+│ (Live Subproc)    │  Adapter  │     │ (IR Gen)   │     │  (validator.js)   │
+└─────────────┘     └───────────┘     └────────────┘     └───────────────────┘
+```
+
+---
+
+## 🧠 Multi-LLM & Runtime Integration
+
+When compiling to LangGraph, the runtime automatically manages providers. You can specify `model: "gpt-4o"` or `model: "gemini-2.0-flash"` in your `.oaf` file, and the compiled Python script will auto-detect your API keys (via `.env`, system vars, or `~/.oaf/.env`) and route the request to the correct provider.
+
+---
+
+## 🗺️ Roadmap & Project Status
+
+| Phase | Deliverables | Status |
+| :--- | :--- | :--- |
+| **Phase 1** — Specification | Language spec (`SPEC.md`), EBNF grammar, examples, IR definition | ✅ Complete |
+| **Phase 2** — Compiler MVP | Zero-dependency Lexer, Parser, 3-Phase Validator, IR Generator, CLI | ✅ Complete |
+| **Phase 3** — Runtime Integration | LangGraph Python Adapter, Dual-LLM (`get_llm()`), Live `run` CLI, E2E Demo | ✅ Complete |
+| **Phase 4** — State Initialization (`--input`) | File-based state injection (`--input data.json`), runtime override (`OAF_INPUT_FILE`) | ✅ Complete |
+| **Phase 4.5** — Multi-Provider, Auth & Tooling | Anthropic (`claude-*`) & Google (`gemma-*`) inference, `oaf auth`, VS Code syntax extension (`.oaf`) | ✅ Complete |
+| **Phase 5** — Additional Adapters | AutoGen Adapter, CrewAI Adapter, Formal `Adapter` base contract | 🔲 Planned |
+| **Phase 6** — Developer CLI Tooling | `oaf fmt` (auto-formatter), `oaf init` (project scaffolding) | 🔲 Planned |
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions from developers, researchers, and engineers! Whether you want to pick up a [`good first issue`](https://github.com/OpenAgentFlow/openagentflow/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22), help build our planned Phase 5 target adapters (**Microsoft AutoGen** or **CrewAI**), or propose language enhancements, please check out our detailed [Contributing Guide](CONTRIBUTING.md) to get started.
+
+---
+
+## 📄 License
+
+This project is open-source and licensed under the [MIT License](LICENSE).

package/adapters/langgraph/demo_template.js

@@ -0,0 +1,104 @@
+/**
+ * OpenAgentFlow — Isolated Demo Helper Template Module
+ *
+ * This module generates self-contained Python code (`_DemoChatModel`, `_maybe_get_demo_llm`,
+ * `_format_demo_state`) used strictly when `--demo` (OAF_DEMO=1) is active.
+ *
+ * It can be cleanly deleted from the codebase if demo simulation mode is ever removed.
+ * See: llm/handover/2026-07-20-screencast-and-demo-removal-guide.md
+ */
+
+export function generateDemoHelperTemplate() {
+  const lines = [
+    `# ─── DEMO HOOK MODULE (Cleanly removable) ───────────────────────────────────`,
+    `import hashlib, json, os`,
+    `class _DemoChatModel:`,
+    `    def __init__(self, model, temperature=0, provider="demo"):`,
+    `        self.model = model`,
+    `        self.temperature = temperature`,
+    `        self._oaf_provider = provider`,
+    ``,
+    `    def invoke(self, messages, *args, **kwargs):`,
+    `        cache_dir = os.path.join(os.path.expanduser("~"), ".oaf")`,
+    `        cache_file = os.path.join(cache_dir, "demo_cache.json")`,
+    `        prompt_parts = []`,
+    `        sys_prompt = ""`,
+    `        for m in messages:`,
+    `            if isinstance(m, dict):`,
+    `                role = m.get("role", "")`,
+    `                content_str = str(m.get("content", ""))`,
+    `                if role == "system": sys_prompt = content_str`,
+    `                prompt_parts.append(f"{role}:{content_str}")`,
+    `            elif hasattr(m, "type"):`,
+    `                content_str = str(getattr(m, "content", ""))`,
+    `                if m.type == "system": sys_prompt = content_str`,
+    `                prompt_parts.append(f"{m.type}:{content_str}")`,
+    `            else:`,
+    `                prompt_parts.append(str(m))`,
+    ``,
+    `        full_prompt = "|".join(prompt_parts)`,
+    `        cache_key = f"{self.model}:{hashlib.sha256(full_prompt.encode('utf-8')).hexdigest()}"`,
+    ``,
+    `        if os.path.exists(cache_file):`,
+    `            try:`,
+    `                with open(cache_file, "r", encoding="utf-8") as f:`,
+    `                    cache_data = json.load(f)`,
+    `                if cache_key in cache_data:`,
+    `                    class _AIMessage:`,
+    `                        def __init__(self, text): self.content = text`,
+    `                    return _AIMessage(cache_data[cache_key])`,
+    `            except Exception:`,
+    `                pass`,
+    ``,
+    `        if "extract the most important facts" in sys_prompt.lower() or "extractor" in sys_prompt.lower():`,
+    `            content = (`,
+    `                "- Monolithic LLMs are transitioning to multi-agent pipelines where specialized agents handle distinct sub-tasks.\\n"`,
+    `                "- Robust state management and clear communication protocols are critical to prevent information loss and infinite loops.\\n"`,
+    `                "- Standardized open-source frameworks provide unified syntax and configurations, lowering the engineering barrier."`,
+    `            )`,
+    `        elif "weave them into a clear, cohesive summary" in sys_prompt.lower() or "synthesizer" in sys_prompt.lower():`,
+    `            content = (`,
+    `                "Modern AI is rapidly evolving from monolithic models to collaborative multi-agent pipelines where specialized models execute modular sub-tasks. "`,
+    `                "While this approach improves reliability and performance, it introduces orchestration challenges requiring robust state management and structured communication protocols. "`,
+    `                "Standardized open-source frameworks address these bottlenecks by offering a unified syntax and automated state coordination, making multi-agent deployment as seamless as containerizing a web application."`,
+    `            )`,
+    `        else:`,
+    `            content = f"[Demo Output for {self.model}]: Successfully processed workflow input."`,
+    ``,
+    `        class _AIMessage:`,
+    `            def __init__(self, text):`,
+    `                self.content = text`,
+    ``,
+    `        try:`,
+    `            os.makedirs(cache_dir, exist_ok=True)`,
+    `            cache_data = {}`,
+    `            if os.path.exists(cache_file):`,
+    `                with open(cache_file, "r", encoding="utf-8") as f:`,
+    `                    cache_data = json.load(f)`,
+    `            cache_data[cache_key] = content`,
+    `            with open(cache_file, "w", encoding="utf-8") as f:`,
+    `                json.dump(cache_data, f, indent=2, ensure_ascii=False)`,
+    `        except Exception:`,
+    `            pass`,
+    ``,
+    `        return _AIMessage(content)`,
+    ``,
+    `def _maybe_get_demo_llm(target_model, temperature, target_provider):`,
+    `    if os.environ.get("OAF_DEMO") == "1" or target_provider == "demo":`,
+    `        return _DemoChatModel(model=target_model, temperature=temperature, provider=target_provider or "demo")`,
+    `    return None`,
+    ``,
+    `def _format_demo_state(result, initial_state):`,
+    `    if os.environ.get("OAF_DEMO") != "1":`,
+    `        return result`,
+    `    display_state = {}`,
+    `    for k, v in result.items():`,
+    `        if k in initial_state and isinstance(v, str) and len(v) > 100 and result[k] == initial_state[k]:`,
+    `            display_state[k] = f"{v[:80]}... ({len(v)} chars abbreviated)"`,
+    `        else:`,
+    `            display_state[k] = v`,
+    `    return display_state`,
+    `# ────────────────────────────────────────────────────────────────────────────`,
+  ];
+  return lines.join('\n');
+}