daimyo 1.0.0

Rules server for agents with REST and MCP interfaces

Daimyo - Rules Server for Agents

A Python server providing rules to AI agents through REST and MCP interfaces. Supports scope-based rules with inheritance, categories for filtering, and server federation for distributed rule management.

Features

• Multiple Interfaces: REST API, MCP (Model Context Protocol), and CLI
• Scope Inheritance: Single and multiple parent inheritance with priority-based conflict resolution
• Rule Types: Commandments (MUST) and Suggestions (SHOULD)
• Categories: Organize rules into hierarchical categories for selective retrieval
• Server Federation: Distribute scopes across multiple servers with automatic merging
• Multiple Formats: Output as YAML, JSON, or Markdown
• Clean Architecture: Domain-driven design with clear separation of concerns

Installation

pip install daimyo

Or install from source:

git clone https://gitlab.com/Kencho1/daimyo.git
cd daimyo
pip install -e .

Quick Start

1. Set Up Your Rules

cp -r example-daimyo-rules daimyo-rules

2. Start the Server

daimyo serve

3. Access the API

Visit http://localhost:8000/docs for interactive API documentation.

curl http://localhost:8000/api/v1/scopes/python-general/rules

Core Concepts

Scopes

Scopes represent organizational contexts (company, team, project). Each scope is a directory containing:

• metadata.yml - Scope configuration and parent references
• commandments.yml - Mandatory rules (MUST)
• suggestions.yml - Recommended rules (SHOULD)

daimyo-rules/
├── python-general/
│   ├── metadata.yml
│   ├── commandments.yml
│   └── suggestions.yml
└── team-backend/
    ├── metadata.yml
    ├── commandments.yml
    └── suggestions.yml

Metadata Format

name: scope-name
description: Human-readable description
parents:
  - parent-scope-1
  - parent-scope-2
tags:
  team: backend
  language: python

Fields:

• name: Scope identifier (must match directory name)
• description: Human-readable description
• parents: List of parent scopes (first = highest priority)
• tags: Key-value pairs for categorization

Categories

Categories are hierarchical subdivisions within rules:

python.web.testing:
  when: When testing web interfaces
  ruleset:
    - Use playwright for acceptance tests
    - Use pytest fixtures for test setup

Rule Types

Commandments (MUST): Mandatory rules that accumulate through inheritance

Suggestions (SHOULD): Recommended rules that can be overridden or appended with + prefix

Usage

REST API

Start the server:

daimyo serve
daimyo serve --host 0.0.0.0 --port 8080

Get rules:

curl http://localhost:8000/api/v1/scopes/python-general/rules

curl -H "Accept: application/json" \
  http://localhost:8000/api/v1/scopes/python-general/rules

curl -H "Accept: text/markdown" \
  http://localhost:8000/api/v1/scopes/python-general/rules

Filter by categories:

curl "http://localhost:8000/api/v1/scopes/team-backend/rules?categories=python.web,python.testing"

MCP Server

Start the MCP server:

daimyo mcp
daimyo mcp --transport sse

Available tools:

• get_rules(scope_name, categories?) - Get formatted rules
• list_scopes() - List available scopes
• apply_scope_rules(scope_name, categories?) - Get prompt template with rules

CLI Commands

daimyo list-scopes
daimyo show python-general
daimyo --version

Configuration

Configuration is managed via config/settings.toml or environment variables:

[default]
rules_path = "./daimyo-rules"
console_log_level = "WARNING"
file_log_level = "INFO"
max_inheritance_depth = 10
master_server_url = ""
remote_timeout_seconds = 5
rest_port = 8000

Override with environment variables:

export DAIMYO_RULES_PATH="/custom/rules/path"
export DAIMYO_MASTER_SERVER_URL="http://master.example.com:8000"
export DAIMYO_CONSOLE_LOG_LEVEL="DEBUG"

Examples

The example-daimyo-rules/ directory contains working examples:

python-general

Base Python development rules with categories for core practices, testing, security, and documentation.

python-fastapi

FastAPI framework rules extending python-general with routing, async patterns, and performance optimization.

team-backend

Backend team rules extending python-general with REST API patterns, database access, and deployment considerations.

project-api

Demonstrates multiple parent inheritance with parents: [team-backend, python-fastapi]:

• Combines team-specific and technology-specific rules
• Shows priority-based conflict resolution
• Uses + prefix to append to parent rules

Advanced Topics

Multiple Parent Inheritance

parents:
  - high-priority
  - low-priority

Commandments: All rules from all parents are combined (additive)

Suggestions: First parent wins in conflicts; use + prefix to append instead of replace

Server Federation

Configure a master server for distributed scope management:

export DAIMYO_MASTER_SERVER_URL="http://master.example.com:8000"

The system will:

1. Look for scopes locally
2. Look for scopes on the master server
3. Merge both if found in both locations (local extends remote)

Scope Sharding

The same scope name can exist on both master server and locally. When both exist, they are merged with the remote version as the base and the local version extending it.

Development

Running Tests

pip install -e ".[dev]"
pytest
pytest --cov=daimyo

Code Quality

mypy daimyo
ruff check daimyo
ruff format daimyo

License

MIT