capacium-models 0.5.0__tar.gz

capacium_models-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Capacium
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

capacium_models-0.5.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: capacium-models
+Version: 0.5.0
+Summary: Shared domain models for the Capacium ecosystem — Listing, TrustState, TrustMachine, and more
+Author: Capacium
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Capacium/capacium-models
+Project-URL: Repository, https://github.com/Capacium/capacium-models
+Project-URL: Issues, https://github.com/Capacium/capacium-models/issues
+Keywords: capacium,models,listing,trust,ai-agents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+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 :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# capacium-models
+
+> [!NOTE]
+> **Public mirror.** The canonical repository is hosted on our self-hosted git.
+> This GitHub copy is a read-only mirror kept in sync for visibility and
+> installation. Bug reports are welcome via Issues; pull requests are applied
+> upstream and synced back here.
+
+Shared domain models for the Capacium ecosystem. Used by `capacium-exchange` and `capacium-crawler`.
+
+## Installation
+
+```bash
+pip install capacium-models
+```
+
+## Models
+
+| Model | Description |
+|-------|-------------|
+| `TrustState` | Enum: DISCOVERED → PENDING_REVIEW → VERIFIED → SIGNED → DEPRECATED |
+| `TrustMachine` | State machine with VALID_TRANSITIONS, can_transition(), transition() |
+| `Listing` | Full listing model (24 fields, auto-UUID, auto-timestamps) |
+| `Publisher` | Publisher profile with verification support |
+| `MCPClient` | Enum of supported MCP clients |
+| `MCPMetadata` | MCP-specific metadata (transport, runtime, auth_model, etc.) |
+| `Category` / `Subcategory` / `TagCount` | Taxonomy models |
+| `Collection` | Curated collection of listing IDs |
+| `ClaimRequest` / `VerificationRecord` | Trust workflow models |
+| `SearchQuery` | Faceted search query model (16 fields) |
+| `ExchangeSearch` | Faceted search SQL engine |
+
+The package-level `TRUST_BADGES` and `get_trust_badge()` exports retain the
+rich badge metadata introduced in v0.4.0. UI-facing canonical text labels,
+including the string-only trust labels, live in `capacium_models.labels`.
+
+## Usage
+
+```python
+from capacium_models import Listing, TrustState, TrustMachine
+
+# Create a discovered listing
+listing = Listing(
+    canonical_name="org/my-mcp-server",
+    package_type="mcp-server",
+    canonical_source_url="https://github.com/org/my-mcp-server",
+    short_description="A cool MCP server",
+    trust_state=TrustState.DISCOVERED,
+)
+
+# Transition through trust states
+machine = TrustMachine()
+if machine.can_transition(listing.trust_state, TrustState.PENDING_REVIEW):
+    listing = machine.transition(
+        listing,
+        TrustState.PENDING_REVIEW,
+        "Validated metadata",
+    )
+```
+
+## Dependencies
+
+Zero runtime dependencies — stdlib only (`dataclasses`, `enum`, `uuid`, `datetime`, `json`, `typing`).
+
+## License
+
+MIT
+
+## Development
+
+Canonical repository: **self-hosted Forgejo** — `git.langevc.com/capacium/capacium-models`
+(`git clone git@git.langevc.com:capacium/capacium-models.git`). Develop against the Forgejo
+clone and open pull requests there. The GitHub copy is a read-only mirror.

capacium_models-0.5.0/README.md

