{"id":28688949,"url":"https://github.com/raestrada/kumeo","last_synced_at":"2026-01-31T23:40:31.736Z","repository":{"id":294549073,"uuid":"987332210","full_name":"raestrada/kumeo","owner":"raestrada","description":"A declarative NoOps DSL for orchestrating distributed agent workflows (LLMs, ML models, Bayesian networks). Features multi-language code generation, automatic deployment, and zero operational overhead. Built with Rust, deployed to Kubernetes, and powered by NATS event streaming.","archived":false,"fork":false,"pushed_at":"2025-05-26T18:40:35.000Z","size":1258,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-14T05:11:25.515Z","etag":null,"topics":["agentic-ai","agentic-framework","agentic-workflow","automation","compiler","dsl","event-driven","llm","nats","noops","ollama","python","rust","workflow"],"latest_commit_sha":null,"homepage":"https://raestrada.github.io/kumeo/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/raestrada.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-20T23:34:19.000Z","updated_at":"2025-05-30T11:45:50.000Z","dependencies_parsed_at":"2025-05-21T00:41:51.135Z","dependency_job_id":null,"html_url":"https://github.com/raestrada/kumeo","commit_stats":null,"previous_names":["raestrada/kumeo"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/raestrada/kumeo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raestrada%2Fkumeo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raestrada%2Fkumeo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raestrada%2Fkumeo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raestrada%2Fkumeo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/raestrada","download_url":"https://codeload.github.com/raestrada/kumeo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/raestrada%2Fkumeo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28960585,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-31T23:03:11.038Z","status":"ssl_error","status_checked_at":"2026-01-31T22:56:44.691Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","agentic-framework","agentic-workflow","automation","compiler","dsl","event-driven","llm","nats","noops","ollama","python","rust","workflow"],"created_at":"2025-06-14T05:11:21.856Z","updated_at":"2026-01-31T23:40:31.717Z","avatar_url":"https://github.com/raestrada.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://raestrada.github.io/kumeo/\"\u003e\n    \u003cimg src=\"./branding/logo.png\" alt=\"Kumeo Logo\" width=\"200\"\u003e\n  \u003c/a\u003e\n\u003c/div\u003e\n\n# Kumeo 🚀  \n\n[![Kumeo CI](https://github.com/raestrada/kumeo/actions/workflows/ci.yml/badge.svg)](https://github.com/raestrada/kumeo/actions/workflows/ci.yml)\n\n**A declarative language for orchestrating distributed agent workflows with LLMs, ML models, and event-driven systems**  \n\nKumeo (from *kume*, meaning *\"together\"* in Mapudungun) is a domain-specific language (DSL) designed to define complex workflows where heterogeneous agents collaborate via events. It employs a multi-language compilation approach, generating optimized code for each agent type (Rust for performance-critical components, Python for ML and Bayesian operations), uses NATS for event streaming, and deploys to Kubernetes for scalability.  \n\n---\n\n## 🔍 Key Features  \n- **Declarative Workflows**: Define agent interactions as event-driven flows  \n- **True NoOps Solution**: The language itself handles everything from code generation to deployment - just write your workflow and run it\n- **Multi-Language Code Generation**: Automatically selects the optimal language for each component:\n  - **Rust**: For high-performance, low-latency agents\n  - **Python**: For ML, data science, and rapid development\n  - **Seamless Interop**: Agents in different languages can communicate transparently\n- **Agent Types**: Support for LLMs (Ollama/OpenAI), ML models (scikit-learn, ONNX), Bayesian networks, and human-in-the-loop  \n- **Event Orchestration**: Built on NATS for real-time, distributed communication  \n- **Kubernetes Native**: Auto-generates deployment manifests for scalable infrastructure  \n- **Visual Editor**: Svelte-based UI for workflow design and monitoring  \n\n---\n\n## 📝 Language Specification\n\n\u003cdiv align=\"center\"\u003e\n\n**[View the complete Kumeo Language Specification](https://github.com/raestrada/kumeo/blob/main/compiler/spec/language_specification.md)**\n\nComprehensive documentation of syntax, grammar, type system, and execution semantics\n\n\u003c/div\u003e\n\n---\n\n## 🏗️ Architecture Overview  \n```\nkumeo/\n├── compiler/       → Rust-based compiler (Kumeo → Multi-language Code + Kubernetes YAML)  \n│   ├── templates/  → Code generation templates for different languages\n├── runtime/        → Agent execution engine (NATS integration)  \n├── ui/             → Svelte visual workflow editor  \n├── examples/       → Sample Kumeo workflows  \n└── kubernetes/     → Deployment templates  \n```\n\n---\n\n## 🚀 Getting Started  \n1. **Install Dependencies**  \n   ```bash\n   rustup install stable\n   cargo install --locked mdbook\n   npm install -g svelte-language-server\n   kubectl apply -f https://raw.githubusercontent.com/nats-io/nats-server/main/k8s/nats-standalone.yaml\n   ```\n\n2. **Build Compiler**  \n   ```bash\n   cd compiler \u0026\u0026 cargo build --release\n   ```\n\n3. **Run Example Workflow**  \n   ```bash\n   ./target/release/kumeo-compiler \\\n     --input examples/fraud_detection.kumeo \\\n     --output dist/\n   kubectl apply -f dist/\n   ```\n\n---\n\n## 📄 Example Kumeo Workflow  \n```kumeo\nworkflow FraudDetection {\n  source: NATS(\"transactions\")\n  target: NATS(\"alerts\")\n  context: BayesianNetwork(\"risk.bn\")\n\n  agents: [\n    LLM(\"ollama/llama3\", prompt=\"Classify {{data}} as fraud? Context: {{context}}\"),\n    MLModel(\"isolation_forest.pkl\", input=LLM.output),\n    DecisionMatrix(\"policy.dmx\", input=MLModel.output)\n  ]\n}\n```\n\n---\n\n## 🛠️ Agent Examples\n\n### Python Agent\n\nHere's a simple example of a Python agent in Kumeo:\n\n```python\nfrom kumeo_runtime import BaseAgent, RuntimeClient\n\nclass GreeterAgent(BaseAgent):\n    async def on_start(self):\n        print(f\"{self.agent_id} is starting...\")\n        \n    async def on_stop(self):\n        print(f\"{self.agent_id} is stopping...\")\n        \n    async def on_message(self, message):\n        action = message.get('action')\n        if action == 'greet':\n            name = message.get('name', 'stranger')\n            return {\"message\": f\"Hello, {name}!\"}\n        return {\"error\": \"Unknown action\"}\n\n# Example usage\nasync def main():\n    async with RuntimeClient() as runtime:\n        agent = GreeterAgent(\"greeter-1\", runtime)\n        await agent.start()\n        \n        # Send a message to the agent\n        response = await agent.handle_message({\n            \"action\": \"greet\",\n            \"name\": \"Kumeo User\"\n        })\n        print(response)  # {\"message\": \"Hello, Kumeo User!\"}\n        \n        await agent.stop()\n\nif __name__ == \"__main__\":\n    import asyncio\n    asyncio.run(main())\n```\n\n### Rust Agent\n\nHere's the equivalent agent in Rust for high-performance scenarios:\n\n```rust\nuse kumeo_runtime::prelude::*;\nuse serde_json::{json, Value};\nuse async_trait::async_trait;\n\nstruct GreeterAgent {\n    agent_id: String,\n}\n\n#[async_trait]\nimpl Agent for GreeterAgent {\n    fn id(\u0026self) -\u003e \u0026str {\n        \u0026self.agent_id\n    }\n\n    async fn on_start(\u0026mut self, _runtime: \u0026RuntimeClient) -\u003e Result\u003c(), AgentError\u003e {\n        println!(\"{} is starting...\", self.agent_id);\n        Ok(())\n    }\n\n    async fn on_stop(\u0026mut self) -\u003e Result\u003c(), AgentError\u003e {\n        println!(\"{} is stopping...\", self.agent_id);\n        Ok(())\n    }\n\n    async fn on_message(\u0026mut self, message: Value) -\u003e Result\u003cValue, AgentError\u003e {\n        let action = message.get(\"action\").and_then(|a| a.as_str()).unwrap_or(\"\");\n        \n        match action {\n            \"greet\" =\u003e {\n                let name = message.get(\"name\").and_then(|n| n.as_str()).unwrap_or(\"stranger\");\n                Ok(json!({ \"message\": format!(\"Hello, {}!\", name) }))\n            }\n            _ =\u003e Ok(json!({ \"error\": \"Unknown action\" })),\n        }\n    }\n}\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    let runtime = RuntimeClient::new().await?;\n    let mut agent = GreeterAgent {\n        agent_id: \"rust-greeter-1\".to_string(),\n    };\n    \n    agent.start(\u0026runtime).await?;\n    \n    // Send a message to the agent\n    let response = agent.handle_message(json!({ \n        \"action\": \"greet\",\n        \"name\": \"Rust User\" \n    })).await?;\n    \n    println!(\"Response: {}\", response);\n    \n    agent.stop().await?;\n    Ok(())\n}\n```\n\n---\n\n## 💻 Development Guide\n\n### Prerequisites\n\n- Rust toolchain (1.65 or newer)\n- LALRPOP installed (`cargo install lalrpop`)\n- Optional: NATS server for testing integrations\n\n### Building the Compiler\n\n```bash\n# Clone the repository\ngit clone https://github.com/raestrada/kumeo.git\ncd kumeo\n\n# Build the compiler\ncd compiler\ncargo build\n\n# Run tests\ncargo test\n```\n\n### Running the Compiler\n\n```bash\n# Development mode\ncargo run -- --input examples/simple.kumeo --output dist/\n\n# Or using the compiled binary\n./target/debug/kumeo-compiler --input examples/simple.kumeo --output dist/\n```\n\n### Development Workflow\n\n1. Make your changes to the compiler code\n2. Run tests: `cargo test`\n3. Format your code: `cargo fmt`\n4. Check for issues: `cargo clippy`\n5. Build: `cargo build`\n\n### Docker Build\n\n```bash\n# Build the Docker image\ncd compiler\ndocker build -t kumeo-compiler .\n\n# Run the compiler using Docker\ndocker run -v $(pwd)/examples:/examples -v $(pwd)/dist:/dist kumeo-compiler --input /examples/simple.kumeo --output /dist/\n```\n\n## 📊 Test Coverage\n\nThe project includes automated tests to ensure code quality. To generate a test coverage report:\n\n### Prerequisites\n\n```bash\n# Install cargo-tarpaulin\ncargo install cargo-tarpaulin\n\n# Install development dependencies\nsudo apt-get update \u0026\u0026 sudo apt-get install -y pkg-config libssl-dev\n```\n\n### Generate Coverage Report\n\n```bash\n# Navigate to the compiler directory\ncd compiler\n\n# Run tests with coverage\ncargo tarpaulin --out Html --output-dir ./target/tarpaulin\n```\n\nThe HTML report will be generated at `compiler/target/tarpaulin/tarpaulin-report.html`.\n\n### Current Coverage\n\n- **Total Coverage**: 53.62%\n- **Lines Covered**: 496 out of 925 lines\n\n### Areas Needing Improvement\n\n1. Files with 0% coverage:\n   - `src/main.rs`\n   - `src/codegen/code_generator.rs`\n   - `src/error.rs`\n   - `src/logging.rs`\n\n2. Files with low coverage (\u003c50%):\n   - `src/lexer.rs` (20.44%)\n   - `src/parser.rs` (36.67%)\n\nTo improve coverage, consider adding unit tests for these areas.\n\n\n---\n\n## 🤝 Contributing  \n1. Fork the repo  \n2. Create a feature branch (`git checkout -b feature/awesome-changes`)  \n3. Commit changes (`git commit -am 'Add new feature'`)  \n4. Push to branch (`git push origin feature/awesome-changes`)  \n5. Open a Pull Request  \n\n---\n\n## 📄 License  \nThis project is licensed under the GNU General Public License v3.0. See [LICENSE](LICENSE) for details.  \n\n---\n\n## 🎨 Editor Setup\n\n### VS Code Syntax Highlighting\n\nTo enable syntax highlighting for `.kumeo` files in VS Code:\n\n1. Create or edit the `.vscode/settings.json` file in your project:\n   ```json\n   {\n     \"files.associations\": {\n       \"*.kumeo\": \"javascript\"\n     },\n     \"javascript.validate.enable\": false,\n     \"[javascript]\": {\n       \"editor.formatOnSave\": false\n     },\n     \"editor.tokenColorCustomizations\": {\n       \"textMateRules\": [\n         {\n           \"scope\": \"comment.line.double-slash.js\",\n           \"settings\": {\n             \"foreground\": \"#6A9955\",\n             \"fontStyle\": \"italic\"\n           }\n         },\n         {\n           \"scope\": \"keyword.control\",\n           \"settings\": {\n             \"foreground\": \"#569CD6\"\n           }\n         },\n         {\n           \"scope\": \"entity.name.type\",\n           \"settings\": {\n             \"foreground\": \"#4EC9B0\"\n           }\n         },\n         {\n           \"scope\": \"string\",\n           \"settings\": {\n             \"foreground\": \"#CE9178\"\n           }\n         }\n       ]\n     }\n   }\n   ```\n\n2. Reopen any `.kumeo` files you have open, or restart VS Code.\n\n3. Your `.kumeo` files will now have basic syntax highlighting with comments, strings, and keywords properly colored.\n\n---\n\n## 📬 Contact  \nGitHub: [@your-username](https://github.com/your-username)  \nTwitter: [@your-handle](https://twitter.com/your-handle)# kumeo\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraestrada%2Fkumeo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fraestrada%2Fkumeo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraestrada%2Fkumeo/lists"}