axis-foundry 0.3.0

AI-native 3D avatar foundry — generate, rig, validate, and export production-ready avatars. Zero runtime dependencies. MCP server included.

AXIS Foundry

AI-native 3D resources foundry — generate, rig, validate, and export production-ready 3D assets across multiple asset kinds.

Zero runtime dependencies. Pure Python 3.11+. Wired into the AXIS Language (GoldenSlice) workflow runtime.

Originally AXIS Foundry. The avatar pipeline remains the flagship and is byte-for-byte compatible. The platform now models a wider asset taxonomy — props, vehicles, environments, VFX, weapons/armor, character accessories, and generic assets — with shared canonical contracts, provenance, marketplace metadata, and TrustFabric listing payloads.

---

Table of Contents

• Features
• Asset Taxonomy
• Installation
• Quickstart
• Supported Input Formats
• Export Targets
• CLI Commands
• Avatar Pipeline
• AXIS Language Integration
• Marketplace + TrustFabric Listings
• Architecture
• Testing
• Continuous Integration
• Requirements
• Contributing
• License

---

Features

• Multi-asset-kind support with a unified CanonicalAssetContract system
• Production-ready 17-stage avatar pipeline (classify → normalize → repair → 65-bone rig → skin → validate → facial → texture → animate → LOD → preview → export)
• Zero external runtime dependencies — 100% Python standard library
• Strong provenance & auditability — every stage emits a versioned, SHA-256-hashed contract
• Native AXIS Language (GoldenSlice) integration with pipeline audit guarantees
• Marketplace-ready outputs including TrustFabric / PAI listing payloads
• Cross-engine export to Unity, Unreal Engine, Godot, and Roblox
• 9,962+ tests passing across Python 3.12–3.14 with strict CI provenance auditing

---

Asset Taxonomy

AssetKind	Status	Notes
AVATAR	Production	Full 17-stage pipeline including 65-bone humanoid rig, skinning, facial, LOD, animation
PROP	Contract + marketplace	Canonical contract, marketplace events, TrustFabric listings
VEHICLE	Contract + marketplace	Canonical contract, marketplace events, TrustFabric listings
ENVIRONMENT	Contract + marketplace	Canonical contract, marketplace events, TrustFabric listings
VFX	Contract + marketplace	Canonical contract, marketplace events, TrustFabric listings
WEAPON_ARMOR	Contract + marketplace	Canonical contract, marketplace events, TrustFabric listings
CHARACTER_ACCESSORY	Contract + marketplace	Canonical contract, marketplace events, TrustFabric listings
GENERIC	Contract + marketplace	Catch-all canonical contract, marketplace events, TrustFabric listings

Note: Pipeline factory functions (process_mesh_file, create_contract_from_template) accept asset_kind= today. Non-AVATAR kinds currently raise NotImplementedError until kind-specific normalize/rig/skin/validate paths are implemented. They are intentionally gated, not stubbed.

---

Installation

# From PyPI (recommended for users)
pip install axis-foundry

# Or in editable mode (for development)
python -m venv .venv
source .venv/bin/activate     # Linux/macOS
# .venv\Scripts\activate      # Windows
pip install -e ".[dev]"

The package has zero runtime dependencies beyond the Python standard library.

After install, two console scripts are available:

Command	What it does
axis-foundry	Full CLI (process, validate, export, ...)
axis-foundry-mcp	MCP stdio server for AI agents

---

Use from your AI agent (MCP)

AXIS Foundry ships a Model Context Protocol server so AI agents (Claude Desktop, Cursor, Windsurf, VS Code Copilot, Blender AI add-ons) can call the avatar pipeline directly.

After pip install axis-foundry, add this to your agent's MCP config:

{
  "mcpServers": {
    "axis-foundry": {
      "command": "axis-foundry-mcp",
      "env": {
        "AXIS_API_BASE": "https://api.avatar.jonathanarvay.com"
      }
    }
  }
}

Config file locations:

• Claude Desktop: %APPDATA%\Claude\claude_desktop_config.json (Windows) / ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
• Cursor / Windsurf: ~/.cursor/mcp.json / ~/.codeium/windsurf/mcp_config.json
• VS Code: .vscode/mcp.json in your workspace

To inspect the tool manifest without starting the server:

python -m axis_foundry mcp --list --json

---

Quickstart

# Process an avatar (default asset kind)
python -m axis_foundry process model.glb

# JSON contract output only
python -m axis_foundry process model.glb --json

# Export ready for Unity
python -m axis_foundry process model.glb --platform unity --export

# Run validation only
python -m axis_foundry validate model.glb

# Batch process an entire directory
python -m axis_foundry batch models/

Python API example:

from axis_foundry.contracts import AssetKind, new_contract

# Create a non-avatar contract directly
prop = new_contract(AssetKind.PROP)
prop.identity.name = "wooden-crate-01"
prop.attributes["material"] = "oak"
print(prop.to_json())

---

Supported Input Formats

Format	Normalizer
.glb, .gltf	glTF 2.0
.fbx	FBX
.obj	Wavefront OBJ
.stl	STL
.ply	PLY
.vrm	VRM
.usda, .usdc, .usdz	USD

---

Export Targets

Platform	Output Format
Unity	.unitypackage-compatible glTF
Unreal	UE-compatible glTF
Godot	Godot-compatible glTF
Roblox	Roblox-compatible mesh

---

CLI Commands

Command	Description
process	Run the full pipeline on a mesh file
info	Classify and display file information
validate	Run validation rules and show results
inspect	Deep inspection of bones, hierarchy, provenance
manifest	Inspect or verify embedded provenance manifest
report	Generate a comprehensive pipeline report
batch	Process multiple files with summary table
wizard	Interactive step-by-step processing
audit	Audit provenance chain and contract integrity
migrate	Migrate contract JSON to current schema
serve	Start HTTP API server (default 127.0.0.1:8321)

---

Avatar Pipeline (Production Path)

Input File
    ↓
Classify → Normalize → Extract Geometry → Repair Mesh
    ↓
Auto-Rig (65-bone humanoid) → Skin Weights → Validate
    ↓
Facial Rig → Texture → Animate → LOD Generation → Preview
    ↓
Export (glTF / engine-specific)

Each stage produces a CanonicalAvatarContract (frozen dataclass) that captures the complete state of the asset. Contracts are versioned, diffable, and carry SHA-256 provenance hashes.

CanonicalAvatarContract inherits from CanonicalAssetContract and hard-pins asset_kind = AssetKind.AVATAR (excluded from serialization for backwards compatibility).

The full pipeline consists of 17 distinct stages with rich intermediate contracts for maximum auditability and partial re-processing.

---

AXIS Language Integration

The Foundry pipeline is exposed as plugins on the AXIS Language (GoldenSlice) workflow runtime:

• Vendored GoldenSlice snapshot lives at axis_foundry/language/_goldenslice/ (stdlib only — zero runtime dependency on external packages).
• Foundry slice (axis_foundry/language/foundry_slice.py) registers:
  • OnAssetPipeline → foundry.normalize, foundry.rig, foundry.skin
  • OnValidate → foundry.validate
  • OnExport → foundry.export
• Pinned upstream: UPSTREAM_GOLDENSLICE_VERSION = "2.3.0"
• axis_foundry.language.pipeline_audit.audit_pipeline_against_axis() guarantees that every hook/plugin/op binding used by the Python implementation exists in the slice. Drift raises PipelineAuditError.

---

Marketplace + TrustFabric Listings

Every MarketplaceHookEvent carries the asset_kind. The axis_foundry.portal.paid_listing module builds (and optionally submits) TrustFabric / PAI-compatible listings:

• Default endpoint: https://api.trustfabric.ai/v1/listings
• Schema v1 with deterministic SHA-256 contract hash
• Submission uses urllib.request (stdlib)
• Opt-in configuration via environment variables:
  • AXIS_TRUSTFABRIC_API_URL
  • AXIS_TRUSTFABRIC_API_KEY

---

Architecture

axis_foundry/
├── contracts/        # AssetKind taxonomy, Canonical*Contract hierarchy,
│                     # query index, schema versioning & migration
├── normalization/    # Format normalizers + intelligent file classifier
├── rigging/          # Auto-rigging, bone mapping, rig repair & validation
├── skinning/         # Geodesic / heat-diffusion / blended weight painting
├── validation/       # Structural + export validation rules + profiles
├── exporters/        # Unity, Unreal, Godot, Roblox glTF/mesh writers
├── animation/        # Retargeting, blending, and animation utilities
├── audit/            # Provenance auditing + CI integration helpers
├── lod/              # Level-of-detail generation pipeline
├── reporting/        # Rich pipeline reports and dashboards
├── language/         # AXIS Language (GoldenSlice) bridge + pipeline audit
├── portal/           # Marketplace hooks + TrustFabric paid listing builder
├── cli.py            # Rich CLI entry point
└── pipeline.py       # Core orchestration & stage contracts

---

Testing

# Run the full test suite
python -m pytest tests/ -q

# Run a specific test module with verbose output
python -m pytest tests/test_pipeline.py -v

9,962 tests passing with zero external runtime dependencies.
Tests execute across Python 3.12, 3.13, and 3.14 in CI.

---

Continuous Integration

GitHub Actions runs on every push and pull request to main:

1. Test — full pytest suite across Python 3.12–3.14
2. Audit — provenance chain verification with JUnit + JSON reports and GitHub annotations

---

Requirements

• Python ≥ 3.11
• No runtime dependencies (pure stdlib)
• pytest ≥ 7.0 (development / testing only)

---

Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-new-thing)
3. Ensure all tests still pass (python -m pytest)
4. Run the pipeline audit (python -m axis_foundry audit)
5. Open a Pull Request

For large changes, please open an issue first to discuss the design.

---

License

MIT License. See LICENSE for full details.

---

Built with ❤️ for the AXIS ecosystem and the future of open, provenance-rich 3D content.