Kumeo 🚀

A declarative language for orchestrating distributed agent workflows with LLMs, ML models, and event-driven systems

Kumeo (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.

🔍 Key Features

Declarative Workflows: Define agent interactions as event-driven flows
True NoOps Solution: The language itself handles everything from code generation to deployment - just write your workflow and run it
Multi-Language Code Generation: Automatically selects the optimal language for each component:
- Rust: For high-performance, low-latency agents
- Python: For ML, data science, and rapid development
- Seamless Interop: Agents in different languages can communicate transparently
Agent Types: Support for LLMs (Ollama/OpenAI), ML models (scikit-learn, ONNX), Bayesian networks, and human-in-the-loop
Event Orchestration: Built on NATS for real-time, distributed communication
Kubernetes Native: Auto-generates deployment manifests for scalable infrastructure
Visual Editor: Svelte-based UI for workflow design and monitoring

📝 Language Specification

View the complete Kumeo Language Specification

Comprehensive documentation of syntax, grammar, type system, and execution semantics

</div>

🏗️ Architecture Overview

kumeo/
├── compiler/       → Rust-based compiler (Kumeo → Multi-language Code + Kubernetes YAML)  
│   ├── templates/  → Code generation templates for different languages
├── runtime/        → Agent execution engine (NATS integration)  
├── ui/             → Svelte visual workflow editor  
├── examples/       → Sample Kumeo workflows  
└── kubernetes/     → Deployment templates

🚀 Getting Started

Install Dependencies

rustup install stable
cargo install --locked mdbook
npm install -g svelte-language-server
kubectl apply -f https://raw.githubusercontent.com/nats-io/nats-server/main/k8s/nats-standalone.yaml

Build Compiler
```
cd compiler && cargo build --release
```

Run Example Workflow

./target/release/kumeo-compiler \
  --input examples/fraud_detection.kumeo \
  --output dist/
kubectl apply -f dist/

📄 Example Kumeo Workflow

workflow FraudDetection {
  source: NATS("transactions")
  target: NATS("alerts")
  context: BayesianNetwork("risk.bn")

  agents: [
    LLM("ollama/llama3", prompt="Classify {{data}} as fraud? Context: {{context}}"),
    MLModel("isolation_forest.pkl", input=LLM.output),
    DecisionMatrix("policy.dmx", input=MLModel.output)
  ]
}

🛠️ Agent Examples

Python Agent

Here's a simple example of a Python agent in Kumeo:

from kumeo_runtime import BaseAgent, RuntimeClient

class GreeterAgent(BaseAgent):
    async def on_start(self):
        print(f"{self.agent_id} is starting...")
        
    async def on_stop(self):
        print(f"{self.agent_id} is stopping...")
        
    async def on_message(self, message):
        action = message.get('action')
        if action == 'greet':
            name = message.get('name', 'stranger')
            return {"message": f"Hello, {name}!"}
        return {"error": "Unknown action"}

# Example usage
async def main():
    async with RuntimeClient() as runtime:
        agent = GreeterAgent("greeter-1", runtime)
        await agent.start()
        
        # Send a message to the agent
        response = await agent.handle_message({
            "action": "greet",
            "name": "Kumeo User"
        })
        print(response)  # {"message": "Hello, Kumeo User!"}
        
        await agent.stop()

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

Rust Agent

Here's the equivalent agent in Rust for high-performance scenarios:

use kumeo_runtime::prelude::*;
use serde_json::{json, Value};
use async_trait::async_trait;

struct GreeterAgent {
    agent_id: String,
}

#[async_trait]
impl Agent for GreeterAgent {
    fn id(&self) -> &str {
        &self.agent_id
    }

    async fn on_start(&mut self, _runtime: &RuntimeClient) -> Result<(), AgentError> {
        println!("{} is starting...", self.agent_id);
        Ok(())
    }

    async fn on_stop(&mut self) -> Result<(), AgentError> {
        println!("{} is stopping...", self.agent_id);
        Ok(())
    }

    async fn on_message(&mut self, message: Value) -> Result<Value, AgentError> {
        let action = message.get("action").and_then(|a| a.as_str()).unwrap_or("");
        
        match action {
            "greet" => {
                let name = message.get("name").and_then(|n| n.as_str()).unwrap_or("stranger");
                Ok(json!({ "message": format!("Hello, {}!", name) }))
            }
            _ => Ok(json!({ "error": "Unknown action" })),
        }
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let runtime = RuntimeClient::new().await?;
    let mut agent = GreeterAgent {
        agent_id: "rust-greeter-1".to_string(),
    };
    
    agent.start(&runtime).await?;
    
    // Send a message to the agent
    let response = agent.handle_message(json!({ 
        "action": "greet",
        "name": "Rust User" 
    })).await?;
    
    println!("Response: {}", response);
    
    agent.stop().await?;
    Ok(())
}

💻 Development Guide

Prerequisites

Rust toolchain (1.65 or newer)
LALRPOP installed (cargo install lalrpop)
Optional: NATS server for testing integrations

Building the Compiler

# Clone the repository
git clone https://github.com/raestrada/kumeo.git
cd kumeo

# Build the compiler
cd compiler
cargo build

# Run tests
cargo test

Running the Compiler

# Development mode
cargo run -- --input examples/simple.kumeo --output dist/

# Or using the compiled binary
./target/debug/kumeo-compiler --input examples/simple.kumeo --output dist/

Development Workflow

Make your changes to the compiler code
Run tests: cargo test
Format your code: cargo fmt
Check for issues: cargo clippy
Build: cargo build

Docker Build

# Build the Docker image
cd compiler
docker build -t kumeo-compiler .

# Run the compiler using Docker
docker run -v $(pwd)/examples:/examples -v $(pwd)/dist:/dist kumeo-compiler --input /examples/simple.kumeo --output /dist/

📊 Test Coverage

The project includes automated tests to ensure code quality. To generate a test coverage report:

Prerequisites

# Install cargo-tarpaulin
cargo install cargo-tarpaulin

# Install development dependencies
sudo apt-get update && sudo apt-get install -y pkg-config libssl-dev

Generate Coverage Report

# Navigate to the compiler directory
cd compiler

# Run tests with coverage
cargo tarpaulin --out Html --output-dir ./target/tarpaulin

The HTML report will be generated at compiler/target/tarpaulin/tarpaulin-report.html.

Current Coverage

Total Coverage: 53.62%
Lines Covered: 496 out of 925 lines

Areas Needing Improvement

Files with 0% coverage:
- src/main.rs
- src/codegen/code_generator.rs
- src/error.rs
- src/logging.rs
Files with low coverage (<50%):
- src/lexer.rs (20.44%)
- src/parser.rs (36.67%)

To improve coverage, consider adding unit tests for these areas.

🤝 Contributing

Fork the repo
Create a feature branch (git checkout -b feature/awesome-changes)
Commit changes (git commit -am 'Add new feature')
Push to branch (git push origin feature/awesome-changes)
Open a Pull Request

📄 License

This project is licensed under the GNU General Public License v3.0. See LICENSE for details.

🎨 Editor Setup

VS Code Syntax Highlighting

To enable syntax highlighting for .kumeo files in VS Code:

Create or edit the .vscode/settings.json file in your project:

{
  "files.associations": {
    "*.kumeo": "javascript"
  },
  "javascript.validate.enable": false,
  "[javascript]": {
    "editor.formatOnSave": false
  },
  "editor.tokenColorCustomizations": {
    "textMateRules": [
      {
        "scope": "comment.line.double-slash.js",
        "settings": {
          "foreground": "#6A9955",
          "fontStyle": "italic"
        }
      },
      {
        "scope": "keyword.control",
        "settings": {
          "foreground": "#569CD6"
        }
      },
      {
        "scope": "entity.name.type",
        "settings": {
          "foreground": "#4EC9B0"
        }
      },
      {
        "scope": "string",
        "settings": {
          "foreground": "#CE9178"
        }
      }
    ]
  }
}

Reopen any .kumeo files you have open, or restart VS Code.
Your .kumeo files will now have basic syntax highlighting with comments, strings, and keywords properly colored.

📬 Contact

GitHub: @your-username
Twitter: @your-handle# kumeo

Kumeo

Install / Use

README

Kumeo 🚀

🔍 Key Features

📝 Language Specification

🏗️ Architecture Overview

🚀 Getting Started

📄 Example Kumeo Workflow

🛠️ Agent Examples

Python Agent

Rust Agent

💻 Development Guide

Prerequisites

Building the Compiler

Running the Compiler

Development Workflow

Docker Build

📊 Test Coverage

Prerequisites

Generate Coverage Report

Current Coverage

Areas Needing Improvement

🤝 Contributing

📄 License

🎨 Editor Setup

VS Code Syntax Highlighting

📬 Contact