Mirai Shared Skills Architecture — ADR-to-Module Map¶
This document maps each of the 8 architectural decisions to the concrete modules that implement them. It complements overview.md (package layout and per-skill data flow) and adrs.md (decision rationale).
High-level topology¶
┌───────────────────────────────────────────────────────────────────────────────┐
│ mirai-agent-core │
│ SemanticRouter ──► ephemeral Pydantic AI Agent ──► tool dispatch │
│ │ │
│ ▼ active_skills (BaseSkill objects) │
└───────────────────────────────┬───────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────────────────────┐
│ mirai-shared-skills │
│ │
│ ┌─────────────────────┐ │
│ │ _registry.py │ SkillCategory, SkillDescriptor (ADR-0001/0004) │
│ │ __init__.bootstrap│ │
│ └──────────┬──────────┘ │
│ │ import-time descriptor registration │
│ ▼ │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ Standard skills │ │ Raw skills │ │
│ │ ─ discovery │ │ ─ execution │ category="raw" │
│ │ ─ auth_gates │ │ ─ database │ must wrap before use │
│ │ ─ browser │ │ │ (ADR-0001) │
│ │ ─ pdf_extraction │ │ │ │
│ │ ─ agentic_rag │ │ │ │
│ │ ─ weather │ │ │ │
│ └──────────┬──────────┘ └──────────┬──────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ Tool objects via tool_from_function (ADR-0007) │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
│ agentic_rag specifically: │
│ ┌─────────────────────┐ │
│ │ providers/ │ GraphProvider, VectorSearchProvider, │
│ │ Neo4j / Azure / │ WebSearchProvider, RerankerProvider │
│ │ Browser / Cohere │ (ADR-0002, gated by extras per ADR-0003) │
│ └─────────────────────┘ │
└───────────────────────────────┬───────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────────────────────┐
│ Downstream client │
│ SecureSkill(skill, policy={...}) per agent-core ADR-0012 │
│ wraps every shipped skill before reaching an agent │
└───────────────────────────────────────────────────────────────────────────────┘
ADR → Module map¶
| ADR | Decision | Primary modules |
|---|---|---|
| 001 | Standard vs Raw Skill Categorization | mirai_shared_skills/_registry.py — SkillCategory, SkillDescriptor.category. mirai_shared_skills/__init__.py — descriptor category field on every bootstrap() entry. mirai_shared_skills/execution/skill.py and mirai_shared_skills/database.py — the two raw skills. |
| 002 | Pluggable Provider Pattern for Multi-Source Retrieval | mirai_shared_skills/agentic_rag/providers/ — four Protocol types and concrete providers. mirai_shared_skills/agentic_rag/skill.py — orchestration accepting providers by construction. |
| 003 | Optional-Dependency Extras for Backend Drivers | pyproject.toml — [project.optional-dependencies]: neo4j, azure, reranker, rag, eval. mirai_shared_skills/agentic_rag/providers/neo4j_graph.py — Neo4jUnavailableError typed-error pattern. |
| 004 | In-Process Skill Descriptor Registry | mirai_shared_skills/_registry.py — register/get/find/all_descriptors/bootstrap. mirai_shared_skills/__init__.py — single bootstrap([...]) call site. mirai_shared_skills/discovery/skill.py — SkillDiscoverySkill, the registry's primary consumer. |
| 005 | Authentication Gates as a Capability Skill | mirai_shared_skills/auth_gates/skill.py — AuthenticationGatesSkill, inspect_status_code, request_credential_handoff, CredentialHandoff Pydantic model. |
| 006 | Token-Budgeted RAG Context Assembly | mirai_shared_skills/agentic_rag/skill.py — DEFAULT_TOKEN_BUDGET, APPROX_CHARS_PER_TOKEN, DEFAULT_CITATION_SAFETY_BUFFER_TOKENS, estimate_citation_tokens. |
| 007 | Functional Tool Construction via tool_from_function |
Every skill.py in the package; the from mirai_core.capabilities.tools import Tool, tool_from_function import pattern is canonical. |
| 008 | References-as-Files for Lazy Instructional Payloads | mirai_shared_skills/discovery/skill.py — load_skill_instructions. mirai_shared_skills/_registry.py — SkillDescriptor.references. Per-subpackage references/ dirs (e.g. agentic_rag/references/azure_search_config.md). |
Catalog vs runtime: division of responsibility¶
The catalog answers: what does this skill do, and what's its safety profile by construction?
The runtime (per agent-core ADR-0012) answers: for this specific client, in this specific environment, what's the per-tool security level — SAFE, REQUIRES_HITL, or BLOCKED?
Concretely, that means:
SkillDescriptor.category(standard|raw) lives in this catalog. It's a property of the skill's primitives, not of any client's policy.SecurityLevel(SAFE|REQUIRES_HITL|BLOCKED) and theSecureSkillwrapper live inmirai-agent-core, applied by each downstream client.
A raw skill (e.g. RawDatabaseSkill) MUST be wrapped in SecureSkill before it reaches an agent. A standard skill MAY be wrapped for defense in depth but doesn't require it.
Configuration toggles¶
Most skills are config-light. The handful with real configuration are listed here:
| Skill / provider | Variable | Purpose |
|---|---|---|
Neo4jGraphProvider |
NEO4J_URI, NEO4J_USER, NEO4J_PASSWORD |
Connection to Neo4j 5.x. Provider raises Neo4jUnavailableError if [neo4j] extra missing. |
AzureSearchProvider |
AZURE_SEARCH_ENDPOINT, AZURE_SEARCH_API_KEY, AZURE_SEARCH_INDEX |
Azure AI Search index. [azure] extra required. |
Cohere reranker |
COHERE_API_KEY |
Cohere Rerank v4. [reranker] extra required. |
WeatherSkill |
WEATHER_API_KEY (provider-dependent) |
Public weather API auth. |
RawDatabaseSkill |
DATABASE_URL |
SQLAlchemy-style URL. |
Detailed install + troubleshooting guidance: see the Provider Configuration guide.
Test commands¶
# Lint + format
uv run ruff check . && uv run ruff format --check .
# Strict type-check
uv run mypy mirai_shared_skills tests
# Unit tests (no live backends)
uv run pytest tests/
# Integration tests with all extras (requires Docker for Neo4j)
uv sync --all-extras
docker compose -f docker-compose.test.yml up -d
uv run pytest tests/ -m integration
# Docs build (caught in CI as well)
uv run mkdocs build --strict