holoscript-holorepo

Python companion for HoloRepo: a plug-and-play sovereign GitHub + database + HoloScript knowledge store for high-volume agent frameworks.

The Python client covers the DB/KS guest surface. It reads any Postgres reachable by psql, or an explicitly configured owned node over SSH + Docker. No host, IP, or container is assumed by default.

Install

pip install holoscript-holorepo

Config

Use holorepo.config.json or env:

export HOLOREPO_DATABASE_URL="postgres://user@host:5432/app"
export PGPASSWORD="..."

For an owned node over SSH, use the jetsonExample profile as an example and set HOLOREPO_SSH, HOLOREPO_SSH_KEY, and HOLOREPO_POSTGRES_CONTAINER.

Use

holorepo-py db read knowledge "select count(*) from memory_entries"
holorepo-py ks query "storage lanes" 8

from holoscript_holorepo import query_ks, read_db

hits = query_ks("sovereign backbone", limit=5)["rows"]

Reads refuse mutations. Writes are staged by the npm client as holorepo.storage-proof.v1 and admitted by the configured operator route.

Native delivery planning, manifest generation, installer templates, and admission proofs live in the npm CLI:

holorepo delivery plan --class native-service --rail oci --rail compose
holorepo delivery manifest --class native-app --rail web-bundle --rail holoqr
holorepo delivery readback --rail pypi --name holoscript-holorepo --version 0.6.0
holorepo delivery admit --manifest delivery.manifest.json --receipt pypi-readback.json
holorepo delivery promote --admission delivery.admission.json --custody-receipt holokey:lease
holorepo delivery import --promotion-import delivery.promotion-import.json --source offline-tarball=./dist/app.tgz --write
holorepo delivery import --storage-adapter owned-metal --promotion-import delivery.promotion-import.json --source offline-tarball=./dist/app.tgz --destination offline-tarball=ssh://node/path/to/app.tgz --destination-digest offline-tarball=sha256:...
holorepo delivery import --storage-adapter owned-metal --promotion-import delivery.promotion-import.json --source offline-tarball=./dist/app.tgz --destination offline-tarball=scp://node/path/to/app.tgz --copy-profile scp-owned-metal --write

Python frameworks can consume the emitted manifest JSON while the package keeps DB/KS reads dependency-free.

Repository Soul Participation

The companion also builds dependency-free participation envelopes. HoloMesh is modeled as an optional sister product: routine plans target an injected holomesh_suggest adapter, while founder, spend, custody, public commitment, governance, and compliance boundaries require a separate protected-review adapter. Neither route grants authority or mutates source.

from holoscript_holorepo import (
    build_holomesh_participation_plan,
    build_repository_soul_suggestion,
    normalize_participation_result,
)

suggestion = build_repository_soul_suggestion(
    repository_soul,
    {
        "source": {"path": "docs/guide.md", "doorId": "contributing"},
        "submitter": {"kind": "agent", "id": "agent-example"},
        "intent": {
            "kind": "documentation",
            "title": "Clarify setup",
            "description": "Add a tested example.",
        },
    },
)
plan = build_holomesh_participation_plan(suggestion, team_id="team-example")
# The caller may pass plan["operation"]["payload"] to its own adapter.
receipt = normalize_participation_result(
    suggestion,
    plan,
    {"ok": True, "result": {"success": True, "suggestion": {"id": "suggestion-1"}}},
)

The emitted schemas are holorepo.repository-soul-suggestion.v1, holorepo.holomesh-participation-plan.v1, and holorepo.repository-soul-participation-receipt.v1.

Release Boundary

holoscript-holorepo is distributed under the MIT license. The compatibility label is still v0-preview: the Python companion supports config/env-driven DB/KS reads for agent frameworks, while write admission remains in the npm client and HoloGate/HoloKey operator lane. The npm client also writes delivery promotion import receipts, filesystem storage-import byte receipts, object/owned-metal destination digest proof receipts, and opt-in provider-copy profile receipts (aws-s3, rclone-copyto, mc-cp, or scp-owned-metal) that bind admitted mirrors back to HoloRepo custody.