mechano

module

v1.3.0 Latest Latest Go to latest Published: Nov 8, 2025 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/yasir2000/mechano

Links

Open Source Insights

README ¶

Mechano

AI Agent Runtime Layer for Dapr

Intelligent, autonomous microservice communication through AI Agents

Features • Quick Start • Documentation • Examples • Contributing • Sponsor

🎯 What is Mechano?

Mechano is a complete runtime layer that extends Dapr to enable intelligent, autonomous communication between microservices through AI Agents. It seamlessly integrates with Dapr's existing building blocks and adds powerful agent-based capabilities through an expressive DSL.

Think of it as "AI Agents meet Cloud-Native Microservices" - combining the best of LangChain/CrewAI/AutoGen with Dapr's distributed systems capabilities.

✨ Features

🤖 Advanced Reasoning

ReAct Pattern: Reasoning + Acting
Chain-of-Thought: Step-by-step reasoning
Tree-of-Thought: Explore multiple paths
Reflexion: Self-improvement loops
Multi-Strategy: Dynamic strategy switching

🤝 Multi-Agent Coordination

Hierarchical: Manager-worker patterns
Peer-to-Peer: Collaborative consensus
Auction-Based: Capability-based bidding
Workflow: Sequential/parallel execution
DAG: Complex dependency resolution

🧠 Memory Systems

Short-Term: Recent context (100 items)
Long-Term: Persistent knowledge
Episodic: Past experiences
Vector: Semantic search (RAG)
Reflection: Insight extraction

🔌 Multi-LLM Support

OpenAI: GPT-4, GPT-3.5 + streaming
Anthropic: Claude 3 (Opus/Sonnet/Haiku)
Azure OpenAI: Enterprise deployment
AWS Bedrock: Claude, Titan, Llama
Local: Ollama, LM Studio, etc.

🔧 Dapr-Native Capabilities

Service Invocation: Call microservices
Pub/Sub: Event-driven messaging
State Management: Persistent storage
Bindings: External system integration
Secrets: Secure credential management

⚡ Production Ready

Planning Engine: Multi-step execution
Code Sandbox: Safe Python/JS execution
Output Parsers: Structured extraction
Checkpointing: State persistence
Observability: Metrics, traces, logs

🚀 Quick Start

Prerequisites

Go 1.21+
Dapr 1.14+
API keys for your LLM provider (OpenAI, Anthropic, etc.)

Installation

# Install Mechano CLI
go install github.com/yasir2000/mechano/cmd/mechano@latest

# Install MCP Server (for AI assistant integration)
go install github.com/yasir2000/mechano/cmd/mechano-mcp@latest

# Initialize Dapr (if not already installed)
dapr init

# Verify installation
mechano version
mechano-mcp --version

Your First Agent

Create my-agent.yaml:

apiVersion: mechano.dev/v1
kind: Agent
metadata:
  name: research-assistant
spec:
  llm:
    provider: openai
    model: gpt-4
    temperature: 0.7
  behavior:
    systemPrompt: "You are a helpful research assistant"
    reasoning:
      strategy: react  # ReAct pattern with reasoning traces
  capabilities:
    - name: search
      type: service-invocation
      config:
        app_id: search-service
        method: search
    - name: save-findings
      type: state
      config:
        store: statestore

Run your agent:

# Start the agent
mechano run my-agent.yaml

# Interact via API
curl -X POST http://localhost:3500/v1.0/invoke/research-assistant/method/execute \
  -H "Content-Type: application/json" \
  -d '{"input": "Research the latest trends in AI agents"}'

📚 Examples

Multi-Agent Team

apiVersion: mechano.dev/v1
kind: AgentTeam
metadata:
  name: content-team
spec:
  coordinator:
    name: editor
    llm:
      provider: openai
      model: gpt-4
  agents:
    - name: researcher
      role: research
    - name: writer
      role: writing
    - name: reviewer
      role: review
  goal: "Create high-quality blog posts"

Planning with DAG

apiVersion: mechano.dev/v1
kind: Plan
metadata:
  name: data-pipeline
spec:
  steps:
    - id: extract
      action: extract-data
      agent: data-agent
    - id: transform
      action: transform-data
      agent: etl-agent
      dependencies: [extract]
    - id: analyze
      action: analyze-data
      agent: analytics-agent
      dependencies: [transform]
    - id: visualize
      action: create-charts
      agent: viz-agent
      dependencies: [analyze]

Vector Memory with RAG

apiVersion: mechano.dev/v1
kind: Agent
metadata:
  name: qa-agent
spec:
  llm:
    provider: anthropic
    model: claude-3-sonnet
  behavior:
    memory:
      type: vector
      enabled: true
      config:
        dimension: 1536
        similarity: cosine
        topK: 5
  capabilities:
    - name: answer
      type: rag
      config:
        chunkSize: 512
        overlap: 50
        rerank: true

Model Context Protocol (MCP) Integration

# Start MCP server for AI assistant integration
mechano-mcp --config mcp-config.json

# Use from Python
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        
        # Create and execute an agent
        await session.call_tool("create_agent", {
            "name": "assistant",
            "spec": {...}
        })
        
        result = await session.call_tool("execute_agent", {
            "agent_name": "assistant",
            "input": "Hello!"
        })

12 MCP Tools Available:

Agent Management: create_agent, list_agents, execute_agent, get_agent_state
Team Coordination: create_team, execute_team
Memory: query_memory, store_memory
Planning: create_plan, execute_plan
Monitoring: get_metrics, get_checkpoints

See MCP Documentation for complete guide.

📦 Official SDKs

Mechano provides official SDKs for 6 programming languages to easily integrate with the MCP server:

