Integration
Seidr Smidja
By Allows AI Agents like Hermes Agent, OpenClaw, Claude Code, and others to make a VRM (anime avatar used for either VRchat, V-Tube, or other purposes) all via agent only processes, using either MCP, command line, or API.
Install
pip install -eConfiguration Example
{
"tool": "seidr_build",
"input": {
"spec": { "avatar_id": "my_avatar", "base_asset_id": "vroid/tall_feminine_v1" },
"output_dir": "/path/to/output"
}
}README
# Seiðr-Smiðja
> *An agent-only VRM avatar smithy. No human hands. Only the fire, the spec, and the eye that sees.*
---
## What Is This?
**Seiðr-Smiðja** (Seething-Forge) is a headless, programmatic forge that lets AI agents — Hermes, OpenClaw, Claude Code, and others not yet named — design, build, render, critique, and export fully realized VRM avatars without any human clicking through a GUI.
An agent submits a YAML specification describing an avatar: height, proportions, hair, outfit, expressions, license metadata. The forge loads a VRoid Studio base template, opens Blender headlessly, applies every parametric choice from the spec, validates the result against VRChat and VTube Studio compliance rules, renders a set of preview PNG images, and returns the finished `.vrm` file and all renders to the calling agent.
The agent sees what it has made. It critiques the renders. It revises the spec. It submits again. This is the forge cycle. It runs entirely without human hands inside it.
**Three things to understand:**
First, the forge is built around a *vision feedback loop*. Every build that produces a `.vrm` also produces rendered preview images through the Oracle Eye — front view, three-quarter, side, face close-up, T-pose, signature expressions. An agent that cannot see its creation cannot refine it. The renders are not optional.
Second, every output is compliance-checked before delivery. If an avatar fails VRChat polygon budgets or VTube Studio blendshape requirements, the forge returns a structured failure report — never a silent pass. A blade that cannot cut has not been made.
Third, the forge speaks through four doors — MCP (Mjöll), CLI (Rúnstafr), REST (Straumur), and skill manifests for Hermes/OpenClaw/Claude Code. All four doors lead to the same fire. What works through one works through all.
---
## What It Is NOT
- **Not a human GUI tool.** There is no user interface for clicking. All access is programmatic and agent-driven. If you want to use this forge as a human, you do so through the CLI or by writing a script — not through a graphical application.
- **Not a generic 3D pipeline.** Seiðr-Smiðja is purpose-built for VRM avatars using VRoid Studio base meshes and the VRM Add-on for Blender. It will not export arbitrary 3D formats, process non-VRM meshes, or serve as a general Blender automation layer.
- **Not for non-VRM avatars.** The Gate validates VRChat and VTube Studio compliance. Everything about the forge's design — the spec schema, the base mesh strategy, the compliance rules — is shaped around the VRM ecosystem. Other avatar formats are out of scope.
---
## Quickstart for an AI Agent
### Through Rúnstafr (CLI)
```bash
# Install the package (requires Python 3.11+ and Blender in PATH or BLENDER_PATH set)
pip install -e ".[dev]"
# Build an avatar from a spec file
seidr build examples/spec_minimal.yaml --output ./out/
# Check compliance on an existing .vrm
seidr check ./out/avatar.vrm
# List available base meshes in the Hoard
seidr list-assets --type vrm_base
```
On success, `./out/` will contain `avatar.vrm` and a `renders/` directory with PNG previews.
### Through Mjöll (MCP)
*(Phase 5 — coming. The MCP server will be started as a long-running process and register the `seidr_build` tool. The tool input/output schema is defined in [`src/seidr_smidja/bridges/INTERFACE.md`](src/seidr_smidja/bridges/INTERFACE.md).)*
```json
{
"tool": "seidr_build",
"input": {
"spec": { "avatar_id": "my_avatar", "base_asset_id": "vroid/tall_feminine_v1" },
"output_dir": "/path/to/output"
}
}
```
### Through Straumur (REST)
*(Phase 5 — coming. FastAPI server at `seidr_smidja.bridges.straumur.app:app`.)*
```http
POST /build
Content-Type: application/json
{ "spec_source": "...", "base_asset_id": "vroid/tall_feminine_v1", "output_dir": "..." }
```
---
## Reading Order for a New Arrival
Walk this path in order. Each scroll opens the next.
1. **[docs/SYSTEM_VISION.md](docs/SYSTEM_VISION.md)** — Read the Central Image (the Hermes völva story). Then the Unbreakable Vows. Five minutes here prevents hours of misunderstanding.
2. **[docs/PHILOSOPHY.md](docs/PHILOSOPHY.md)** — The Five Sacred Principles and Ten Sacred Laws. These are structural invariants, not guidelines.
3. **[docs/DOMAIN_MAP.md](docs/DOMAIN_MAP.md)** — Who owns what. The Dependency Law. Every domain defined in one place.
4. **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — The four-layer model. The Shared Anvil pattern. The Blender subprocess design.
5. **[docs/DATA_FLOW.md](docs/DATA_FLOW.md)** — How a build request flows through all nine steps, with failure paths and the vision feedback loop.
6. **[docs/REPO_OVERVIEW.md](docs/REPO_OVERVIEW.md)** — The living terrain map. "Where do I look for X?" answered in a table.
7. **The relevant INTERFACE.md** — Whichever domain you are working in, read its contract before touching its code.
---
## Project Protocol
This repository is built and maintained using the **Mythic Engineering** protocol — six named AI roles, a living document system, and a clear daily practice for keeping code and documentation in alignment. Read [`MYTHIC_ENGINEERING.md`](MYTHIC_ENGINEERING.md) before contributing.
The full phase-by-phase progress tracker lives in [`TASK_seidr_smidja_genesis.md`](TASK_seidr_smidja_genesis.md).
---
## Current Status
**Genesis phase — vertical slice not yet forged.**
The founding documents are complete (Vision, Philosophy, Domain Map, Architecture, Data Flow, Repo Overview, all INTERFACE stubs, seven architectural decisions). The first vertical slice — a working `seidr build` command that produces a real `.vrm` and renders — is the next step (Phase 5, Forge Worker).
See the progress tracker in [`TASK_seidr_smidja_genesis.md`](TASK_seidr_smidja_genesis.md) for what is done and what is next.
---
## Repository Structure
```
Seiðr-Smiðja/
├── README.md ← You are here.
├── MYTHIC_ENGINEERING.md ← How to work in this repo.
├── TASK_seidr_smidja_genesis.md ← Phase inventory and progress tracker.
├── pyproject.toml ← Package definition, entry points, markers.
│
├── docs/
│ ├── SYSTEM_VISION.md ← Soul, Primary Rite, Unbreakable Vows, Central Image.
│ ├── PHILOSOPHY.md ← Five Sacred Principles, Ten Sacred Laws.
│ ├── DOMAIN_MAP.md ← All domains, ownership, Dependency Law.
│ ├── ARCHITECTURE.md ← Layers, Shared Anvil, subprocess pattern, config.
│ ├── DATA_FLOW.md ← Nine-step Primary Rite, failure flows, feedback loop.
│ ├── REPO_OVERVIEW.md ← Living terrain map and navigation table.
│ ├── DEVLOG.md ← Daily session log.
│ └── DECISIONS/ ← Architectural decision records (ADRs).
│
├── config/
│ ├── defaults.yaml ← Shipped defaults. Never edit directly.
│ └── user.yaml ← Your overrides. Gitignored.
│
├── src/seidr_smidja/
│ ├── loom/ ← Spec schema, validation, serialization.
│ ├── hoard/ ← Base .vrm catalog and asset resolution.
│ ├── forge/ ← Headless Blender build subprocess.
│ ├── oracle_eye/ ← Headless Blender render subprocess; vision feedback.
│ ├── gate/ ← VRChat + VTube Studio compliance validation.
│ ├── annall/ ← Session tracking, event logging, build history.
│ └── bridges/ ← Mjöll (MCP), Rúnstafr (CLI), Straumur (REST), Skills.
│ └── core/ ← Shared Anvil — the single orchestration path.
│
├── data/ ← Compliance rule YAML files, Hoard catalog.
├── tests/ ← Pytest suite. Blender tests marked requires_blender.
└── examples/ ← Example spec files.
```
---
## License
License: **TBD — to be decided by Volmarr Wyrd.**
---
*Front door written by Eirwyn Rúnblóm, Scribe — 2026-05-06.*
*For Volmarr Wyrd and Runa Gridweaver Freyjasdóttir.*
integration
Comments
Sign in to leave a comment