@@ -0,0 +1,73 @@
+# capacium-models
+
+> [!NOTE]
+> **Public mirror.** The canonical repository is hosted on our self-hosted git.
+> This GitHub copy is a read-only mirror kept in sync for visibility and
+> installation. Bug reports are welcome via Issues; pull requests are applied
+> upstream and synced back here.
+
+Shared domain models for the Capacium ecosystem. Used by `capacium-exchange` and `capacium-crawler`.
+
+## Installation
+
+```bash
+pip install capacium-models
+```
+
+## Models
+
+| Model | Description |
+|-------|-------------|
+| `TrustState` | Enum: DISCOVERED → PENDING_REVIEW → VERIFIED → SIGNED → DEPRECATED |
+| `TrustMachine` | State machine with VALID_TRANSITIONS, can_transition(), transition() |
+| `Listing` | Full listing model (24 fields, auto-UUID, auto-timestamps) |
+| `Publisher` | Publisher profile with verification support |
+| `MCPClient` | Enum of supported MCP clients |
+| `MCPMetadata` | MCP-specific metadata (transport, runtime, auth_model, etc.) |
+| `Category` / `Subcategory` / `TagCount` | Taxonomy models |
+| `Collection` | Curated collection of listing IDs |
+| `ClaimRequest` / `VerificationRecord` | Trust workflow models |
+| `SearchQuery` | Faceted search query model (16 fields) |
+| `ExchangeSearch` | Faceted search SQL engine |
+
+The package-level `TRUST_BADGES` and `get_trust_badge()` exports retain the
+rich badge metadata introduced in v0.4.0. UI-facing canonical text labels,
+including the string-only trust labels, live in `capacium_models.labels`.
+
+## Usage
+
+```python
+from capacium_models import Listing, TrustState, TrustMachine
+
+# Create a discovered listing
+listing = Listing(
+    canonical_name="org/my-mcp-server",
+    package_type="mcp-server",
+    canonical_source_url="https://github.com/org/my-mcp-server",
+    short_description="A cool MCP server",
+    trust_state=TrustState.DISCOVERED,
+)
+
+# Transition through trust states
+machine = TrustMachine()
+if machine.can_transition(listing.trust_state, TrustState.PENDING_REVIEW):
+    listing = machine.transition(
+        listing,
+        TrustState.PENDING_REVIEW,
+        "Validated metadata",
+    )
+```
+
+## Dependencies
+
+Zero runtime dependencies — stdlib only (`dataclasses`, `enum`, `uuid`, `datetime`, `json`, `typing`).
+
+## License
+
+MIT
+
+## Development
+
+Canonical repository: **self-hosted Forgejo** — `git.langevc.com/capacium/capacium-models`
+(`git clone git@git.langevc.com:capacium/capacium-models.git`). Develop against the Forgejo
+clone and open pull requests there. The GitHub copy is a read-only mirror.