Language	Package	Installation	Documentation
Python	`mechano-sdk`	`pip install mechano-sdk`	Python SDK
Go	`mechano/sdk/go`	`go get github.com/yasir2000/mechano/sdk/go`	Go SDK
Java	`mechano-sdk`	Maven/Gradle	Java SDK
Rust	`mechano-sdk`	`cargo add mechano-sdk`	Rust SDK
C#	`Mechano.SDK`	`dotnet add package Mechano.SDK`	C# SDK
PHP	`mechano/sdk`	`composer require mechano/sdk`	PHP SDK

Quick Example (Python):

from mechano_sdk import MechanoClient

client = MechanoClient()
agent = client.create_agent("Research Assistant", "researcher", ["web_search"])
result = client.execute_agent(agent.id, "Research quantum computing")

Quick Example (Go):

import mechano "github.com/yasir2000/mechano/sdk/go"

client := mechano.NewClient("http://localhost:3501")
agent, _ := client.CreateAgent(ctx, "Research Assistant", "researcher", 
    []string{"web_search"}, nil)

See SDK Documentation for comprehensive guides and examples.

📦 SDK Distribution

All SDKs are ready for distribution to their respective package managers.

Build Distributions

Linux/macOS:

chmod +x scripts/build-distributions.sh
./scripts/build-distributions.sh

Windows:

scripts\build-distributions.bat

This creates distribution packages in the dist/ directory:

Python: .whl and .tar.gz
Java: .jar, -sources.jar, -javadoc.jar
Rust: .crate
C#: .nupkg and .snupkg
PHP: .tar.gz

Publishing

See sdk/DISTRIBUTION.md for complete publishing instructions.

Quick publish (with credentials configured):

export PUBLISH_PYTHON=true
export PUBLISH_JAVA=true
export PUBLISH_RUST=true
export PUBLISH_CSHARP=true
./scripts/publish-distributions.sh

Distribution Resources

📖 Distribution Guide - Complete build & publish guide
✅ Release Checklist - Step-by-step release process
📊 Distribution Summary - Package status & statistics
📝 Release Notes - v0.3.0 release notes

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Your Applications                         │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                  Mechano Runtime Layer                       │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │ Agents   │  │ Planning │  │  Memory  │  │Reasoning │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                    Dapr Runtime                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │Service   │  │ Pub/Sub  │  │  State   │  │ Bindings │   │
│  │Invocation│  │          │  │Management│  │          │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
└─────────────────────────────────────────────────────────────┘

🎨 Visual Identity

Mechano's branding is inspired by Dapr, featuring:

Colors: Blue (#0d6efd) → Purple (#6f42c1) gradient
Icon: ⚙️ Mechanical gear with neural network pattern
Typography: Modern, technical sans-serif (Inter)

See BRANDING.md for complete brand guidelines.

📖 Documentation

Getting Started - Installation and first steps
DSL Reference - Complete YAML specification
API Documentation - REST and gRPC APIs
Examples - Real-world use cases
Architecture - System design
Contributing - Development guide

🧪 Testing

# Run all tests
make test

# Run specific test suite
go test ./test/e2e/...

# Run with coverage
make test-coverage

# Run benchmarks
make benchmark

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone repository
git clone https://github.com/yasir2000/mechano.git
cd mechano

# Install dependencies
go mod download

# Build
make build

# Run tests
make test

# Run linting
make lint

Mechano is an open-source project that requires significant time and resources to maintain. Your sponsorship helps us:

🚀 Develop new features faster
🐛 Fix bugs and improve stability
📚 Create better documentation
🎓 Provide community support
🔒 Maintain security updates

Sponsorship Tiers

🥉 Bronze

$10/month
✓ Sponsor badge
✓ Logo on README
✓ Priority support

🥈 Silver

$50/month
✓ All Bronze benefits
✓ Logo on website
✓ Feature requests

🥇 Gold

$250/month
✓ All Silver benefits
✓ Priority bug fixes
✓ Direct support channel

💎 Platinum

$1000/month
✓ All Gold benefits
✓ Custom features
✓ Dedicated support

Become a Sponsor on GitHub ❤️

Current Sponsors

Become our first sponsor!

Other Ways to Support

⭐ Star this repository - Help us reach more developers
🐦 Share on social media - Spread the word about Mechano
📝 Write tutorials - Help others learn Mechano
🐛 Report bugs - Help us improve quality
💡 Suggest features - Shape the future of Mechano

📦 Ecosystem

Official Packages

@mechano/cli - Command-line interface
@mechano/sdk - Go SDK for Mechano
@mechano/python - Python bindings
@mechano/ui - Web-based visual designer

Community

Discord - Chat with the community
GitHub Discussions - Ask questions
Stack Overflow - Get help
Twitter - Follow updates

📊 Stats

GitHub contributors GitHub last commit GitHub issues GitHub pull requests

📄 License

Mechano is licensed under the Apache License 2.0.

🙏 Acknowledgments

Dapr - For the amazing distributed runtime
LangChain - For pioneering agent frameworks
CrewAI - For multi-agent coordination patterns
AutoGen - For conversation-driven agents

🔗 Links

Website: mechano.dev
Documentation: mechano.dev/docs
GitHub: github.com/yasir2000/mechano
Docker Hub: hub.docker.com/r/yasir2000/mechano
NPM: @mechano/cli

Made with ❤️ by the Mechano community

Report Bug • Request Feature • Join Discord

Directories ¶

Path	Synopsis
cmd
mechano command
mechano-mcp command
mechano-runtime command
mechano/commands
mcp
config
server
tools
pkg
agent
agent/capabilities
checkpoint
coordination
dsl
llm
llm/openai
memory
observability
parser
planning
reasoning
runtime
sandbox
version

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL