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

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:

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

Export Targets

CLI Commands

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.