capacium_models-0.5.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "capacium-models"
+version = "0.5.0"
+description = "Shared domain models for the Capacium ecosystem — Listing, TrustState, TrustMachine, and more"
+authors = [{name = "Capacium"}]
+requires-python = ">=3.10"
+dependencies = []
+license = "MIT"
+readme = "README.md"
+keywords = ["capacium", "models", "listing", "trust", "ai-agents"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://github.com/Capacium/capacium-models"
+Repository = "https://github.com/Capacium/capacium-models"
+Issues = "https://github.com/Capacium/capacium-models/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]

capacium_models-0.5.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

capacium_models-0.5.0/src/capacium_models/__init__.py

@@ -0,0 +1,66 @@
+"""Shared domain models for the Capacium ecosystem.
+
+Usage:
+    from capacium_models import Listing, TrustState, TrustMachine
+"""
+
+from .models import (
+    MCPClient,
+    MCPMetadata,
+    TrustTransition,
+    Listing,
+    Publisher,
+    Category,
+    Subcategory,
+    TagCount,
+    Collection,
+    ClaimRequest,
+    VerificationRecord,
+    SearchQuery,
+)
+from .trust import TrustState, TrustMachine, TRUST_BADGES, get_trust_badge
+from .keys import (
+    LICENSE_PUBLIC_KEYS,
+    UnknownLicenseKid,
+    get_license_public_key,
+    known_kids,
+)
+from .labels import (
+    RESOURCE_KIND_LABELS,
+    OPERATOR_TYPE_LABELS,
+    INSTALL_STATUS_LABELS,
+    get_kind_label,
+    get_operator_type_label,
+    get_install_status_label,
+)
+from .search import ExchangeSearch
+
+__all__ = [
+    "MCPClient",
+    "MCPMetadata",
+    "TrustState",
+    "TrustTransition",
+    "TrustMachine",
+    "Listing",
+    "Publisher",
+    "Category",
+    "Subcategory",
+    "TagCount",
+    "Collection",
+    "ClaimRequest",
+    "VerificationRecord",
+    "SearchQuery",
+    "ExchangeSearch",
+    "TRUST_BADGES",
+    "get_trust_badge",
+    "RESOURCE_KIND_LABELS",
+    "OPERATOR_TYPE_LABELS",
+    "INSTALL_STATUS_LABELS",
+    "get_kind_label",
+    "get_operator_type_label",
+    "get_install_status_label",
+    "LICENSE_PUBLIC_KEYS",
+    "UnknownLicenseKid",
+    "get_license_public_key",
+    "known_kids",
+]

capacium_models-0.5.0/src/capacium_models/keys.py

@@ -0,0 +1,123 @@
+"""License public-key registry for capacium-models consumers.
+
+Consumers verify license tokens (issued by capacium-exchange `LicenseService`)
+using Ed25519. The matching PRIVATE key lives ONLY in envctl on prod, under:
+
+    envctl get capacium-exchange CAPACIUM_LICENSE_SIGNING_KEY    # 64-hex private
+    envctl get capacium-exchange CAPACIUM_LICENSE_SIGNING_KID    # current kid
+
+This module holds the corresponding PUBLIC keys, indexed by `kid` (key
+identifier as embedded in license token payloads). Consumers use these to
+verify signatures locally without round-tripping to the Exchange.
+
+Key rotation lifecycle for a given kid:
+  - Active:     issues new tokens; PRIVATE held in envctl
+  - Retired:    no longer issues NEW tokens; OLD tokens still validate
+                (entry stays in this registry until last token expires)
+  - Removed:    entry deleted from registry; OLD tokens fail validation
+
+To add a new kid: append to LICENSE_PUBLIC_KEYS, bump the package version
+(minor bump — additive); ship as a new capacium-models release. NEVER
+remove an entry whose tokens may still be in circulation.
+
+DECISION-001 reference: license-signing keypair is DISTINCT from
+capability-signing keypair. kid namespace MUST start with `lic-`.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List
+
+
+# ── License public-key registry ───────────────────────────────────────────
+#
+# Format: dict[kid -> 64-char lowercase hex] (32 bytes Ed25519 public key)
+#
+# Each entry MUST match the private key currently set as
+# CAPACIUM_LICENSE_SIGNING_KEY in envctl on capacium-prod, under the
+# matching kid CAPACIUM_LICENSE_SIGNING_KID.
+
+LICENSE_PUBLIC_KEYS: Dict[str, str] = {
+    # ──────────────────────────────────────────────────────────────────────
+    # kid: lic-2026-q2-01
+    # Added: 2026-06-03 (initial v2 launch — corresponds to the FIRST
+    # Ed25519 keypair generated on maintainer workstation, private uploaded
+    # to envctl on capacium-prod)
+    # ──────────────────────────────────────────────────────────────────────
+    "lic-2026-q2-01": "8e5e33e1ab3676d239a1f89cded6afca9aca0e8ba24c3b4b50ad4b71ef84e978",
+}
+
+
+# ── Public API ────────────────────────────────────────────────────────────
+
+
+class UnknownLicenseKid(KeyError):
+    """Raised when a license token's `kid` is not in the public-key registry.
+
+    Consumers MUST reject the token in this case (treat as invalid signature).
+    Receiving this exception is the signal to upgrade `capacium-models` to a
+    newer version that includes the missing kid.
+    """
+
+
+def get_license_public_key(kid: str) -> str:
+    """Return the 64-char hex public key for a license kid.
+
+    Args:
+        kid: Key identifier as embedded in license token payload.
+
+    Returns:
+        64-char lowercase hex string representing the Ed25519 public key.
+
+    Raises:
+        UnknownLicenseKid: when `kid` is not in `LICENSE_PUBLIC_KEYS`, OR
+            when its registered value is not a valid 64-char hex string
+            (e.g., still a placeholder, malformed registry entry).
+            Consumer code MUST reject the token in this case.
+    """
+    try:
+        pubkey = LICENSE_PUBLIC_KEYS[kid]
+    except KeyError as e:
+        raise UnknownLicenseKid(
+            f"kid={kid!r} not in LICENSE_PUBLIC_KEYS. "
+            f"Known kids: {known_kids()}. "
+            f"Upgrade capacium-models to support newer kids."
+        ) from e
+    _validate_hex(kid, pubkey)
+    return pubkey
+
+
+def known_kids() -> List[str]:
+    """Return all registered kids, sorted newest-first (lexicographic reverse).
+
+    Naming convention `lic-YYYY-qN-NN` makes lex reverse equal to
+    chronological reverse.
+    """
+    return sorted(LICENSE_PUBLIC_KEYS.keys(), reverse=True)
+
+
+# ── Internal helpers ──────────────────────────────────────────────────────
+
+
+def _validate_hex(kid: str, pubkey: str) -> None:
+    """Validate that `pubkey` is a 64-char lowercase hex string.
+
+    Raises UnknownLicenseKid (not ValueError) so consumers handling kid
+    lookup errors have a single exception type to catch.
+    """
+    if not isinstance(pubkey, str):
+        raise UnknownLicenseKid(
+            f"kid={kid!r} has non-string pubkey of type {type(pubkey).__name__}"
+        )
+    if len(pubkey) != 64:
+        raise UnknownLicenseKid(
+            f"kid={kid!r} pubkey length is {len(pubkey)}, expected 64 hex chars. "
+            f"Likely placeholder — registry entry must be filled in before release."
+        )
+    try:
+        int(pubkey, 16)
+    except ValueError as e:
+        raise UnknownLicenseKid(
+            f"kid={kid!r} pubkey is not valid hex: {e}. "
+            f"Registry entry may still contain a placeholder."
+        ) from e

capacium_models-0.5.0/src/capacium_models/labels.py

@@ -0,0 +1,75 @@
+"""Canonical label registries for all Capacium surfaces.
+
+These dicts serve as single sources of truth — all UIs, badges, APIs, and CLI
+surfaces derive their display labels from these exactly maps.
+"""
+
+RESOURCE_KIND_LABELS = {
+    "skill": "Skill",
+    "mcp-server": "MCP Server",
+    "bundle": "Bundle",
+    "tool": "Tool",
+    "prompt": "Prompt",
+    "template": "Template",
+    "workflow": "Workflow",
+    "connector-pack": "Connector Pack",
+    "operator": "Operator",
+    "checkpoint": "Checkpoint",
+    "policy": "Policy",
+    "resource": "Resource",
+}
+
+OPERATOR_TYPE_LABELS = {
+    "ai": "AI",
+    "human": "Human",
+    "hybrid": "Hybrid",
+}
+
+INSTALL_STATUS_LABELS = {
+    "not_installed": "Not Installed",
+    "installing": "Installing",
+    "installed": "Installed",
+    "failed": "Failed",
+    "update_available": "Update Available",
+    "removed": "Removed",
+}
+
+TRUST_BADGES = {
+    "discovered": "Discovered",
+    "pending_review": "Pending Review",
+    "verified": "Verified",
+    "signed": "Signed",
+    "deprecated": "Deprecated",
+}
+
+
+def get_kind_label(kind: str) -> str:
+    """Return the human-readable label for a capability kind.
+
+    Falls back to the raw string if the kind is unknown.
+    """
+    return RESOURCE_KIND_LABELS.get(kind, kind)
+
+
+def get_operator_type_label(op_type: str) -> str:
+    """Return the human-readable label for an operator type.
+
+    Falls back to the raw string if the type is unknown.
+    """
+    return OPERATOR_TYPE_LABELS.get(op_type, op_type)
+
+
+def get_install_status_label(status: str) -> str:
+    """Return the human-readable label for an install status.
+
+    Falls back to the raw string if the status is unknown.
+    """
+    return INSTALL_STATUS_LABELS.get(status, status)
+
+
+def get_trust_badge(state: str) -> str:
+    """Return the human-readable trust badge label for a trust state.
+
+    Falls back to the raw string if the state is unknown.
+    """
+    return TRUST_BADGES.get(state, state)