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.

• 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

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  

1. 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

2. Build Compiler

   cd compiler && cargo build --release

3. Run Example Workflow

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

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)
  ]
}

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())

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(())
}

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

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

# Build the compiler
cd compiler
cargo build

# Run tests
cargo test

# 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/

1. Make your changes to the compiler code
2. Run tests: cargo test
3. Format your code: cargo fmt
4. Check for issues: cargo clippy
5. Build: cargo 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/

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

# Install cargo-tarpaulin
cargo install cargo-tarpaulin

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

# 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.

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

1. Files with 0% coverage:

   • src/main.rs
   • src/codegen/code_generator.rs
   • src/error.rs
   • src/logging.rs

2. 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.

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

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

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

1. 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"
           }
         }
       ]
     }
   }

2. Reopen any .kumeo files you have open, or restart VS Code.

3. Your .kumeo files will now have basic syntax highlighting with comments, strings, and keywords properly colored.

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