{"id":48902643,"url":"https://github.com/tyabu12/hamoru","last_synced_at":"2026-04-16T16:30:49.077Z","repository":{"id":347587050,"uuid":"1194282640","full_name":"tyabu12/hamoru","owner":"tyabu12","description":"\"Terraform for LLMs.\" Declaratively orchestrate multiple LLM providers in harmony, with policy-based model selection and cost impact prediction. Named after Japanese ハモる (to harmonize) — because your LLMs should sing together, not solo.","archived":false,"fork":false,"pushed_at":"2026-03-28T17:07:44.000Z","size":186,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-28T17:11:17.551Z","etag":null,"topics":["agent-collaboration","ai","anthropic","async","cli","cost-optimization","declarative","developer-tools","llm","llm-orchestration","multi-provider","openai","openai-compatible","policy-engine","rust","tokio","workflow-engine"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tyabu12.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-28T06:17:57.000Z","updated_at":"2026-03-28T16:36:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tyabu12/hamoru","commit_stats":null,"previous_names":["tyabu12/hamoru"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/tyabu12/hamoru","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tyabu12%2Fhamoru","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tyabu12%2Fhamoru/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tyabu12%2Fhamoru/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tyabu12%2Fhamoru/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tyabu12","download_url":"https://codeload.github.com/tyabu12/hamoru/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tyabu12%2Fhamoru/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31894713,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T11:36:10.202Z","status":"ssl_error","status_checked_at":"2026-04-16T11:36:09.652Z","response_time":69,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5: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":["agent-collaboration","ai","anthropic","async","cli","cost-optimization","declarative","developer-tools","llm","llm-orchestration","multi-provider","openai","openai-compatible","policy-engine","rust","tokio","workflow-engine"],"created_at":"2026-04-16T16:30:48.045Z","updated_at":"2026-04-16T16:30:49.071Z","avatar_url":"https://github.com/tyabu12.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# 🎶 hamoru\n\n**\"Terraform for LLMs.\"**\n\nDeclaratively orchestrate multiple LLM providers in harmony,\\\nwith policy-based model selection and cost impact prediction.\n\n*Named after Japanese ハモる (to harmonize)*\\\n*— because your LLMs should sing together, not solo.*\n\n[![CI](https://github.com/tyabu12/hamoru/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/tyabu12/hamoru/actions/workflows/ci.yml)\n[![Security Audit](https://github.com/tyabu12/hamoru/actions/workflows/security.yml/badge.svg?branch=main)](https://github.com/tyabu12/hamoru/actions/workflows/security.yml)\n[![coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/tyabu12/8c8891a593f77b776e5d672b8dd8ab2c/raw/hamoru-coverage.json)](https://gist.github.com/tyabu12/8c8891a593f77b776e5d672b8dd8ab2c)\n\n\u003c/div\u003e\n\n\u003e 🚧 **This project is under active development and is not production-ready.** 🚧\n\u003e\n\u003e Use at your own risk. APIs and configuration formats may change without notice.\n\n## 🎯 Current Phase\n\n**Phase 5: API Server (serve)**\n\nSee [design-plan.md](docs/design-plan.md) for the full roadmap.\n\n## ✨ Key Differentiators\n\n1. 🎼 **Declarative Agent Collaboration** — Define LLM collaboration patterns (Generator/Evaluator, Pipeline, Debate) in YAML\n2. ⚖️ **Policy as Code** — Intent-based model selection: `tags: [review] → quality-first policy → Opus auto-selected`\n3. 🔮 **Cost Impact Prediction** — `hamoru plan` simulates cost changes before applying policy updates\n\n## 🔌 Supported Providers\n\n| Provider | Type | Models (built-in catalog) | Status |\n|----------|------|---------------------------|--------|\n| [Anthropic](https://platform.claude.com/docs/en/home) | Cloud API | `claude-sonnet-4-6`, `claude-haiku-4-5` | ✅ |\n| [DeepSeek](https://api-docs.deepseek.com/) | OpenAI-compatible | — | 🔲 Planned (post-v1.0) |\n| [Google Gemini](https://ai.google.dev/gemini-api/docs) | Cloud API | — | 🔲 Planned (post-v1.0) |\n| [Groq](https://console.groq.com/docs/overview) | OpenAI-compatible | — | 🔲 Planned (post-v1.0) |\n| [Ollama](https://ollama.com) | Local | `llama3.3:70b`, `qwen2.5-coder:14b` | ✅ |\n| [OpenAI](https://platform.openai.com/docs) | Cloud API | — | 🔲 Planned (post-v1.0) |\n\n\u003e Models listed above are from the built-in catalog with default pricing. You can configure any model your provider supports via `hamoru.yaml` — including custom cost overrides.\n\u003e\n\u003e Providers marked **OpenAI-compatible** will use the OpenAI adapter with a custom `base_url`. Any OpenAI-compatible API (Mistral, Together, Fireworks, etc.) can be configured the same way.\n\n## 🏗️ Architecture\n\n```\n┌──────────────────────────────────────────────────────────┐\n│                    User Interface                         │\n│  CLI: hamoru plan / apply / serve / status                │\n│  REST: OpenAI-compatible API (POST /v1/chat/completions)  │\n├──────────────────────────────────────────────────────────┤\n│  Layer 5: Agent Collaboration Engine          [NEW]       │\n│  Declarative agent definitions (YAML)                     │\n│  Patterns: Generator/Evaluator, Pipeline, Debate          │\n│  Harness: cost caps, timeouts, quality gates              │\n├──────────────────────────────────────────────────────────┤\n│  Layer 4: Orchestration Engine                            │\n│  Workflow definitions (YAML) → step DAG execution         │\n│  Branching (Tool Calling / STATUS line), loops, parallel  │\n├──────────────────────────────────────────────────────────┤\n│  Layer 3: Policy Engine                                   │\n│  Declarative policies: cost caps / quality / latency      │\n│  Task intent (tags) → policy matching → model selection   │\n├──────────────────────────────────────────────────────────┤\n│  Layer 2: Provider Abstraction                            │\n│  Unified trait: LlmProvider (direct impl w/ reqwest+serde)│\n│  Adapters: Claude API / Ollama → later: OpenAI / Gemini   │\n├──────────────────────────────────────────────────────────┤\n│  Layer 1: Configuration \u0026 Telemetry                       │\n│  Configuration: YAML (Git-managed, Hot Reload)            │\n│  Telemetry: execution history / cost (InMemory→SQLite→S3) │\n│  plan (Telemetry-based cost impact prediction)            │\n└──────────────────────────────────────────────────────────┘\n```\n\n## 📋 Prerequisites\n\n- [Rust](https://rustup.rs/) stable toolchain (`clippy` and `rustfmt` components)\n\n## 🚀 Quick Start\n\n```bash\ncargo build\ncargo run --bin hamoru -- init\n```\n\n### 🏠 Option A: Local LLM (no API key required)\n\nInstall [Ollama](https://ollama.com), then add it to your config (`.hamoru/hamoru.yaml`).  \nWe use `llama3.2` (3B, ~2 GB) here for a quick first run — you can swap in any model Ollama supports:\n\n```yaml\nproviders:\n  - name: local\n    type: ollama\n    endpoint: http://localhost:11434\n    models:\n      - llama3.2\n```\n\n```bash\nollama pull llama3.2\ncargo run --bin hamoru -- providers test\ncargo run --bin hamoru -- run -m local:llama3.2 \"Hello, world!\"\n```\n\n### ☁️ Option B: Cloud LLM (API key required)\n\nSet your API key as an environment variable:\n\n```bash\n# Recommended: read without echoing to avoid shell history leakage\nprintf \"Enter API key: \" \u0026\u0026 read -rs HAMORU_ANTHROPIC_API_KEY \u0026\u0026 export HAMORU_ANTHROPIC_API_KEY\necho  # newline after silent input\n```\n\n\u003e **Security note:** Avoid typing API keys directly in commands (e.g., `export KEY=sk-ant-...`) — they may be saved in your shell history file. Use `read -rs` as shown above, or load from a secrets manager.\n\n```bash\ncargo run --bin hamoru -- providers test\ncargo run --bin hamoru -- run -m claude:claude-sonnet-4-6 \"Hello, world!\"\n```\n\n### More examples\n\n```bash\n# Policy-based model selection\ncargo run --bin hamoru -- run -p cost-optimized \"Summarize this text\"\n\n# Tag-based routing\ncargo run --bin hamoru -- run --tags review \"Review this code for security issues\"\n\n# Multi-step workflow\ncargo run --bin hamoru -- run -w workflow.yaml \"Implement an auth API\"\n```\n\n### 🌐 OpenAI-compatible API server\n\n```bash\n# Start the server (localhost:3000 by default)\nHAMORU_API_KEYS=my-secret-key cargo run --bin hamoru -- serve\n\n# In another terminal — use any OpenAI-compatible client\ncurl http://localhost:3000/v1/models \\\n  -H \"Authorization: Bearer my-secret-key\"\n\ncurl http://localhost:3000/v1/chat/completions \\\n  -H \"Authorization: Bearer my-secret-key\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"model\": \"claude:claude-sonnet-4-6\",\n    \"messages\": [{\"role\": \"user\", \"content\": \"Hello!\"}]\n  }'\n```\n\n\u003e **Tip:** Omit `HAMORU_API_KEYS` to skip authentication (convenient for local dev).\n\u003e Use `--port` and `--bind` to customize the listen address.\n\n## 🔑 Environment Variables\n\n| Variable | Provider | Status |\n|----------|----------|--------|\n| `HAMORU_API_KEYS` | hamoru serve (API auth) | ✅ |\n| `HAMORU_ANTHROPIC_API_KEY` | Anthropic | ✅ |\n| `HAMORU_DEEPSEEK_API_KEY` | DeepSeek | 🔲 Planned (post-v1.0) |\n| `HAMORU_GEMINI_API_KEY` | Google Gemini | 🔲 Planned (post-v1.0) |\n| `HAMORU_GROQ_API_KEY` | Groq | 🔲 Planned (post-v1.0) |\n| `HAMORU_OPENAI_API_KEY` | OpenAI | 🔲 Planned (post-v1.0) |\n\n\u003e Ollama runs locally and does not require an API key.\n\n## 📖 Commands\n\n### Top-level commands\n\n| Command | Description | Status |\n|---------|-------------|--------|\n| `hamoru init` | Initialize project (creates `.hamoru/` with config templates) | ✅ |\n| `hamoru run \u003cprompt\u003e` | Execute a prompt, workflow, or collaboration | ✅ |\n| `hamoru plan` | Telemetry-based cost impact prediction | ✅ |\n| `hamoru metrics --period 7d` | View cost and performance metrics | ✅ |\n| `hamoru providers list` | List configured providers and their models | ✅ |\n| `hamoru providers test` | Test connectivity to all configured providers | ✅ |\n| `hamoru telemetry show` | Show telemetry store details | ✅ |\n| `hamoru telemetry pull` | Sync telemetry from remote storage | 🔲 Planned (remote config) |\n| `hamoru telemetry push` | Sync telemetry to remote storage | 🔲 Planned (remote config) |\n| `hamoru status` | Show current configuration overview | 🔲 Planned |\n| `hamoru serve` | Start OpenAI-compatible API server | ✅ |\n| `hamoru agents list` | List agent definitions | 🔲 Planned (Phase 6) |\n| `hamoru agents test \u003cname\u003e` | Dry-run a collaboration pattern | 🔲 Planned (Phase 6) |\n\n### `hamoru run` options\n\n| Flag | Description | Status |\n|------|-------------|--------|\n| `-m provider:model` | Direct model selection (e.g., `claude:claude-sonnet-4-6`) | ✅ |\n| `-p policy-name` | Policy-based model selection (e.g., `cost-optimized`) | ✅ |\n| `--tags tag1,tag2` | Tag-based routing (can combine with `-p`) | ✅ |\n| `-w workflow.yaml` | Execute a multi-step workflow from YAML | ✅ |\n| `-a collaboration` | Execute an agent collaboration pattern | 🔲 Planned (Phase 6) |\n| `--no-stream` | Disable streaming (print full response at once) | ✅ |\n\n## 🛠️ Development\n\n```bash\n# Run tests\ncargo test --all-targets\n\n# Check code quality\ncargo clippy --all-targets -- -D warnings\ncargo fmt --all --check\n```\n\n### E2E smoke test\n\n```bash\n# Offline only (no API key or Ollama needed)\nbash scripts/smoke-test.sh --offline\n\n# Auto-detect (runs Anthropic tests if API key is set, Ollama tests if server is running)\nbash scripts/smoke-test.sh\n\n# With Anthropic API tests\nprintf \"API key: \" \u0026\u0026 read -rs HAMORU_ANTHROPIC_API_KEY \u0026\u0026 export HAMORU_ANTHROPIC_API_KEY\nbash scripts/smoke-test.sh\n\n# With Ollama tests (start Ollama in a separate terminal first)\n# Terminal 1: ollama serve\n# Terminal 2:\nollama pull qwen2.5:0.5b  # recommended: lightweight (~400MB), responds in seconds\nbash scripts/smoke-test.sh\n\n# Verbose output (show stdout/stderr for all tests)\nbash scripts/smoke-test.sh --verbose\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for full development setup and coding rules.\n\n## 📁 Project Structure\n\n```\nhamoru/\n├── crates/\n│   ├── hamoru-core/          # Core library\n│   │   └── src/\n│   │       ├── provider/     # Layer 2: LLM provider adapters\n│   │       ├── telemetry/    # Layer 1: Execution history \u0026 metrics\n│   │       ├── config/       # Layer 1: YAML config loading\n│   │       ├── policy/       # Layer 3: Policy engine\n│   │       ├── orchestrator/ # Layer 4: Workflow execution\n│   │       ├── agents/       # Layer 5: Agent collaboration (planned)\n│   │       ├── server/       # API layer: OpenAI wire types, namespace, translation\n│   │       └── error.rs      # Unified error types\n│   └── hamoru-cli/           # CLI entry point\n├── docs/\n│   ├── design-plan.md        # Detailed design document\n│   └── decisions/            # Architecture Decision Records\n├── CLAUDE.md                 # Project context for Claude Code\n├── CONTRIBUTING.md           # Development guidelines\n└── SECURITY.md               # Security policy\n```\n\n## 📄 License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftyabu12%2Fhamoru","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftyabu12%2Fhamoru","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftyabu12%2Fhamoru/lists"}