Metadata-Version: 2.4
Name: axis-foundry
Version: 0.3.0
Summary: AI-native 3D avatar foundry — generate, rig, validate, and export production-ready avatars. Zero runtime dependencies. MCP server included.
Author-email: "Last Man Up Inc." <support@no-fate.ai>
License: MIT
Project-URL: Homepage, https://avatar.jonathanarvay.com
Project-URL: Source, https://github.com/lastmanupinc-hub/AXIS-Foundry
Project-URL: Issues, https://github.com/lastmanupinc-hub/AXIS-Foundry/issues
Project-URL: Documentation, https://github.com/lastmanupinc-hub/AXIS-Foundry#readme
Keywords: avatar,3d,rigging,skinning,gltf,glb,vrm,fbx,unity,unreal,godot,roblox,mcp,model-context-protocol,ai-agents
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
Classifier: Topic :: Multimedia :: Graphics :: 3D Rendering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: license-file

# 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.

[![Python](https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![Tests](https://img.shields.io/badge/tests-9962%20passing-success)](https://github.com/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![AXIS Platform](https://img.shields.io/badge/AXIS-Platform-6E3A8C)](https://no-fate.ai/)

---

## Table of Contents

- [Features](#features)
- [Asset Taxonomy](#asset-taxonomy)
- [Installation](#installation)
- [Quickstart](#quickstart)
- [Supported Input Formats](#supported-input-formats)
- [Export Targets](#export-targets)
- [CLI Commands](#cli-commands)
- [Avatar Pipeline](#avatar-pipeline-production-path)
- [AXIS Language Integration](#axis-language-integration)
- [Marketplace + TrustFabric Listings](#marketplace--trustfabric-listings)
- [Architecture](#architecture)
- [Testing](#testing)
- [Continuous Integration](#continuous-integration)
- [Requirements](#requirements)
- [Contributing](#contributing)
- [License](#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

```bash
# 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](https://modelcontextprotocol.io)
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:

```json
{
  "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:

```bash
python -m axis_foundry mcp --list --json
```

---

## Quickstart

```bash
# 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:

```python
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

```bash
# 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](LICENSE) for full details.

---

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