{"id":50454214,"url":"https://github.com/mizcausevic-dev/model-registry-pro","last_synced_at":"2026-06-01T01:05:45.868Z","repository":{"id":357280933,"uuid":"1233343398","full_name":"mizcausevic-dev/model-registry-pro","owner":"mizcausevic-dev","description":"Model lifecycle catalog for AI agents: versions, lineage, stage promotion, and approval gates. Audit-friendly governance for which version is in prod, who approved it, and what came before.","archived":false,"fork":false,"pushed_at":"2026-05-12T04:26:37.000Z","size":22,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-12T06:27:32.736Z","etag":null,"topics":["ai-agents","approval-workflow","governance","lineage","ml-platform","mlops","model-lifecycle","model-registry","platform-engineering","python"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mizcausevic-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-08T21:24:07.000Z","updated_at":"2026-05-12T04:26:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mizcausevic-dev/model-registry-pro","commit_stats":null,"previous_names":["mizcausevic-dev/model-registry-pro"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mizcausevic-dev/model-registry-pro","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizcausevic-dev%2Fmodel-registry-pro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizcausevic-dev%2Fmodel-registry-pro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizcausevic-dev%2Fmodel-registry-pro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizcausevic-dev%2Fmodel-registry-pro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mizcausevic-dev","download_url":"https://codeload.github.com/mizcausevic-dev/model-registry-pro/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mizcausevic-dev%2Fmodel-registry-pro/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33755379,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","approval-workflow","governance","lineage","ml-platform","mlops","model-lifecycle","model-registry","platform-engineering","python"],"created_at":"2026-06-01T01:05:45.757Z","updated_at":"2026-06-01T01:05:45.848Z","avatar_url":"https://github.com/mizcausevic-dev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# model-registry-pro 🗂️\n\n\u003e Model lifecycle catalog for AI agents: versions, lineage, stage promotion, and approval gates.\n\u003e Audit-friendly governance for *which version is in prod, who approved it, and what came before*.\n\n[![CI](https://github.com/mizcausevic-dev/model-registry-pro/actions/workflows/ci.yml/badge.svg)](https://github.com/mizcausevic-dev/model-registry-pro/actions/workflows/ci.yml)\n![Python](https://img.shields.io/badge/python-3.10%2B-blue)\n![License](https://img.shields.io/badge/license-MIT-green)\n![Status](https://img.shields.io/badge/status-alpha-orange)\n\n---\n\n## Demo\n\nA complete approval workflow: register three lineage-linked model versions,\nauto-promote DEV -\u003e STAGING, request STAGING -\u003e PROD with mandatory review,\napprove, and confirm the new production version:\n\n![Demo output](docs/demo-output.svg)\n\n## Why\n\nEvery team running AI agents in production keeps the same things in spreadsheets,\nsticky notes, or Slack DMs:\n\n- *Which model version is actually in prod right now?*\n- *Who approved that?*\n- *What was it derived from? What's it derived into?*\n- *Can we even roll back to the previous version cleanly?*\n\nWhen auditors, compliance, or your own incident response team asks - and\nthey will - the answer can't be \"let me dig.\"\n\n**model-registry-pro is the tiny, embeddable governance layer that makes those\nquestions trivial.**\n\n## What\n\nSix primitives, zero runtime dependencies:\n\n| Component | Purpose |\n|---|---|\n| `ModelVersion` | Frozen `(name, version)` identity for any registered artifact |\n| `Model` | Metadata wrapper with description, parent lineage link, tags, and provenance |\n| `Stage` | Lifecycle FSM: DEV -\u003e STAGING -\u003e PROD -\u003e DEPRECATED -\u003e RETIRED |\n| `Approval` | Audit-trailed promotion request with requester, approver, timestamps, notes |\n| `LineageGraph` | Parent/child queries: ancestors, descendants, BFS over derivations |\n| `ModelRegistry` | Facade combining all of the above with a pluggable `PromotionPolicy` |\n\n## Architecture\n\n![Architecture](docs/architecture.svg)\n\n## Lifecycle FSM\n\nStage transitions are controlled - not every move is allowed, and most are gated by policy:\n\n![Lifecycle](docs/lifecycle.svg)\n\n## Install\n\n```bash\npip install model-registry-pro\n```\n\nOr from source:\n\n```bash\ngit clone https://github.com/mizcausevic-dev/model-registry-pro\ncd model-registry-pro\npip install -e \".[dev]\"\npytest\n```\n\n## Quickstart\n\n### Register a lineage chain\n\n```python\nfrom model_registry_pro import ModelRegistry, Model, ModelVersion, DefaultPolicy\n\nregistry = ModelRegistry(policy=DefaultPolicy(approvers={\"alice\", \"bob\"}))\n\n# Base model\nv1 = Model(version=ModelVersion(\"rag-agent\", \"1.0.0\"), description=\"initial release\")\nregistry.register(v1)\n\n# Fine-tuned descendant\nv2 = Model(\n    version=ModelVersion(\"rag-agent\", \"2.0.0\"),\n    description=\"fine-tuned on customer logs\",\n    parent=v1.version,\n    metadata={\"params\": \"1.5B\", \"training_corpus\": \"customer-2024-q4\"},\n)\nregistry.register(v2)\n```\n\n### Promote with approval gate\n\n```python\nfrom model_registry_pro import Stage\n\n# DEV -\u003e STAGING is auto-approved (default policy)\nregistry.request_promotion(v2.version, Stage.STAGING, requested_by=\"dev1\")\nassert registry.stage_of(v2.version) == Stage.STAGING\n\n# STAGING -\u003e PROD requires a designated approver\npending = registry.request_promotion(\n    v2.version, Stage.PROD,\n    requested_by=\"dev1\",\n    notes=\"passed eval suite, p95 latency = 380ms\",\n)\n# pending.state == ApprovalState.PENDING; stage NOT yet changed\n\n# Reviewer approves\nregistry.approve(pending.id, approved_by=\"alice\", notes=\"LGTM\")\nassert registry.stage_of(v2.version) == Stage.PROD\n```\n\n### Query the catalog\n\n```python\n# What's currently serving production traffic?\nprod = registry.production_version(\"rag-agent\")  # -\u003e Model(rag-agent:2.0.0)\n\n# What's pending review?\nqueue = registry.pending_approvals()             # -\u003e List[Approval]\n\n# Lineage queries\nancestors = registry.ancestors(v2.version)       # -\u003e [Model(rag-agent:1.0.0)]\nchildren = registry.descendants(v1.version)      # -\u003e [Model(rag-agent:2.0.0)]\n\n# Filter by stage\nin_dev = registry.by_stage(Stage.DEV)\ndeprecated = registry.by_stage(Stage.DEPRECATED)\n```\n\n### Custom policy\n\n```python\nfrom model_registry_pro.policy import OpenPolicy\n\n# No approvals required (useful for staging environments / tests)\nregistry = ModelRegistry(policy=OpenPolicy())\n\n# Or write your own:\nclass TwoPersonRule:\n    def requires_approval(self, mv, current, target):\n        return target == Stage.PROD\n\n    def can_approve(self, approver, mv, target):\n        return approver in {\"alice\", \"bob\", \"carol\"}\n```\n\n## Buyer\n\n- **Platform / MLOps** - drop-in catalog for the model fleet\n- **Compliance / Audit** - deterministic answer to \"who approved what when\"\n- **SRE** - safe rollback path - `production_version()` is always the source of truth\n\n## Pairs With\n\n- [`agent-canary`](https://github.com/mizcausevic-dev/agent-canary) - registry says what versions exist, canary controls who sees which\n- [`agent-router`](https://github.com/mizcausevic-dev/agent-router) - look up `production_version()` to dispatch traffic\n- [`identity-mesh`](https://github.com/mizcausevic-dev/identity-mesh) - approval requester / approver identities can be SPIFFE-bound\n- *Coming:* `agent-trace-ledger` - link inference traces back to the exact model version + approval id\n\n## Roadmap\n\n- [ ] Persistence backend (SQLite / Postgres / DynamoDB adapters)\n- [ ] Webhook on stage transitions (Slack / PagerDuty / GitHub)\n- [ ] Rich semver comparator (currently lexicographic)\n- [ ] Model artifact storage adapter (S3, GCS) with content hashing\n- [ ] Approval policy from declarative YAML\n- [ ] PyPI release\n\n## Doctrine\n\n\u003e *\"In production AI, the question is never 'what model do we use' - it's 'what model\n\u003e do we use right now, who said yes, and what's the rollback path.'\"*\n\nThree rules:\n\n1. **Every promotion is a record.** No silent stage changes. Every state move has an audit row.\n2. **Lineage is mandatory metadata.** A model without a parent declaration is fine; a model with a forgotten parent isn't.\n3. **Production is a stage, not a deploy event.** Knowing what's in prod must be a single function call, not a Slack thread.\n\n## License\n\nMIT - see [LICENSE](./LICENSE).\n\n---\n\nBuilt by [Mirza Causevic](https://github.com/mizcausevic-dev) - Part of the\n[mizcausevic-dev](https://github.com/mizcausevic-dev) AI platform engineering portfolio.\n\n---\n\n**Connect:** [LinkedIn](https://www.linkedin.com/in/mirzacausevic/) · [Kinetic Gain](https://kineticgain.com) · [Medium](https://medium.com/@mizcausevic/) · [Skills](https://mizcausevic.com/skills/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmizcausevic-dev%2Fmodel-registry-pro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmizcausevic-dev%2Fmodel-registry-pro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmizcausevic-dev%2Fmodel-registry-pro/lists"}