AlphaForge

Deterministic post-processing for AI-generated production assets.

About

AlphaForge transforms AI-generated images into production-ready digital assets using mathematically correct, deterministic algorithms. It does not generate images, and it does not rely on machine learning inference.

Current Status

AlphaForge Core is frozen. The deterministic reconstruction pipeline is implemented and tested, the public API is declared stable, and future visual improvements will be implemented as optional, composable refinement layers outside the core engine.

Installation

npm install alphaforge

Usage

import { reconstructPipeline } from "alphaforge";

await reconstructPipeline({
  observationAPath: "./render-white.png",
  observationBPath: "./render-black.png",
  backgroundA: [1, 1, 1],
  backgroundB: [0, 0, 0],
  outputPath: "./result.png",
});

Only the symbols exported from the package root are public. Internal modules are not covered by the stability contract.

Project Documentation

For a full overview of the project, architecture, public API, accepted decisions, and formal specifications, see PROJECT.md. It is the source of truth for the documentation map.

Key documents:

• PROJECT.md — vision, mission, scope, goals, and documentation map.
• CONSTITUTION.md — long-term project principles.
• ARCHITECTURE.md — system architecture and module responsibilities.
• API.md — canonical registry of the public API.
• ADR.md — architecture decision records.
• TASKS.md — roadmap and milestones.
• CHANGELOG.md — project history.
• docs/specifications/ — normative technical specifications for the reconstruction pipeline.

Development

This project uses pnpm, Node.js 20+, and TypeScript.

Setup

pnpm install

Available Scripts

| Script | Description | | ----------------------- | ----------------------------- | | pnpm run build | Compile TypeScript to dist/ | | pnpm run typecheck | Run TypeScript type checking | | pnpm run test | Run tests | | pnpm run lint | Run ESLint | | pnpm run format:check | Check Prettier formatting |

Workflow

This repository uses the following branching strategy:

• main — production-ready state.
• develop — integration branch for features.
• feature/* and fix/* — short-lived work branches.

Branches are squash merged into develop. Releases are prepared by merging develop into main.

Contributing

Contributions should follow the principles defined in CONSTITUTION.md, the architecture in ARCHITECTURE.md, the public API contract in API.md, the accepted decisions in ADR.md, and the development guidelines in CLAUDE.md.

Testing Philosophy

AlphaForge combines unit testing, integration testing, and property-based testing to verify deterministic behavior and mathematical correctness.

Maturity

AlphaForge is pre-1.0. The Core mathematical engine and the public API are frozen as of v0.9.0. Necessary corrections to demonstrable defects may still occur under the 0.x line, but the reconstruction pipeline will not change for visual preference or convenience.

Future improvements, including CLI support, automatic background inference, and edge-aware refinement, will be implemented as optional layers outside the core engine.

Limitations

• No CLI yet. The current release is a TypeScript library only.
• No automatic background inference. Background colors must be declared by the caller; optional background validation can detect mismatches.
• Refinement features are not part of the core. Edge refinement, halo reduction, and color decontamination are planned for future milestones.

Maintainer

Maintained by Mauricio Cabrera.

• Website: https://maucabrera.dev
• GitHub: https://github.com/maucabreradev
• Email: [email protected]

License

MIT