This guide covers all API, configuration, and behavioral changes introduced between v0.3.0 (Phase 4) and v0.7.0 (Phase 15).
Before (v0.3.0):
from hamr.core.models import CharacterSpec
spec = CharacterSpec(...)After (v0.7.0-rc1):
from hamr.core.spec import Spec
spec = Spec.from_yaml("character.yaml")
# CharacterSpec is still a data model, but Spec is the canonical entry pointBefore (v0.3.0): Build was an ad-hoc series of function calls in
build_avatar.py with no stage numbering, timing, or error recovery.
After (v0.7.0-rc1):
from hamr.core.pipeline import BuildPipeline
pipeline = BuildPipeline()
result = pipeline.build(spec) # Returns PipelineResult
# result.stages — per-stage timing, success/failure
# result.success — overall build status
# result timing, output_size, diagnostics- 14 explicit numbered stages (0–13)
- Per-stage timing and
BuildResulttracking --skip-stages hair,clothingfor targeted debuggingPerfBudgetintegration at pipeline start and end
The following modules were introduced in Phases 11–14:
| Module | Class / Function | Since |
|---|---|---|
hamr.core.pipeline |
BuildPipeline, PipelineResult |
v0.5.0 |
hamr.core.perf |
PerfBudget, PerfTracker |
v0.4.0 |
hamr.core.presets |
PresetLoader |
v0.4.0 |
hamr.core.validate |
spec_to_dict() |
v0.6.0 |
hamr.core.gpu_profiles |
GPUProfiler |
v0.6.0 |
hamr.core.a11y |
Accessibility & CLI flags | v0.6.0 |
hamr.core.texture_procedural |
TextureForge |
v0.6.0 |
hamr.hair.mesh |
HairForge |
v0.4.0 |
hamr.clothing.mesh |
ClothingForge |
v0.4.0 |
hamr.rigs.stub_bones |
create_missing_bones() |
v0.4.0 |
hamr.rigs.weights |
WeightPaintEngine |
v0.4.0 |
hamr.rigs.verify |
RigVerifier, RigReport |
v0.4.0 |
hamr.rigs.spring_bones |
create_spring_bones() |
v0.4.0 |
hamr.rigs.colliders |
CollisionForge |
v0.5.0 |
hamr.materials.forge |
MaterialForge |
v0.5.0 |
hamr.face.expressions |
ExpressionDiscovery |
v0.5.0 |
hamr.export.first_person |
FirstPersonAnnotator |
v0.4.0 |
hamr.export.vrm_validator |
VRMValidator |
v0.6.0 |
hamr.export.animation_clips |
AnimationForge |
v0.6.0 |
hamr.docs.generate |
DocGenerator |
v0.6.0 |
hamr.core.regression |
RegressionThreshold, RegressionBaseline |
v0.7.0 |
hamr.core.release |
ArtifactInfo, ReleaseManifest |
v0.7.0 |
hamr.blender_bridge.e2e |
E2EBuildConfig, E2EBuildResult |
v0.7.0 |
hamr.docs.api_reference |
APIEntry, generate_api_reference() |
v0.7.0 |
| Old Path | New Path | Notes |
|---|---|---|
hamr.core.spec.Spec |
Same | Spec is now the canonical import; CharacterSpec is a data model |
hamr.core.models.CharacterSpec |
Still exists | Use Spec for YAML loading; CharacterSpec is the data structure |
The CharacterSpec YAML format now supports a pipeline section:
# New in v0.5.0+ — pipeline configuration
pipeline:
skip_stages: [] # e.g., ["hair", "clothing"]
perf_budget: standard # minimal | standard | full
spring_bones: true
collision: true
# Existing fields remain unchanged
body:
height_cm: 165
build: feminine
proportions: average
# ...Presets (in assets/presets/) now support:
- Deep merge — user specs override preset defaults while preserving nested structure
- Pipeline section —
pipelinesub-key with stage configuration - Validation — presets are validated against the
CharacterSpecschema on load
| Flag | Since | Description |
|---|---|---|
--json |
v0.5.0 | Machine-readable JSON output for all commands |
--verbose |
v0.5.0 | Detailed output for list-presets etc. |
--skip-stages |
v0.5.0 | Skip pipeline stages (comma-separated) |
--no-color |
v0.6.0 | Strip ANSI/Rich formatting for piped output |
--quiet |
v0.6.0 | Suppress all non-error output |
| Code | Meaning | Since |
|---|---|---|
| 0 | Success | v0.3.0 |
| 1 | Warning | v0.6.0 |
| 2 | Error | v0.6.0 |
| 3 | Environment missing | v0.6.0 |
hamr.core.spec.Spec.to_dict()round-trips — Usespec_to_dict()fromhamr.core.validatefor guaranteed round-trip-able serialization. TheSpec.to_dict()method remains but does not guarantee all fields survive a YAML round-trip.- Ad-hoc build scripts — Direct calls to individual forge functions should
migrate to
BuildPipeline.build(). The old functions are not removed, but they are not the recommended entry point. - Flat JSON presets — Presets are now YAML-based with deep merge. Flat JSON preset files will still load but should be migrated to the new format.
- Python ≥ 3.10 required (unchanged from v0.3.0)
- New runtime dependencies:
pydantic>=2.0,rich>=13.0 - Dev dependencies:
mypy,ruffadded to[dev]extras - Blender dependency unchanged —
bpyis not pip-installable; core library works without it - pytest markers:
blender,slow,benchmark,perf,e2eavailable
- GitHub Actions —
.github/workflows/ci.ymlruns lint, test, coverage, and benchmark on every push/PR - Release workflow —
.github/workflows/release.ymlbuilds wheel/sdist and publishes to TestPyPI on tag push - Branch protection —
DevelopmentandMainbranches require passing CI
from hamr.docs.api_reference import generate_api_reference
# Generate markdown API reference for all hamr.* modules
md = generate_api_reference()
# Or specify specific modules
md = generate_api_reference(["hamr.core", "hamr.rigs"])Tests that relied on ad-hoc build calls should migrate to:
from hamr.core.pipeline import BuildPipeline
from hamr.core.spec import Spec
spec = Spec.from_yaml("test_spec.yaml")
result = BuildPipeline().build(spec)
assert result.successFor CI environments without Blender, use:
pytest tests/ -m "not blender" -m "not e2e"For performance regression tests:
pytest tests/ -m perf