rock-kb 0.1.0__tar.gz

rock_kb-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.DS_Store
+.venv/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.pyc
+docs/log/
+data/
+service/dist/
+service/.wrangler/
+service/node_modules/
+agent/*.generated.tmp

rock_kb-0.1.0/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: rock-kb
+Version: 0.1.0
+Summary: Thin CLI client for the public Rock RMS agent knowledge base.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# rock-kb
+
+Thin terminal client for the public Rock RMS agent knowledge base.
+
+Current public install from GitHub, before the PyPI package is released:
+
+```bash
+uvx --from 'git+https://github.com/ONE-ALL-Church/rock-agent-kb#subdirectory=clients/python' rock-kb search "check-in labels not printing"
+uvx --from 'git+https://github.com/ONE-ALL-Church/rock-agent-kb#subdirectory=clients/python' rock-kb get check-in
+uvx --from 'git+https://github.com/ONE-ALL-Church/rock-agent-kb#subdirectory=clients/python' rock-kb claims workflows --min-tier source_backed
+uvx --from 'git+https://github.com/ONE-ALL-Church/rock-agent-kb#subdirectory=clients/python' rock-kb dashboard
+uvx --from 'git+https://github.com/ONE-ALL-Church/rock-agent-kb#subdirectory=clients/python' rock-kb mcp-config
+```
+
+After the client is published to PyPI, the shorter package-registry form works:
+
+```bash
+uvx rock-kb search "check-in labels not printing"
+uvx rock-kb get check-in
+uvx rock-kb claims workflows --min-tier source_backed
+uvx rock-kb dashboard
+uvx rock-kb mcp-config
+```
+
+From a local `rock-agent-kb` checkout before the package is published:
+
+```bash
+uv run --project clients/python rock-kb search "check-in labels not printing"
+uv run --project clients/python rock-kb validate bundle.jsonl
+ROCK_KB_TOKEN=<issued-token> uv run --project clients/python rock-kb submit bundle.jsonl --org <org-id>
+```
+
+Set `ROCK_KB_URL` to point at a staging service. Set `ROCK_KB_TOKEN` when submitting bundles.
+
+Hosted submission is token-gated per organization. If `rock-kb submit` reports
+that `ROCK_KB_TOKEN` is required, ask a Rock KB maintainer to issue a token for
+the reviewed `orgs/<org-id>.yaml` registration. Store the token in an
+environment variable, CI/app secret, or local secret store such as macOS
+Keychain; do not save it in repo files.

rock_kb-0.1.0/README.md

@@ -0,0 +1,39 @@
+# rock-kb
+
+Thin terminal client for the public Rock RMS agent knowledge base.
+
+Current public install from GitHub, before the PyPI package is released:
+
+```bash
+uvx --from 'git+https://github.com/ONE-ALL-Church/rock-agent-kb#subdirectory=clients/python' rock-kb search "check-in labels not printing"
+uvx --from 'git+https://github.com/ONE-ALL-Church/rock-agent-kb#subdirectory=clients/python' rock-kb get check-in
+uvx --from 'git+https://github.com/ONE-ALL-Church/rock-agent-kb#subdirectory=clients/python' rock-kb claims workflows --min-tier source_backed
+uvx --from 'git+https://github.com/ONE-ALL-Church/rock-agent-kb#subdirectory=clients/python' rock-kb dashboard
+uvx --from 'git+https://github.com/ONE-ALL-Church/rock-agent-kb#subdirectory=clients/python' rock-kb mcp-config
+```
+
+After the client is published to PyPI, the shorter package-registry form works:
+
+```bash
+uvx rock-kb search "check-in labels not printing"
+uvx rock-kb get check-in
+uvx rock-kb claims workflows --min-tier source_backed
+uvx rock-kb dashboard
+uvx rock-kb mcp-config
+```
+
+From a local `rock-agent-kb` checkout before the package is published:
+
+```bash
+uv run --project clients/python rock-kb search "check-in labels not printing"
+uv run --project clients/python rock-kb validate bundle.jsonl
+ROCK_KB_TOKEN=<issued-token> uv run --project clients/python rock-kb submit bundle.jsonl --org <org-id>
+```
+
+Set `ROCK_KB_URL` to point at a staging service. Set `ROCK_KB_TOKEN` when submitting bundles.
+
+Hosted submission is token-gated per organization. If `rock-kb submit` reports
+that `ROCK_KB_TOKEN` is required, ask a Rock KB maintainer to issue a token for
+the reviewed `orgs/<org-id>.yaml` registration. Store the token in an
+environment variable, CI/app secret, or local secret store such as macOS
+Keychain; do not save it in repo files.

rock_kb-0.1.0/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "rock-kb"
+version = "0.1.0"
+description = "Thin CLI client for the public Rock RMS agent knowledge base."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = []
+
+[project.scripts]
+rock-kb = "rock_kb_client.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/rock_kb_client"]

rock_kb-0.1.0/src/rock_kb_client/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

rock_kb-0.1.0/src/rock_kb_client/cli.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from urllib import request
+
+from .validator import validate_bundle
+
+DEFAULT_BASE_URL = "https://rock-agent-kb.oneandall.church"
+USER_AGENT = "rock-kb-client/0.1 (+https://github.com/ONE-ALL-Church/rock-agent-kb)"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="rock-kb")
+    parser.add_argument("--url", default=os.environ.get("ROCK_KB_URL", DEFAULT_BASE_URL), help="Rock KB service base URL")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    search = subparsers.add_parser("search")
+    search.add_argument("query")
+    search.add_argument("--limit", type=int, default=10)
+    search.add_argument("--min-tier", default="routing_context_only")
+
+    subparsers.add_parser("concepts")
+    get = subparsers.add_parser("get")
+    get.add_argument("concept_id")
+
+    claims = subparsers.add_parser("claims")
+    claims.add_argument("concept_id")
+    claims.add_argument("--tier")
+    claims.add_argument("--min-tier", default="routing_context_only")
+
+    subparsers.add_parser("manifest")
+    subparsers.add_parser("dashboard")
+
+    validate = subparsers.add_parser("validate")
+    validate.add_argument("bundle", type=Path)
+
+    submit = subparsers.add_parser("submit")
+    submit.add_argument("bundle", type=Path)
+    submit.add_argument("--org", required=True)
+
+    subparsers.add_parser("mcp-config")
+
+    args = parser.parse_args(argv)
+    base_url = str(args.url).rstrip("/")
+
+    if args.command == "search":
+        return print_json(get_json(f"{base_url}/search?q={quote(args.query)}&limit={args.limit}&min_tier={quote(args.min_tier)}"))
+    if args.command == "concepts":
+        return print_json(get_json(f"{base_url}/concepts"))
+    if args.command == "get":
+        return print_text(get_text(f"{base_url}/concepts/{quote(args.concept_id)}.md"))
+    if args.command == "claims":
+        suffix = f"?min_tier={quote(args.min_tier)}"
+        if args.tier:
+            suffix += f"&tier={quote(args.tier)}"
+        return print_json(get_json(f"{base_url}/claims/{quote(args.concept_id)}{suffix}"))
+    if args.command == "manifest":
+        return print_json(get_json(f"{base_url}/manifest.json"))
+    if args.command == "dashboard":
+        return print_json(get_json(f"{base_url}/operations/dashboard"))
+    if args.command == "validate":
+        errors = validate_bundle(args.bundle)
+        if errors:
+            for error in errors:
+                print(f"ERROR {error}", file=sys.stderr)
+            return 1
+        return print_json({"status": "ok", "file": str(args.bundle)})
+    if args.command == "submit":
+        errors = validate_bundle(args.bundle)
+        if errors:
+            for error in errors:
+                print(f"ERROR {error}", file=sys.stderr)
+            return 1
+        token = os.environ.get("ROCK_KB_TOKEN")
+        if not token:
+            print("ERROR ROCK_KB_TOKEN is required for submit", file=sys.stderr)
+            return 1
+        rows = [json.loads(line) for line in args.bundle.read_text(encoding="utf-8").splitlines() if line.strip()]
+        return print_json(post_json(f"{base_url}/submit", {"org_id": args.org, "bundle": rows}, token=token))
+    if args.command == "mcp-config":
+        return print_json(
+            {
+                "mcpServers": {
+                    "rock-kb": {
+                        "type": "http",
+                        "url": f"{base_url}/mcp"
+                    }
+                }
+            }
+        )
+    return 1
+
+
+def get_json(url: str):
+    return json.loads(get_text(url))
+
+
+def get_text(url: str) -> str:
+    req = request.Request(url, headers={"user-agent": USER_AGENT})
+    with request.urlopen(req) as response:
+        return response.read().decode("utf-8")
+
+
+def post_json(url: str, payload: dict, token: str):
+    body = json.dumps(payload).encode("utf-8")
+    req = request.Request(
+        url,
+        data=body,
+        method="POST",
+        headers={
+            "content-type": "application/json",
+            "authorization": f"Bearer {token}",
+            "user-agent": USER_AGENT,
+            "accept": "application/json",
+        },
+    )
+    with request.urlopen(req) as response:
+        return json.loads(response.read().decode("utf-8"))
+
+
+def quote(value: str) -> str:
+    from urllib.parse import quote as url_quote
+
+    return url_quote(value, safe="")
+
+
+def print_json(value) -> int:
+    print(json.dumps(value, indent=2, sort_keys=True))
+    return 0
+
+
+def print_text(value: str) -> int:
+    print(value, end="" if value.endswith("\n") else "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

rock_kb-0.1.0/src/rock_kb_client/validator.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from urllib.parse import urlparse
+
+SCHEMA = "rock-kb-org-contribution-v1"
+CONTRIBUTION_TYPES = {
+    "task_card",
+    "troubleshooting_pattern",
+    "release_caveat",
+    "entity_note",
+    "guide_section",
+    "source_link",
+    "open_question",
+}
+PUBLIC_REVIEW_STATUSES = {"redaction_reviewed", "approved_for_public_distillation"}
+CONFIDENCE_VALUES = {"low", "medium", "high", "needs_review"}
+REQUIRED_FIELDS = {
+    "schema",
+    "contribution_id",
+    "org_id",
+    "concept_ids",
+    "contribution_type",
+    "title",
+    "distilled_summary",
+    "source_urls",
+    "source_record_ids",
+    "redaction_attestation",
+    "review_status",
+    "license_attestation",
+    "confidence",
+    "needs_live_verification",
+}
+PRIVATE_FIELD_NAMES = {
+    "raw_text",
+    "full_text",
+    "content",
+    "html",
+    "markdown",
+    "transcript",
+    "media_url",
+    "private_path",
+    "private_source_paths",
+    "private_corpus_pointer",
+}
+PRIVATE_PATH_PREFIXES = (
+    "data/review/",
+    "data/media/",
+    "data/normalized/",
+    "data/raw-manifests/",
+    "data/index/",
+)
+DIRECT_MEDIA_URL_HINTS = (
+    ".mp3",
+    ".mp4",
+    ".m3u8",
+    ".mpd",
+    "player.vimeo.com",
+    "oauth2_token_id=",
+    "access_token=",
+    "signature=",
+)
+SENSITIVE_PATTERNS = (
+    re.compile(r"(?i)(?:^|[^A-Za-z0-9_-])(password|secret|api[_-]?key|token)\s*[:=]\s*['\"]?[^'\"\s]+"),
+    re.compile(r"(?<![A-Za-z0-9_-])sk-[A-Za-z0-9_-]{20,}(?![A-Za-z0-9_-])"),
+    re.compile(r"(?i)connectionstring\s*[:=]"),
+)
+
+
+def validate_bundle(path: Path) -> list[str]:
+    errors: list[str] = []
+    seen_ids: dict[str, str] = {}
+    for line_number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), start=1):
+        if not line.strip():
+            continue
+        label = f"{path}:{line_number}"
+        try:
+            row = json.loads(line)
+        except json.JSONDecodeError as exc:
+            errors.append(f"{label} invalid JSONL: {exc.msg}")
+            continue
+        if not isinstance(row, dict):
+            errors.append(f"{label} row must be an object")
+            continue
+        contribution_id = str(row.get("contribution_id") or "")
+        if contribution_id:
+            if contribution_id in seen_ids:
+                errors.append(f"{label} duplicate contribution_id {contribution_id}; first seen at {seen_ids[contribution_id]}")
+            else:
+                seen_ids[contribution_id] = label
+        errors.extend(validate_row(row, label))
+    return errors
+
+
+def validate_row(row: dict, label: str) -> list[str]:
+    errors: list[str] = []
+    missing = sorted(field for field in REQUIRED_FIELDS if field not in row or row.get(field) is None)
+    if missing:
+        errors.append(f"{label} missing fields: {', '.join(missing)}")
+    if row.get("schema") != SCHEMA:
+        errors.append(f"{label} schema must be {SCHEMA}")
+    if row.get("contribution_type") not in CONTRIBUTION_TYPES:
+        errors.append(f"{label} invalid contribution_type")
+    if row.get("review_status") not in PUBLIC_REVIEW_STATUSES:
+        errors.append(f"{label} public contribution must be redaction_reviewed or approved_for_public_distillation")
+    if row.get("confidence") not in CONFIDENCE_VALUES:
+        errors.append(f"{label} invalid confidence")
+    if not isinstance(row.get("needs_live_verification"), bool):
+        errors.append(f"{label} needs_live_verification must be true or false")
+    if not isinstance(row.get("concept_ids"), list) or not row.get("concept_ids"):
+        errors.append(f"{label} concept_ids must be a non-empty list")
+    if not isinstance(row.get("source_urls"), list):
+        errors.append(f"{label} source_urls must be a list")
+    if not isinstance(row.get("source_record_ids"), list):
+        errors.append(f"{label} source_record_ids must be a list")
+    if not row.get("source_urls") and not row.get("source_record_ids"):
+        errors.append(f"{label} must include source_urls or source_record_ids")
+    for url in row.get("source_urls") or []:
+        if not isinstance(url, str):
+            errors.append(f"{label} source_urls must contain strings")
+        elif url and urlparse(url).scheme and urlparse(url).scheme not in {"http", "https"}:
+            errors.append(f"{label} source_urls must use http or https URLs")
+    if not truthy_attestation(row.get("redaction_attestation")):
+        errors.append(f"{label} redaction_attestation must be true or an affirmative string")
+    if not truthy_attestation(row.get("license_attestation")):
+        errors.append(f"{label} license_attestation must be true or an affirmative string")
+    errors.extend(f"{label} {message}" for message in find_leaks(row))
+    return errors
+
+
+def find_leaks(row: dict) -> list[str]:
+    errors: list[str] = []
+    for field_path in prohibited_public_field_paths(row):
+        errors.append(f"contains prohibited public field: {field_path}")
+    serialized = json.dumps(row, ensure_ascii=False)
+    for line in serialized.splitlines():
+        for pattern in SENSITIVE_PATTERNS:
+            if pattern.search(line):
+                errors.append(f"contains sensitive-looking value: {line.strip()[:120]}")
+                break
+    for path, value in string_values(row):
+        lowered = value.lower()
+        if any(hint in lowered for hint in DIRECT_MEDIA_URL_HINTS):
+            errors.append(f"contains direct/tokenized media URL at {path}: {value[:120]}")
+        normalized = value.replace("\\", "/")
+        if any(prefix in normalized for prefix in PRIVATE_PATH_PREFIXES):
+            errors.append(f"contains private path reference at {path}: {value[:120]}")
+    return errors
+
+
+def prohibited_public_field_paths(value, prefix: str = "$") -> list[str]:
+    paths: list[str] = []
+    if isinstance(value, dict):
+        for key, nested in value.items():
+            path = f"{prefix}.{key}"
+            if key in PRIVATE_FIELD_NAMES:
+                paths.append(path)
+            paths.extend(prohibited_public_field_paths(nested, path))
+    elif isinstance(value, list):
+        for index, nested in enumerate(value):
+            paths.extend(prohibited_public_field_paths(nested, f"{prefix}[{index}]"))
+    return paths
+
+
+def string_values(value, prefix: str = "$") -> list[tuple[str, str]]:
+    values: list[tuple[str, str]] = []
+    if isinstance(value, dict):
+        for key, nested in value.items():
+            values.extend(string_values(nested, f"{prefix}.{key}"))
+    elif isinstance(value, list):
+        for index, nested in enumerate(value):
+            values.extend(string_values(nested, f"{prefix}[{index}]"))
+    elif isinstance(value, str):
+        values.append((prefix, value))
+    return values
+
+
+def truthy_attestation(value) -> bool:
+    if value is True:
+        return True
+    return isinstance(value, str) and value.strip().lower() in {"true", "yes", "reviewed", "attested", "approved"}