Metadata-Version: 2.4
Name: morphism
Version: 0.1.1
Summary: Categorical governance engine — morphisms, functors, natural transformations
Project-URL: Homepage, https://morphism.systems
Project-URL: Repository, https://github.com/morphism-systems/morphism
Project-URL: Documentation, https://morphism.systems/docs
Author: Morphism Systems
License-Expression: BUSL-1.1
License-File: LICENSE
Keywords: ai-governance,category-theory,convergence,drift-detection,functor,governance-framework,kappa-metric,llm-governance,morphism,proof-witness,ssot
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: numpy>=1.26
Requires-Dist: pydantic>=2.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: asv>=0.6; extra == 'dev'
Requires-Dist: hypothesis>=6.0; extra == 'dev'
Requires-Dist: mkdocs-material>=9.0; extra == 'dev'
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pymdown-extensions>=10.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Requires-Dist: virtualenv>=20.0; extra == 'dev'
Provides-Extra: paper
Requires-Dist: matplotlib>=3.7; extra == 'paper'
Requires-Dist: scipy>=1.11; extra == 'paper'
Description-Content-Type: text/markdown

# Morphism

[![npm](https://img.shields.io/npm/v/@morphism-systems/cli?label=%40morphism-systems%2Fcli)](https://www.npmjs.com/package/@morphism-systems/cli)
[![CI](https://github.com/morphism-systems/morphism/actions/workflows/ci.yml/badge.svg)](https://github.com/morphism-systems/morphism/actions/workflows/ci.yml)
[![Governance Score](https://img.shields.io/badge/governance-125%2F125-brightgreen)](https://morphism.systems)
[![License: BUSL-1.1](https://img.shields.io/badge/License-BUSL--1.1-blue.svg)](LICENSE)

**The control plane for AI-assisted engineering.** Morphism helps engineering teams keep AI-assisted workflows consistent, auditable, and controllable across repos, agents, CI, and shared workspace review.

> Entropy is the default. Governance is the override.

## Why Morphism

- **Control, not just observability** — Catch repo, workflow, and policy drift before it becomes team-level entropy
- **Mathematical foundation** — Functors, natural transformations, and sheaf cohomology (tools for verifying distributed consistency) give Morphism a rigorous model for convergence
- **Typed evidence** — Every verdict ties back to explicit artifacts, not hand-wavy policy claims
- **Local-first adoption** — CLI and MCP server run in developer workflows and CI; dashboard surfaces shared state for teams

## Quick Install

```bash
# CLI (recommended — works standalone)
npm install -g @morphism-systems/cli

# MCP server (for Claude Code / Cursor)
npm install -g @morphism-systems/mcp-server

# One-command setup (CLI + MCP server + skills + hooks)
npm install -g @morphism-systems/plugin-bundle
```

## Packages

| Package | Description | Tiers |
|---------|-------------|-------|
| [`@morphism-systems/cli`](https://www.npmjs.com/package/@morphism-systems/cli) | Governance CLI — init, validate, score, doctor | Free+ |
| [`@morphism-systems/mcp-server`](https://www.npmjs.com/package/@morphism-systems/mcp-server) | MCP server — validation, scoring, drift metrics | Pro+ |
| [`@morphism-systems/plugin-bundle`](https://www.npmjs.com/package/@morphism-systems/plugin-bundle) | One-command installer — MCP servers, skills, hooks | Free+ |
| [`@morphism-systems/shared`](https://www.npmjs.com/package/@morphism-systems/shared) | Shared types, schemas, and utilities | Free+ |
| [`@morphism-systems/sdk`](https://www.npmjs.com/package/@morphism-systems/sdk) | Embeddable governance client for third-party platforms | Pro+ |
| [`@morphism-systems/agentic-math`](https://www.npmjs.com/package/@morphism-systems/agentic-math) | Category theory MCP server — morphisms, functors, convergence | Free+ |
| [`@morphism-systems/design-tokens`](https://www.npmjs.com/package/@morphism-systems/design-tokens) | Design tokens and theme system — CSS/Tailwind generators | Free+ |

## Tiers

| Tier | Price | What you get |
|------|-------|--------------|
| **Free** | $0 | CLI validate + score, repo baseline checks, up to 10 agents |
| **Pro** | $29/seat/mo | Kappa drift metric, entropy, diff, agent registry, MCP server access |
| **Team** | $79/seat/mo | Shared policies, policy packs, audit log export, typed evidence review |
| **Enterprise** | Custom | Unlimited agents, proof witnesses, custom policy rollout, dedicated support |

See [`packages/shared/src/plans.ts`](packages/shared/src/plans.ts) for the canonical entitlement definitions.

## Quick Start

### Initialize a repo

```bash
morphism init        # Creates .morphism/config.json
morphism doctor      # Verifies repo docs, Python, and governance scripts
morphism validate    # Runs the governance pipeline
morphism score       # Prints the full maturity score breakdown
```

`morphism init` does not generate `AGENTS.md` or `SSOT.md`. `morphism doctor` expects those repo governance files to already exist.

### Add the MCP Server (Claude, Cursor, etc.)

```json
{
  "mcpServers": {
    "morphism": {
      "command": "npx",
      "args": ["@morphism-systems/mcp-server"]
    }
  }
}
```

### Development (contributors)

```bash
npm install && npx turbo dev       # TypeScript (Next.js + packages)
pip install -e ".[dev]" && pytest  # Python (governance engine)
```

## Prerequisites

| Tool | Version | Notes |
|------|---------|-------|
| Node.js | 20+ (22 recommended) | [nodejs.org](https://nodejs.org) |
| npm | included with Node.js | — |
| Python | 3.11+ | [python.org](https://python.org) |

## Environment Setup (web app)

1. Copy the example env file:
   ```bash
   cp apps/morphism/.env.local.example apps/morphism/.env.local
   ```
2. Fill in the required values. See [docs/integrations/platform-services.md](docs/integrations/platform-services.md) for service credentials (Clerk, Supabase, Sentry, Pinecone).
3. Or pull live values from Vercel if you have project access:
   ```bash
   cd apps/morphism && vercel env pull
   ```

## Database Setup

This project uses Supabase (PostgreSQL). For local development, point `SUPABASE_URL` and `SUPABASE_ANON_KEY` in `.env.local` at a Supabase project. See [docs/integrations/platform-services.md](docs/integrations/platform-services.md) for connection details and migration instructions.

## Architecture

### Monorepo structure

```mermaid
graph TD
    subgraph "Developer workflow"
        CLI["@morphism-systems/cli<br/>morphism init · validate · score"]
        MCP["@morphism-systems/mcp-server<br/>33 governance tools"]
        MATH["@morphism-systems/agentic-math<br/>Category theory MCP"]
    end

    subgraph "Shared layer"
        SHARED["@morphism-systems/shared<br/>Types · Schemas · Plan gates"]
        TOKENS["@morphism-systems/design-tokens<br/>10 themes · CSS/Tailwind"]
        SDK["@morphism-systems/sdk<br/>Embeddable client"]
        BUNDLE["@morphism-systems/plugin-bundle<br/>One-command installer"]
    end

    subgraph "Python core — src/morphism/"
        ENGINE["engine/<br/>Morphism · Functor · NaturalTransformation"]
        METRICS["metrics/<br/>Kappa convergence · Delta drift"]
        SHEAF["sheaf/<br/>Consistency cohomology"]
        HEAL["healing/<br/>DriftScanner · DriftHealer"]
    end

    subgraph "App"
        WEB["apps/morphism<br/>Next.js 15 dashboard"]
    end

    CLI --> SHARED
    MCP --> SHARED
    MATH --> SHARED
    WEB --> SHARED
    WEB --> TOKENS
    SDK --> SHARED
    BUNDLE --> CLI
    BUNDLE --> MCP
    MCP -.->|JSON-RPC bridge| ENGINE
    ENGINE --> METRICS
    ENGINE --> SHEAF
    HEAL --> METRICS
```

### Governance data flow

```mermaid
flowchart LR
    A["git commit"] --> B["pre-commit hook"]
    B --> C{"policy_check.py"}
    C -->|pass| D["commit created"]
    C -->|fail| E["blocked + guidance"]
    D --> F["pre-push hook"]
    F --> G{"enforce_repo_conventions.py<br/>verify_pipeline.py<br/>orphan_scan.py"}
    G -->|pass| H["push to remote"]
    G -->|fail| I["blocked + guidance"]
    H --> J["CI: release.yml"]
    J --> K["npm publish<br/>PyPI publish<br/>GitHub Release<br/>Vercel promotion"]

    style C fill:#e9c46a,color:#000
    style G fill:#e9c46a,color:#000
    style K fill:#2d6a4f,color:#fff
```

| Layer | Stack | Purpose |
|-------|-------|---------|
| **Web** | Next.js 15, Turborepo | SaaS dashboard |
| **Shared** | TypeScript, Zod | Types, schemas, utilities |
| **MCP** | TypeScript, MCP SDK | AI tool integration (33 tools) |
| **Python** | Click, Category Theory | Control engine, drift metrics |
| **Scripts** | Python | CI validation, scoring, repo enforcement |

## Governance

The governance framework is the core of Morphism. See [AGENTS.md](AGENTS.md) for the full specification.

| Document | Purpose |
|----------|---------|
| [AGENTS.md](AGENTS.md) | Root governance rules |
| [SSOT.md](SSOT.md) | Single source of truth |
| [Kernel](docs/governance/morphism-kernel.md) | 7 invariants (I-1..I-7) |
| [Docs Index](docs/index.md) | Documentation map (source) |
| [CHANGELOG.md](CHANGELOG.md) | Consolidated release history |
| [morphism.systems](https://morphism.systems) | Product site and thin docs index |
| [Full docs (MkDocs)](https://morphism-systems.github.io/morphism) | Canonical public docs, governance, and reference docs |

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, architecture overview, and contribution guidelines.

## License

[Business Source License 1.1](LICENSE) — Change Date 2030-02-20, Change License Apache 2.0
