holoscript-holorepo 0.2.0__py3-none-any.whl

holoscript_holorepo/__init__.py

@@ -0,0 +1,225 @@
+"""holoscript-holorepo: Python companion for HoloRepo.
+
+The client is config/env driven. It can read any Postgres reachable by `psql`,
+or an explicitly configured owned node over SSH + docker exec. No host, IP, or
+container is assumed by default.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import subprocess
+from pathlib import Path
+from urllib.parse import urlsplit, urlunsplit
+
+__version__ = "0.2.0"
+RELEASE_LANE = "v0-preview"
+CONFIG_SCHEMA = "holorepo.config.v1"
+
+_MUTATION = re.compile(r"\b(insert|update|delete|drop|alter|create|truncate|grant|revoke|copy|merge|call)\b", re.I)
+_READ_HEAD = re.compile(r"^(select|with|explain|show|table)\b", re.I)
+
+
+def default_config() -> dict:
+    return {
+        "schema": CONFIG_SCHEMA,
+        "productName": "HoloRepo",
+        "activeProfile": "local",
+        "storage": {"kind": "filesystem", "root": ".holorepo/storage"},
+        "git": {"backend": "local-bare", "root": ".holorepo/git"},
+        "database": {"transport": "direct-psql", "connectionEnv": "HOLOREPO_DATABASE_URL"},
+        "knowledgeStore": {"database": "knowledge", "table": "memory_entries"},
+        "agents": {"maxConcurrentWriters": 100},
+        "profiles": {
+            "jetsonExample": {
+                "note": "Example only. HoloRepo no longer assumes this host, container, or path.",
+                "database": {
+                    "transport": "ssh-docker-psql",
+                    "ssh": {"hostEnv": "HOLOREPO_SSH", "keyEnv": "HOLOREPO_SSH_KEY"},
+                    "docker": {"containerEnv": "HOLOREPO_POSTGRES_CONTAINER"},
+                    "userEnv": "HOLOREPO_DATABASE_USER",
+                },
+            }
+        },
+    }
+
+
+def _merge(a: dict, b: dict) -> dict:
+    out = dict(a)
+    for key, value in (b or {}).items():
+        if isinstance(value, dict) and isinstance(out.get(key), dict):
+            out[key] = _merge(out[key], value)
+        else:
+            out[key] = value
+    return out
+
+
+def load_config(path: str | None = None, env: dict | None = None) -> dict:
+    env = os.environ if env is None else env
+    target = Path(path or env.get("HOLOREPO_CONFIG", "holorepo.config.json"))
+    cfg = json.loads(target.read_text()) if target.exists() else default_config()
+    if "$schema" in cfg and "schema" not in cfg:
+        cfg["schema"] = cfg["$schema"]
+    profile = env.get("HOLOREPO_CONFIG_PROFILE") or cfg.get("activeProfile") or cfg.get("profile")
+    if profile and cfg.get("profiles", {}).get(profile):
+        cfg = _merge(cfg, cfg["profiles"][profile])
+        cfg["activeProfile"] = profile
+    if env.get("HOLOREPO_DATABASE_URL"):
+        cfg["database"] = _merge(cfg.get("database", {}), {"transport": "direct-psql", "connectionEnv": "HOLOREPO_DATABASE_URL"})
+    elif env.get("DATABASE_URL"):
+        cfg["database"] = _merge(cfg.get("database", {}), {"transport": "direct-psql", "connectionEnv": "DATABASE_URL"})
+    return cfg
+
+
+def _sha256(text: str) -> str:
+    return "sha256:" + hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def is_read_only_sql(sql: str) -> bool:
+    s = (sql or "").strip().rstrip(";").strip()
+    if not s:
+        return False
+    if ";" in s:
+        return False
+    if s.startswith("\\"):
+        return True
+    return bool(_READ_HEAD.match(s)) and not _MUTATION.search(s)
+
+
+def sanitize_term(term: str) -> str:
+    return re.sub(r"\s+", " ", re.sub(r"[%_\\']", " ", term or "")).strip()[:120]
+
+
+def safe_table(name: str = "memory_entries") -> str:
+    if not re.match(r"^[a-z_][a-z0-9_]*$", name or "", re.I):
+        raise ValueError(f"unsafe SQL identifier: {name}")
+    return name
+
+
+def build_ks_query(term: str, domain: str | None = None, limit: int = 10, table: str = "memory_entries") -> str:
+    t = sanitize_term(term)
+    tbl = safe_table(table)
+    dom = f" and domain = '{sanitize_term(domain)}'" if domain else ""
+    lim = max(1, min(50, int(limit) if str(limit).isdigit() else 10))
+    return (
+        "select id, domain, type, coalesce(confidence,0), "
+        "left(regexp_replace(content, '\\s+', ' ', 'g'), 150) "
+        f"from {tbl} where content ILIKE '%{t}%'{dom} and coalesce(is_stale,false)=false "
+        f"order by coalesce(reuse_count,0) desc, updated_at desc limit {lim}"
+    )
+
+
+def redact_connection_string(value: str | None) -> str | None:
+    if not value:
+        return value
+    try:
+        parts = urlsplit(value)
+        host = parts.hostname or "host"
+        port = f":{parts.port}" if parts.port else ""
+        user = "redacted@" if parts.username else ""
+        return urlunsplit((parts.scheme, f"{user}{host}{port}", parts.path, parts.query, parts.fragment))
+    except Exception:
+        return re.sub(r"//[^:@/\s]+:[^@/\s]+@", "//redacted:redacted@", value)
+
+
+def _split_password_from_url(value: str):
+    if not value:
+        return value, None
+    try:
+        parts = urlsplit(value)
+        if not parts.password:
+            return value, None
+        host = parts.hostname or ""
+        port = f":{parts.port}" if parts.port else ""
+        netloc = f"{parts.username}@{host}{port}" if parts.username else f"{host}{port}"
+        return urlunsplit((parts.scheme, netloc, parts.path, parts.query, parts.fragment)), parts.password
+    except Exception:
+        return value, None
+
+
+def redact_db_summary(db: str, config: dict | None = None, env: dict | None = None) -> str:
+    env = os.environ if env is None else env
+    config = load_config(env=env) if config is None else config
+    db_cfg = config.get("database", {})
+    transport = db_cfg.get("transport", "direct-psql")
+    env_name = db_cfg.get("connectionEnv")
+    if env_name and env.get(env_name):
+        return f"{redact_connection_string(env[env_name])} db={db} ({transport}, redacted)"
+    return f"postgres://<{env_name or 'HOLOREPO_DATABASE_URL'}>/{db} ({transport}, redacted)"
+
+
+def _run_psql(db: str, sql: str, meta: bool = False, config: dict | None = None, env: dict | None = None):
+    env = os.environ if env is None else env
+    config = load_config(env=env) if config is None else config
+    db_cfg = config.get("database", {})
+    transport = db_cfg.get("transport", "direct-psql")
+    password = None
+    if transport == "direct-psql":
+        env_name = db_cfg.get("connectionEnv", "HOLOREPO_DATABASE_URL")
+        conn = env.get(env_name)
+        if not conn:
+            return False, "", f"direct-psql needs {env_name}"
+        conn, password = _split_password_from_url(conn)
+        args = ["psql", "-X", conn, "-c" if meta else "-tAc", sql]
+    elif transport == "ssh-docker-psql":
+        ssh = db_cfg.get("ssh", {})
+        docker = db_cfg.get("docker", {})
+        host = ssh.get("host") or env.get(ssh.get("hostEnv", "HOLOREPO_SSH"))
+        key = ssh.get("keyPath") or env.get(ssh.get("keyEnv", "HOLOREPO_SSH_KEY"))
+        container = docker.get("container") or env.get(docker.get("containerEnv", "HOLOREPO_POSTGRES_CONTAINER"))
+        user = db_cfg.get("user") or env.get(db_cfg.get("userEnv", "HOLOREPO_DATABASE_USER"), "postgres")
+        if not host:
+            return False, "", "ssh-docker-psql needs database.ssh.host or hostEnv"
+        if not container:
+            return False, "", "ssh-docker-psql needs database.docker.container or containerEnv"
+        esc = sql.replace("'", "'\\''")
+        flag = "" if meta else "-tA"
+        remote = f"sudo docker exec '{container}' psql -U '{user}' -d '{db}' {flag} -c '{esc}'"
+        args = ["ssh", "-o", "StrictHostKeyChecking=no", "-o", "ConnectTimeout=15"]
+        if key:
+            args.extend(["-i", os.path.expanduser(key)])
+        args.extend([host, remote])
+    else:
+        return False, "", f"unsupported database transport: {transport}"
+    child_env = dict(os.environ)
+    child_env.update(env)
+    if transport == "direct-psql" and password and not child_env.get("PGPASSWORD"):
+        child_env["PGPASSWORD"] = password
+    proc = subprocess.run(args, capture_output=True, text=True, timeout=30, env=child_env)
+    return proc.returncode == 0, proc.stdout.strip(), proc.stderr.strip()
+
+
+def read_db(db: str, sql: str, config: dict | None = None, env: dict | None = None) -> dict:
+    if not is_read_only_sql(sql):
+        return {"ok": False, "refused": True}
+    ok, out, err = _run_psql(db, sql, meta=sql.strip().startswith("\\"), config=config, env=env)
+    if not ok:
+        return {"ok": False, "err": err}
+    rows = out.split("\n") if out else []
+    receipt = {
+        "schema": "holorepo.db-read-receipt.v1",
+        "backend": (config or load_config(env=env)).get("database", {}).get("transport", "direct-psql"),
+        "db": db,
+        "connection": redact_db_summary(db, config=config, env=env),
+        "query_digest": _sha256(sql),
+        "result_digest": _sha256(out),
+        "row_count": len(rows),
+        "read_only": True,
+    }
+    return {"ok": True, "out": out, "rows": len(rows), "receipt": receipt}
+
+
+def query_ks(term: str, domain: str | None = None, limit: int = 10, config: dict | None = None, env: dict | None = None) -> dict:
+    config = load_config(env=env) if config is None else config
+    ks = config.get("knowledgeStore", {})
+    ok, out, err = _run_psql(ks.get("database", "knowledge"), build_ks_query(term, domain, limit, ks.get("table", "memory_entries")), config=config, env=env)
+    if not ok:
+        return {"ok": False, "err": err}
+    rows = []
+    for line in filter(None, out.split("\n")):
+        parts = line.split("|")
+        if len(parts) >= 5:
+            rows.append({"id": parts[0], "domain": parts[1], "type": parts[2], "confidence": parts[3], "snippet": parts[4]})
+    return {"ok": True, "term": sanitize_term(term), "rows": rows}

holoscript_holorepo/cli.py

@@ -0,0 +1,58 @@
+"""holorepo-py CLI."""
+from __future__ import annotations
+
+import json
+import sys
+
+from . import default_config, load_config, query_ks, read_db
+
+HELP = """holorepo-py - Python companion for HoloRepo
+
+  holorepo-py config                     print resolved config
+  holorepo-py db read <db> "<sql>"        guest read (SELECT/meta only) + receipt
+  holorepo-py ks query "<text>" [limit]   configured HoloScript KS read
+
+Config: holorepo.config.json + env. No host, IP, or container is assumed.
+"""
+
+
+def main(argv=None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if not argv or argv[0] in ("-h", "--help"):
+        print(HELP)
+        return 0
+    group = argv[0]
+    if group == "config":
+        print(json.dumps(load_config(), indent=2))
+        return 0
+    if group == "sample":
+        print(json.dumps(default_config(), indent=2))
+        return 0
+    if group == "db" and len(argv) >= 4 and argv[1] == "read":
+        result = read_db(argv[2], argv[3])
+        if result.get("refused"):
+            print("[holorepo-py] REFUSED: read accepts SELECT/meta only; mutations go through stage-write.", file=sys.stderr)
+            return 3
+        if not result["ok"]:
+            print(f"[holorepo-py] query failed: {result['err'][:200]}", file=sys.stderr)
+            return 1
+        print(f"read {argv[2]} ({result['rows']} rows) {result['receipt']['result_digest'][:24]}")
+        print(result["out"][:1600])
+        return 0
+    if group == "ks" and len(argv) >= 3 and argv[1] == "query":
+        limit = int(argv[3]) if len(argv) > 3 and argv[3].isdigit() else 10
+        result = query_ks(argv[2], limit=limit)
+        if not result["ok"]:
+            print(f"[holorepo-py] query failed: {result['err'][:200]}", file=sys.stderr)
+            return 1
+        print(f'"{result["term"]}" - {len(result["rows"])} hit(s)')
+        for row in result["rows"]:
+            print(f"  [{row['domain']}/{row['type']}] {row['snippet']}")
+            print(f"    {row['id']} conf={row['confidence']}")
+        return 0
+    print(HELP, file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

holoscript_holorepo-0.2.0.dist-info/METADATA

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: holoscript-holorepo
+Version: 0.2.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.
+
+## 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.

holoscript_holorepo-0.2.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+holoscript_holorepo/__init__.py,sha256=ifTEeT6guzDgKAvQLc7bdqtgkVSw373eym6JSX52Hho,9667
+holoscript_holorepo/cli.py,sha256=KohNz3zb9wMdERAa5Um4bC8L85NqChPxGS2nIe4Lzsg,2143
+holoscript_holorepo-0.2.0.dist-info/licenses/LICENSE,sha256=b7rhi2piGUvTWuK-gR-z0NMuHUqvbVYE-es4fy51I7Y,1096
+holoscript_holorepo-0.2.0.dist-info/METADATA,sha256=tmFchkMYVVGuZgHClAPv_qhT8fCzlFA5i2kug8Pj-B8,2415
+holoscript_holorepo-0.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+holoscript_holorepo-0.2.0.dist-info/entry_points.txt,sha256=0-2F2urCUEDKi7lDERYKHkJjV6qmUDiiB6z0enSqn7E,61
+holoscript_holorepo-0.2.0.dist-info/top_level.txt,sha256=FBRsbCcrCu5BHVU2Jg1NBEZauG8uslbOFpk05CGC5Ng,20
+holoscript_holorepo-0.2.0.dist-info/RECORD,,

holoscript_holorepo-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

holoscript_holorepo-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+holorepo-py = holoscript_holorepo.cli:main

holoscript_holorepo-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HoloScript ecosystem (Joseph, founder).
+
+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.

holoscript_holorepo-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+holoscript_holorepo