diff --git a/README.md b/README.md index 3cf24f6..ce676a9 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,19 @@ # Base120 -> **v1 Python validator RETIRED (2026-04-14).** The original v1 validator -> code is no longer the active surface. The canonical registry -> (`Base120_Canonical_Model_Registry.yaml`) and data files (`registries/`) -> remain here as source of truth. -> -> **v2 Python SDK is active (scaffolding in `base120/`):** `cli.py`, `engine.py`, -> `models.py`, `ledger.py`, `mcp_server.py`. Version line `2.0.0.dev0` per -> `pyproject.toml`. See `GOVERNANCE.md` for the contract authority and change -> taxonomy that govern this SDK. +> **Lifecycle note (2026-05-24).** The original v1 validator runtime was +> retired on 2026-04-14. This repository now contains the active stdlib-only +> Python v2 SDK (`base120` 2.0.0.dev0) for operator lookup, prompting, MCP +> serving, and VERUM-aligned ledger records. +> The canonical v1 registry (`Base120_Canonical_Model_Registry.yaml`) and data +> files (`registries/`) remain here as source of truth. > > **FM taxonomy (FM1–FM30) migrated to:** > [`hummbl-governance`](https://github.com/hummbl-dev/hummbl-governance) > — `from hummbl_governance.errors import FailureMode, HummblError` > -> **MCP server (TypeScript, live):** -> [`mcp-server`](https://github.com/hummbl-dev/mcp-server) — all 120 operators served via MCP +> **MCP server:** use the Python `base120-mcp` entry point from this package, +> or the external [`mcp-server`](https://github.com/hummbl-dev/mcp-server) +> mirror when a TypeScript server is required. [![License: Apache 2.0](https://img.shields.io/badge/license-Apache_2.0-blue)](LICENSE) @@ -23,73 +21,98 @@ ## Quick Example -Apply a model to decompose a problem: +Apply an operator, generate a prompt, and persist a governance-readable record: ```python -from base120.validators.validate import validate_artifact - -# FM42: Separation of Concerns -- does this component have a single responsibility? -artifact = { - "id": "auth-service-review", - "domain": "core", - "class": "architecture", - "instance": "auth-svc", - "models": ["FM42"] # Separation of Concerns -} -errors = validate_artifact(artifact, schema, mappings, err_registry) -# [] -- valid artifact, model applies cleanly +from base120 import Engine, Ledger + +engine = Engine() + +operator = engine.get("P6") +print(operator.name) # Point-of-View Anchoring + +prompt = engine.prompt("P6", "How should we price the certification tier?") +result = engine.record( + "P6", + "How should we price the certification tier?", + "Anchor the offer to the compliance officer's risk budget.", + 0.85, +) + +ledger = Ledger("base120-ledger.jsonl") +ledger.append(result.to_tuple()) ``` -Each of the 120 models is a named, versioned reasoning primitive with a defined domain, failure graph, and validation rules. +Each of the 120 operators is a named, versioned reasoning primitive with a +defined transformation family and deterministic package representation. ## Features -- **120 mental models** across 6 cognitive domains (core, systems, security, governance, operations, meta) -- **6 cognitive transformations** -- deterministic operations that compose models into chains -- **CLI validation** -- `base120 validate-contract` checks governance artifacts against the frozen spec -- **Observability layer** -- opt-in structured JSON events for production monitoring -- **MCP integration** -- serve models to AI agents via [mcp-server](https://github.com/hummbl-dev/mcp-server) -- **Golden corpus** -- all implementations must match the canonical test corpus in `tests/corpus` +- **120 reasoning operators** across 6 transformation families +- **Stdlib-only Python SDK** -- no third-party runtime dependencies +- **CLI tooling** -- `base120 list`, `base120 get`, `base120 prompt`, and `base120 families` +- **Append-only ledger** -- persist operator applications as VERUM-aligned JSONL tuples +- **MCP integration** -- serve operators to AI agents with the `base120-mcp` entry point +- **Canonical registry and corpus docs** -- frozen v1 reference artifacts remain in-tree -## Install +## Install From Source ```bash -pip install base120 - -# Or from source git clone https://github.com/hummbl-dev/base120.git && cd base120 pip install -e ".[test]" ``` +The package name is `base120`, but this repository should not claim PyPI +availability until a published package exists. + ## CLI ```bash -# Validate a contract unit (schema, failure graph, version metadata) -base120 validate-contract path/to/contract.json +# List all operators +base120 list + +# Inspect one operator +base120 get P6 + +# Generate an operator-specific prompt for a problem +base120 prompt P6 "How should we price the certification tier?" + +# List canonical operator families +base120 families ``` -See [`docs/contract-units.md`](docs/contract-units.md) for contract unit format and examples. +The historical contract-unit validator spec is archived in +[`docs/contract-units.md`](docs/contract-units.md); the current v2 SDK does not +ship `base120 validate-contract`. -## Observability +## Ledger -Opt-in structured events for production deployments: +Persist operator applications as JSONL tuples: ```python -from base120.observability import create_event_sink +from base120 import Engine, Ledger -event_sink = create_event_sink() # logs to stdout -errors = validate_artifact(artifact, schema, mappings, err_registry, - event_sink=event_sink) -# Emits: {"event_type": "validator_result", "result": "success", ...} +engine = Engine() +result = engine.record("DE1", "Reduce release risk.", "Split blockers by owner.", 0.9) + +ledger = Ledger() +ledger.append(result.to_tuple()) +high_drift = ledger.cut(0.5) ``` -Omitting `event_sink` preserves original v1.0.0 behavior with zero overhead. Full spec: [`docs/observability.md`](docs/observability.md). +The archived v1 validator observability contract remains in +[`docs/observability.md`](docs/observability.md), but the current v2 SDK does +not expose `base120.observability`. ## Authority Statement -This repository is the **authoritative reference implementation** for Base120 v1.0.0. All other language implementations are semantic mirrors and MUST conform exactly to the outputs defined here. +This repository is the **authoritative source** for the Base120 v1 registry, +reference artifacts, and current Python v2 SDK. Other language +implementations should conform to the frozen registry and corpus artifacts +defined here. The `2.0.0.dev0` Python SDK API remains pre-release until a +non-dev package version is published. -### v1.0.x Policy +### v1 Artifact Policy - **Permitted:** Security fixes, CI hardening, documentation, corpus additions - **Prohibited:** Schema changes, registry modifications, breaking changes @@ -125,3 +148,7 @@ Apache 2.0 -- see [LICENSE](LICENSE). --- Built by [HUMMBL LLC](https://hummbl.io). Base120 powers the cognitive layer behind multi-agent coordination at scale. + +## Repository Health + +See [docs/REPO_HEALTH.md](docs/REPO_HEALTH.md) for validation and branch-protection expectations. diff --git a/docs/REPO_HEALTH.md b/docs/REPO_HEALTH.md index 67333b1..38e9daf 100644 --- a/docs/REPO_HEALTH.md +++ b/docs/REPO_HEALTH.md @@ -5,13 +5,13 @@ - **Repository**: `hummbl-dev/base120` - **Canonical URL**: `https://github.com/hummbl-dev/base120` - **Owner**: HUMMBL Team -- **Stewardship scope**: Canonical Base120 registry, executable corpus contract, governance specs, and v1 reference artifacts. +- **Stewardship scope**: Canonical Base120 registry, executable corpus contract, governance specs, v1 reference artifacts, and the active Python v2 SDK. ## Lifecycle -- **Status**: Active public repository with the Python v1 package retired. +- **Status**: Active public repository with frozen v1 registry/corpus artifacts and an active Python v2 SDK (`base120` 2.0.0.dev0). - **Default branch**: `main`. -- **Release posture**: v1 Python runtime code has been removed. Registry, corpus, governance, documentation, and CI hardening changes may continue through pull requests. +- **Release posture**: The v1 validator runtime is retired. The current Python package exposes operator lookup, prompting, MCP serving, and VERUM-aligned ledger records; registry, corpus, governance, documentation, and CI hardening changes may continue through pull requests. - **Archive trigger**: Archive only if the canonical Base120 registry and corpus contract move to another declared source of truth. ## Source Of Truth @@ -21,7 +21,8 @@ - `tests/corpus/` is the canonical executable corpus path for Base120 contract artifacts. - `docs/corpus-contract.md` and `mirrors/CONFORMANCE_CONTRACT.md` document the corpus contract for implementations and mirrors. - `GOVERNANCE.md` and `docs/governance-decision-tree.md` define change classes and review expectations. -- `docs/contract-units.md` defines contract unit structure and examples. +- `docs/contract-units.md` defines archived v1 contract unit structure and examples; the current v2 SDK does not ship the `base120 validate-contract` command. +- `base120/` contains the active v2 SDK package. ## Validation Contract @@ -32,6 +33,7 @@ python -m pip install --upgrade pip pip install -e ".[test]" pytest python -m pytest tests/ -v +python -m pip wheel . --no-deps -w dist-smoke ``` Expected CI coverage: @@ -53,15 +55,16 @@ Expected CI coverage: ## Known Operational Gaps - GitHub branch protection is tracked centrally in `hummbl-dev/hummbl-dev#18`; do not overclaim required checks until that audit is updated. -- The Python v1 package is retired, so validation should focus on registry, corpus, and mirror-conformance integrity rather than runtime feature growth. +- The Python v1 validator package is retired, while the v2 SDK is active pre-release. Keep README/API docs aligned with the actual `Engine`, `Ledger`, CLI, and MCP entry points. +- `docs/contract-units.md` and `docs/observability.md` are archived v1 validator contracts, not current v2 SDK API promises. - `tests/test_corpus_contract.py` validates that `tests/corpus/` exists, has valid/invalid JSON artifacts, and has expected-error manifests for every invalid artifact. ## Fleet Scan Classification Future fleet scans can classify this repository as: -- **Lifecycle**: active, v1 runtime retired +- **Lifecycle**: active, v1 validator runtime retired, v2 SDK pre-release active - **Visibility**: public -- **Primary function**: canonical Base120 registry and executable corpus contract +- **Primary function**: canonical Base120 registry, executable corpus contract, and active stdlib-only Python SDK - **Validation entrypoint**: `pytest` - **Primary metadata owner**: HUMMBL Team diff --git a/docs/contract-units.md b/docs/contract-units.md index 1146a64..5aadd2d 100644 --- a/docs/contract-units.md +++ b/docs/contract-units.md @@ -1,5 +1,11 @@ # Base120 Contract Units +> **Status (2026-05-24): archived v1 validator contract.** The current +> `base120` v2 SDK does not implement the `base120 validate-contract` command. +> The CLI examples below document the retired validator surface and must not be +> treated as current package behavior unless validator support is reintroduced +> with tests. + ## Overview Contract units are the **core governance artifacts** in Base120. They serve as **executable specifications** that define: @@ -25,12 +31,19 @@ Contract units are **independent governance artifacts** but MUST align with Base ## CLI Usage -### Installation +This section is historical. For current SDK commands, use `base120 list`, +`base120 get`, `base120 prompt`, and `base120 families`. + +### Historical Installation -Install Base120 with pip: +The retired validator was once installed as a package. Do not use this snippet +as current release guidance; the active v2 SDK is installed from this source +tree until a package is published. ```bash -pip install base120 +git clone https://github.com/hummbl-dev/base120.git +cd base120 +python -m pip install -e ".[test]" ``` ### Validating a Contract Unit @@ -339,8 +352,8 @@ jobs: uses: actions/setup-python@v4 with: python-version: '3.12' - - name: Install Base120 - run: pip install base120 + - name: Install Base120 from source + run: python -m pip install -e ".[test]" - name: Validate Contract run: base120 validate-contract contracts/service-contract.json ``` diff --git a/docs/observability.md b/docs/observability.md index e836e63..0da435f 100644 --- a/docs/observability.md +++ b/docs/observability.md @@ -1,9 +1,14 @@ # Base120 Observability Contract -**Version:** v1.0.0 -**Status:** Governance-guaranteed (Indicated work) +**Version:** v1.0.0 +**Status:** Archived v1 validator contract **Failure Mode Addressed:** FM19 (Observability Failure) +> **Current SDK note (2026-05-24):** the `base120` v2 SDK does not expose +> `base120.validators` or `base120.observability`. This document preserves the +> retired v1 validator observability contract; it is not a current package API +> promise. + --- ## Purpose diff --git a/tests/test_docs_current_contract.py b/tests/test_docs_current_contract.py new file mode 100644 index 0000000..f00127c --- /dev/null +++ b/tests/test_docs_current_contract.py @@ -0,0 +1,77 @@ +"""Public documentation checks for the current Base120 package surface.""" + +from __future__ import annotations + +from pathlib import Path +import tomllib + +import base120 + + +ROOT = Path(__file__).resolve().parents[1] + + +def _read(relative: str) -> str: + return (ROOT / relative).read_text(encoding="utf-8") + + +def _flat(text: str) -> str: + return " ".join(text.split()) + + +def test_readme_advertises_current_sdk_surface() -> None: + readme = _read("README.md") + flat_readme = _flat(readme) + + unsupported_claims = [ + "Python code has been removed", + "base120 validate-contract path/to", + "from base120.validators", + "from base120.observability", + "pip install base120", + ] + for claim in unsupported_claims: + assert claim not in readme + + assert "does not ship `base120 validate-contract`" in flat_readme + assert "does not expose `base120.observability`" in flat_readme + assert "from base120 import Engine, Ledger" in readme + assert "base120 list" in readme + assert "base120 get P6" in readme + assert "base120 prompt P6" in readme + assert "base120 families" in readme + assert "should not claim PyPI availability" in flat_readme + + +def test_archived_validator_docs_are_marked_as_archived() -> None: + archived_docs = [ + "docs/contract-units.md", + "docs/observability.md", + ] + + for relative in archived_docs: + text = _read(relative) + lower_text = text.lower() + assert "archived v1 validator contract" in lower_text + assert "current" in lower_text + assert "v2 sdk does not" in lower_text + + +def test_current_docs_do_not_claim_pypi_install() -> None: + docs_to_check = [ + "README.md", + "docs/contract-units.md", + "docs/observability.md", + ] + + for relative in docs_to_check: + assert "pip install base120" not in _read(relative) + + +def test_documented_sdk_version_matches_package_metadata() -> None: + pyproject = tomllib.loads((ROOT / "pyproject.toml").read_text(encoding="utf-8")) + version = pyproject["project"]["version"] + + assert base120.__version__ == version + assert version in _read("README.md") + assert version in _read("docs/REPO_HEALTH.md")