Metadata-Version: 2.4
Name: holoscript-holorepo
Version: 0.6.0
Summary: Python companion for HoloRepo: plug-and-play sovereign DB + HoloScript KS for agent frameworks.
Author: HoloScript ecosystem
License-Expression: MIT
Project-URL: Homepage, https://github.com/brianonbased-dev/ai-ecosystem/tree/main/packages/holorepo-py
Project-URL: Source, https://github.com/brianonbased-dev/ai-ecosystem
Project-URL: Doctrine, https://github.com/brianonbased-dev/ai-ecosystem/blob/main/docs/handbooks/holorepo-operating-model.md
Keywords: holoscript,holorepo,sovereign,postgres,knowledge-store,agent-framework
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: Database
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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

```bash
pip install holoscript-holorepo
```

## Config

Use `holorepo.config.json` or env:

```bash
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

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

```python
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:

```bash
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.

```python
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.
