bernstein 2.1.0__tar.gz → 2.2.0__tar.gz

{bernstein-2.1.0 → bernstein-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bernstein
-Version: 2.1.0
+Version: 2.2.0
 Summary: Audit-grade multi-agent orchestration for CLI coding agents (Claude Code, Codex, Gemini CLI, and 40 more): HMAC-chained audit log, signed agent cards, per-artefact lineage, air-gap deploy. The orchestrator your compliance team will sign off on.
 Project-URL: Homepage, https://bernstein.run
 Project-URL: Documentation, https://bernstein.readthedocs.io
@@ -103,6 +103,7 @@ Requires-Dist: grpcio-tools>=1.68; extra == 'grpc'
 Requires-Dist: grpcio>=1.68; extra == 'grpc'
 Requires-Dist: protobuf>=5.29; extra == 'grpc'
 Provides-Extra: gui
+Requires-Dist: qrcode>=7.4; extra == 'gui'
 Requires-Dist: sse-starlette>=2.1.0; extra == 'gui'
 Provides-Extra: k8s
 Requires-Dist: kubernetes>=35.0.0; extra == 'k8s'

{bernstein-2.1.0 → bernstein-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bernstein"
-version = "2.1.0"
+version = "2.2.0"
 description = "Audit-grade multi-agent orchestration for CLI coding agents (Claude Code, Codex, Gemini CLI, and 40 more): HMAC-chained audit log, signed agent cards, per-artefact lineage, air-gap deploy. The orchestrator your compliance team will sign off on."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -184,7 +184,15 @@ eval = ["datasets>=4.8.5", "huggingface-hub>=0.24"]
 # minimal so TUI users keep zero overhead. Enable with:
 #   pip install 'bernstein[gui]'
 # then: bernstein gui serve
-gui = ["sse-starlette>=2.1.0"]
+gui = [
+    "sse-starlette>=2.1.0",
+    # Terminal QR rendering for ``bernstein gui qr`` and the
+    # ``--tunnel`` flag of ``bernstein gui serve`` (#1218). Pure Python,
+    # MIT-licensed, no native deps. The qr renderer ships a fallback
+    # placeholder when this extra is absent so minimal installs do not
+    # crash - they just print a "install qrcode" diagnostic.
+    "qrcode>=7.4",
+]
 # OpenTelemetry OTLP/gRPC exporter for GenAI semantic conventions
 # (src/bernstein/core/observability/otlp_exporter.py). The exporter is a
 # no-op when this extra is absent or BERNSTEIN_OTEL_ENDPOINT is unset, so

bernstein-2.2.0/src/bernstein/cli/commands/bom_cmd.py

@@ -0,0 +1,174 @@
+"""``bernstein bom`` -- emit and verify AI-BOM exports.
+
+The AI Bill of Materials is a deterministic projection over the lineage
+v2 chain, the cost ledger, the decision log and the adapter contract
+YAMLs (see ``bernstein.core.compliance.ai_bom`` for the data model).
+
+Commands:
+
+* ``bernstein bom emit --run <id> [--format <fmt>] [--out <path>]``
+  Read the run snapshot (or load a custom snapshot JSON via
+  ``--snapshot``) and emit the encoded BOM. ``--format`` defaults to
+  ``json`` and accepts ``json``, ``cyclonedx`` and ``spdx``.
+* ``bernstein bom verify <path>`` -- structural verification report.
+
+Both subcommands are pure projections / pure verifications: no network
+calls, no writes outside the resolved output path. This matches the
+"BOM is not a source of truth" invariant in issue #1371.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any, cast
+
+import click
+
+
+@click.group("bom")
+def bom_group() -> None:
+    """AI Bill of Materials -- model/prompt/tool provenance.
+
+    \b
+    Examples:
+      bernstein bom emit --run 20260518-101010 --format cyclonedx
+      bernstein bom emit --snapshot /tmp/run.json --format json --out bom.json
+      bernstein bom verify ./bernstein-2.1.0.bom.json
+    """
+
+
+@bom_group.command("emit")
+@click.option(
+    "--run",
+    "run_id",
+    default=None,
+    help="Bernstein run identifier. Reads .sdd/runs/<run>/bom_snapshot.json.",
+)
+@click.option(
+    "--snapshot",
+    "snapshot_path",
+    default=None,
+    type=click.Path(dir_okay=False, exists=True, resolve_path=True),
+    help="Explicit snapshot JSON path. Mutually exclusive with --run.",
+)
+@click.option(
+    "--format",
+    "fmt",
+    default="json",
+    type=click.Choice(["json", "cyclonedx", "spdx"]),
+    show_default=True,
+    help="Output encoding. Defaults to Bernstein-native JSON.",
+)
+@click.option(
+    "--out",
+    "out_path",
+    default=None,
+    type=click.Path(dir_okay=False, resolve_path=True),
+    help="Write encoded BOM to this path (default: stdout).",
+)
+@click.option(
+    "--workdir",
+    default=".",
+    show_default=True,
+    help="Project root (used to resolve .sdd/runs when --run is given).",
+)
+def emit_cmd(
+    run_id: str | None,
+    snapshot_path: str | None,
+    fmt: str,
+    out_path: str | None,
+    workdir: str,
+) -> None:
+    """Emit an AI-BOM derived from an existing run snapshot."""
+    from bernstein.core.compliance.ai_bom import (
+        BOMError,
+        encode_bom,
+        generate_bom,
+    )
+
+    if run_id and snapshot_path:
+        click.echo("error: --run and --snapshot are mutually exclusive", err=True)
+        raise SystemExit(2)
+    if not run_id and not snapshot_path:
+        click.echo("error: one of --run or --snapshot is required", err=True)
+        raise SystemExit(2)
+
+    if run_id:
+        snap_path = Path(workdir).resolve() / ".sdd" / "runs" / run_id / "bom_snapshot.json"
+        if not snap_path.exists():
+            click.echo(f"error: snapshot not found at {snap_path}", err=True)
+            raise SystemExit(1)
+    else:
+        assert snapshot_path is not None
+        snap_path = Path(snapshot_path)
+
+    try:
+        snapshot_raw: Any = json.loads(snap_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        click.echo(f"error: failed to load snapshot: {exc}", err=True)
+        raise SystemExit(1) from None
+
+    if not isinstance(snapshot_raw, dict):
+        click.echo("error: snapshot must decode to a JSON object", err=True)
+        raise SystemExit(1)
+
+    snapshot: dict[str, Any] = cast("dict[str, Any]", snapshot_raw)
+
+    try:
+        bom = generate_bom(snapshot)
+        payload = encode_bom(bom, fmt=fmt)
+    except BOMError as exc:
+        click.echo(f"error: {exc}", err=True)
+        raise SystemExit(1) from None
+
+    if out_path:
+        Path(out_path).write_bytes(payload)
+        click.echo(f"wrote {len(payload)} bytes to {out_path}")
+        return
+
+    sys.stdout.buffer.write(payload)
+    sys.stdout.buffer.write(b"\n")
+
+
+@bom_group.command("verify")
+@click.argument(
+    "bom_path",
+    type=click.Path(dir_okay=False, exists=True, resolve_path=True),
+)
+@click.option(
+    "--quiet",
+    is_flag=True,
+    default=False,
+    help="Only emit exit code; suppress the verification report.",
+)
+def verify_cmd(bom_path: str, quiet: bool) -> None:
+    """Verify a previously emitted AI-BOM."""
+    from bernstein.core.compliance.ai_bom import verify_bom
+
+    raw = Path(bom_path).read_bytes()
+    report = verify_bom(raw)
+
+    if quiet:
+        raise SystemExit(0 if report.ok else 1)
+
+    if report.ok:
+        click.echo(f"PASS: checked {report.checked_count} element(s)")
+    else:
+        click.echo(f"FAIL: {len(report.errors)} error(s); checked {report.checked_count} element(s)")
+        for err in report.errors:
+            click.echo(f"  - {err}")
+    raise SystemExit(0 if report.ok else 1)
+
+
+# Optional helper for tests / other callers: serialise a snapshot dict into
+# the BOM emit pipeline without going through Click's invocation machinery.
+def emit_bom_from_snapshot(snapshot: dict[str, Any], fmt: str = "json") -> bytes:
+    """Encode ``snapshot`` directly. Thin wrapper for non-CLI callers."""
+    from bernstein.core.compliance.ai_bom import encode_bom, generate_bom
+
+    return encode_bom(generate_bom(snapshot), fmt=fmt)
+
+
+__all__ = ["bom_group", "emit_bom_from_snapshot"]

bernstein-2.2.0/src/bernstein/cli/commands/consensus_cmd.py

@@ -0,0 +1,145 @@
+"""CLI command group: ``bernstein consensus`` -- cross-cycle relay inspection.
+
+Subcommands:
+
+* ``show <cycle>``    -- pretty-print one cycle relay document.
+* ``export <cycle>``  -- emit raw JSON, or markdown via ``--format md``.
+* ``next``            -- print only the ``next_action`` of the head relay.
+* ``list``            -- list every cycle id known to the chain.
+* ``verify``          -- verify the HMAC chain on disk.
+
+The relay store lives at ``.sdd/runtime/consensus/`` by default; override
+with ``BERNSTEIN_ORCHESTRATION_RELAY_PATH`` or the global ``--path``
+option.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import click
+
+from bernstein.core.orchestration.consensus_relay import (
+    RelayChainError,
+    RelayNotFoundError,
+    RelayStore,
+)
+
+
+def _store(path: str | None) -> RelayStore:
+    return RelayStore(Path(path) if path else None)
+
+
+@click.group("consensus")
+@click.option(
+    "--path",
+    "path_str",
+    default=None,
+    help="Override the relay directory (defaults to .sdd/runtime/consensus).",
+)
+@click.pass_context
+def consensus_group(ctx: click.Context, path_str: str | None) -> None:
+    """Inspect the cross-cycle consensus relay.
+
+    \b
+    Examples:
+      bernstein consensus list
+      bernstein consensus show cycle-42
+      bernstein consensus next
+      bernstein consensus export cycle-42 --format md
+      bernstein consensus verify
+    """
+    ctx.ensure_object(dict)
+    ctx.obj["path"] = path_str
+
+
+@consensus_group.command("list")
+@click.pass_context
+def consensus_list(ctx: click.Context) -> None:
+    """Print every cycle id, oldest first."""
+    cycles = _store(ctx.obj.get("path")).cycles()
+    if not cycles:
+        click.echo("no relay entries")
+        return
+    for c in cycles:
+        click.echo(c)
+
+
+@consensus_group.command("show")
+@click.argument("cycle_id", required=False, default=None)
+@click.pass_context
+def consensus_show(ctx: click.Context, cycle_id: str | None) -> None:
+    """Pretty-print a relay document. Defaults to the current head."""
+    store = _store(ctx.obj.get("path"))
+    try:
+        markdown = store.export_markdown(cycle_id)
+    except RelayNotFoundError as exc:
+        raise click.ClickException(str(exc)) from exc
+    click.echo(markdown)
+
+
+@consensus_group.command("export")
+@click.argument("cycle_id", required=False, default=None)
+@click.option(
+    "--format",
+    "fmt",
+    type=click.Choice(["json", "md"]),
+    default="json",
+    show_default=True,
+    help="Output format.",
+)
+@click.pass_context
+def consensus_export(ctx: click.Context, cycle_id: str | None, fmt: str) -> None:
+    """Export a single cycle relay as JSON or markdown.
+
+    With ``--format json`` the output is a single JSON object. With
+    ``--format md`` the output is the same compact markdown produced by
+    ``show``.
+    """
+    store = _store(ctx.obj.get("path"))
+    try:
+        if cycle_id is None:
+            doc = store.head()
+            if doc is None:
+                raise click.ClickException("no relay entries")
+        else:
+            doc = store.read(cycle_id)
+    except RelayNotFoundError as exc:
+        raise click.ClickException(str(exc)) from exc
+    if fmt == "md":
+        click.echo(store.export_markdown(doc.cycle_id))
+    else:
+        click.echo(json.dumps(doc.to_dict(), indent=2, sort_keys=True))
+
+
+@consensus_group.command("next")
+@click.pass_context
+def consensus_next(ctx: click.Context) -> None:
+    """Print the head relay's ``next_action`` -- the single follow-up to do.
+
+    Used by ``bernstein run`` cold-start path. Exits with code 1 when no
+    relay exists yet so shell scripts can branch.
+    """
+    head = _store(ctx.obj.get("path")).head()
+    if head is None:
+        raise click.ClickException("no relay entries")
+    if not head.next_action:
+        click.echo("")
+        return
+    click.echo(head.next_action)
+
+
+@consensus_group.command("verify")
+@click.pass_context
+def consensus_verify(ctx: click.Context) -> None:
+    """Verify the HMAC chain on disk.
+
+    Exits with code 0 on a clean chain, 1 with an explanation otherwise.
+    """
+    store = _store(ctx.obj.get("path"))
+    try:
+        store.verify()
+    except RelayChainError as exc:
+        raise click.ClickException(f"chain invalid: {exc}") from exc
+    click.echo("ok")

bernstein-2.2.0/src/bernstein/cli/commands/knowledge_cmd.py

@@ -0,0 +1,255 @@
+"""CLI surface for the diary + synthesis knowledge layer.
+
+Subcommands:
+
+* ``bernstein knowledge diary list`` -- list diaries in the active SDD tree.
+* ``bernstein knowledge diary show <task>`` -- pretty-print one entry.
+* ``bernstein knowledge synthesize --since <duration>`` -- run the
+  synthesis pass and write a markdown report. The ``--apply`` flag flips
+  the HITL gate and writes the approved marker.
+
+The module is intentionally thin: business logic lives in
+:mod:`bernstein.core.knowledge.diary` and
+:mod:`bernstein.core.knowledge.synthesizer`. The CLI only owns argument
+parsing, path resolution, and Rich output formatting.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import click
+
+from bernstein.core.knowledge.diary import (
+    DiaryError,
+    load_diaries,
+    load_diary,
+)
+from bernstein.core.knowledge.synthesizer import (
+    DEFAULT_JACCARD_THRESHOLD,
+    DEFAULT_MIN_CLUSTER_SIZE,
+    SynthesizerError,
+    approve,
+    parse_duration,
+    synthesize,
+    write_report,
+)
+
+if TYPE_CHECKING:
+    from bernstein.core.knowledge.diary import DiaryEntry
+
+
+def _resolve_sdd_dir(explicit: str | None) -> Path:
+    """Return the ``.sdd`` directory to operate on.
+
+    Resolution order:
+      1. Explicit ``--sdd-dir`` flag value.
+      2. ``$BERNSTEIN_SDD_DIR`` env var.
+      3. ``./.sdd`` under the current working directory.
+    """
+    if explicit:
+        return Path(explicit).resolve()
+    import os
+
+    env = os.environ.get("BERNSTEIN_SDD_DIR")
+    if env:
+        return Path(env).resolve()
+    return (Path.cwd() / ".sdd").resolve()
+
+
+@click.group("knowledge")
+def knowledge_group() -> None:
+    """Diary + synthesis knowledge layer.
+
+    \b
+    Examples:
+      bernstein knowledge diary list
+      bernstein knowledge diary show task-42
+      bernstein knowledge synthesize --since 14d
+      bernstein knowledge synthesize --since 7d --apply
+    """
+
+
+@knowledge_group.group("diary")
+def diary_group() -> None:
+    """Inspect per-task diary entries."""
+
+
+@diary_group.command("list")
+@click.option(
+    "--sdd-dir",
+    default=None,
+    help="Override the SDD root directory.",
+)
+@click.option(
+    "--json",
+    "as_json",
+    is_flag=True,
+    default=False,
+    help="Emit machine-readable JSON instead of a table.",
+)
+def diary_list_cmd(sdd_dir: str | None, as_json: bool) -> None:
+    """List every diary entry in the active SDD tree."""
+    target = _resolve_sdd_dir(sdd_dir)
+    entries = load_diaries(target)
+    if as_json:
+        click.echo(json.dumps([e.to_dict() for e in entries], indent=2, sort_keys=True))
+        return
+    if not entries:
+        click.echo(f"No diary entries under {target / 'runtime' / 'diaries'}.")
+        return
+    click.echo(f"{'task_id':<32} {'created_at':<26} {'tags':<40}")
+    click.echo("-" * 100)
+    for entry in entries:
+        tags = ", ".join(entry.tags[:6])
+        if len(entry.tags) > 6:
+            tags += ", ..."
+        click.echo(f"{entry.task_id:<32} {entry.created_at:<26} {tags:<40}")
+
+
+@diary_group.command("show")
+@click.argument("task_id")
+@click.option(
+    "--sdd-dir",
+    default=None,
+    help="Override the SDD root directory.",
+)
+@click.option(
+    "--json",
+    "as_json",
+    is_flag=True,
+    default=False,
+    help="Emit machine-readable JSON instead of formatted text.",
+)
+def diary_show_cmd(task_id: str, sdd_dir: str | None, as_json: bool) -> None:
+    """Show the diary entry for ``task_id``."""
+    target = _resolve_sdd_dir(sdd_dir)
+    diary_path = target / "runtime" / "diaries" / f"{task_id}.json"
+    if not diary_path.exists():
+        click.echo(f"No diary entry for task {task_id!r} at {diary_path}.", err=True)
+        sys.exit(1)
+    try:
+        entry = load_diary(diary_path)
+    except DiaryError as exc:
+        click.echo(f"Failed to load diary {diary_path}: {exc}", err=True)
+        sys.exit(1)
+    if as_json:
+        click.echo(json.dumps(entry.to_dict(), indent=2, sort_keys=True))
+        return
+    _render_entry(entry)
+
+
+def _render_entry(entry: DiaryEntry) -> None:
+    """Pretty-print a single diary entry to stdout."""
+    click.echo(f"Diary entry: {entry.task_id}")
+    click.echo(f"  created_at:     {entry.created_at}")
+    click.echo(f"  schema_version: {entry.schema_version}")
+    click.echo(f"  redaction_hash: {entry.redaction_hash}")
+    click.echo(f"  tags:           {', '.join(entry.tags) if entry.tags else '(none)'}")
+    click.echo("")
+    _render_section("Tried", entry.tried)
+    _render_section("Worked", entry.worked)
+    _render_section("Failed", entry.failed)
+    click.echo("Rationale:")
+    click.echo(f"  {entry.rationale or '(none)'}")
+
+
+def _render_section(name: str, bullets: tuple[str, ...]) -> None:
+    """Print a labelled bullet section."""
+    click.echo(f"{name}:")
+    if not bullets:
+        click.echo("  (none)")
+    else:
+        for bullet in bullets:
+            click.echo(f"  - {bullet}")
+    click.echo("")
+
+
+@knowledge_group.command("synthesize")
+@click.option(
+    "--since",
+    default="14d",
+    show_default=True,
+    help="Lookback window. Accepts NNd, NNh, NNm, NNs, or a bare integer (days).",
+)
+@click.option(
+    "--threshold",
+    type=float,
+    default=DEFAULT_JACCARD_THRESHOLD,
+    show_default=True,
+    help="Tag-overlap Jaccard threshold for clustering (0..1).",
+)
+@click.option(
+    "--min-cluster-size",
+    type=int,
+    default=DEFAULT_MIN_CLUSTER_SIZE,
+    show_default=True,
+    help="Drop clusters smaller than this size.",
+)
+@click.option(
+    "--apply",
+    "apply_flag",
+    is_flag=True,
+    default=False,
+    help="Flip the HITL gate: mark the report as approved and persist it.",
+)
+@click.option(
+    "--sdd-dir",
+    default=None,
+    help="Override the SDD root directory.",
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    default=False,
+    help="Print the report to stdout without writing to disk.",
+)
+def synthesize_cmd(
+    since: str,
+    threshold: float,
+    min_cluster_size: int,
+    apply_flag: bool,
+    sdd_dir: str | None,
+    dry_run: bool,
+) -> None:
+    """Aggregate recent diaries into themes and write a markdown report.
+
+    Without ``--apply`` the report lands on disk with ``approved: false``
+    in its frontmatter; downstream consumers MUST refuse to mutate role
+    prompts based on an unapproved report.
+    """
+    target = _resolve_sdd_dir(sdd_dir)
+    try:
+        delta = parse_duration(since)
+    except SynthesizerError as exc:
+        click.echo(f"Invalid --since value: {exc}", err=True)
+        sys.exit(2)
+    window_days = max(1, delta.days or 1)
+    entries = load_diaries(target)
+    try:
+        report = synthesize(
+            entries,
+            window_days=window_days,
+            threshold=threshold,
+            min_cluster_size=min_cluster_size,
+        )
+    except SynthesizerError as exc:
+        click.echo(f"Synthesis failed: {exc}", err=True)
+        sys.exit(1)
+    if apply_flag:
+        report = approve(report)
+    if dry_run:
+        from bernstein.core.knowledge.synthesizer import render_report
+
+        click.echo(render_report(report))
+        return
+    path = write_report(report, target)
+    click.echo(f"Wrote synthesis report: {path}")
+    click.echo(f"  themes:   {report.theme_count}")
+    click.echo(f"  approved: {report.approved}")
+
+
+__all__ = ["knowledge_group"]

{bernstein-2.1.0 → bernstein-2.2.0}/src/bernstein/cli/main.py

@@ -56,11 +56,14 @@ from bernstein.cli.checkpoint_cmd import checkpoint_cmd
 from bernstein.cli.ci_cmd import ci_group
 from bernstein.cli.cloud_cmd import cloud_group
 from bernstein.cli.commands.best_of_n_rank_cmd import best_of_n_group
+from bernstein.cli.commands.bom_cmd import bom_group
 from bernstein.cli.commands.citation_cmd import quality_group as citation_quality_group
+from bernstein.cli.commands.consensus_cmd import consensus_group
 from bernstein.cli.commands.criterion_profile_cmd import criterion_profile_group
 from bernstein.cli.commands.decisions_cmd import decisions_group
 from bernstein.cli.commands.export_cmd import export_cmd
 from bernstein.cli.commands.fleet_cmd import fleet_group
+from bernstein.cli.commands.knowledge_cmd import knowledge_group
 from bernstein.cli.commands.resume_cmd import resume_cmd
 from bernstein.cli.commands.role_adapter_policy_cmd import security_group as _role_adapter_security_group
 from bernstein.cli.commands.skills_cmd import skills_group
@@ -811,6 +814,7 @@ cli.add_command(plan, "tasks")
 cli.add_command(backlog_group, "backlog")
 cli.add_command(logs_group, "logs")
 cli.add_command(decisions_group, "decisions")
+cli.add_command(consensus_group, "consensus")
 cli.add_command(list_tasks, "list-tasks")
 
 # From workspace_cmd module - groups and commands
@@ -894,6 +898,7 @@ cli.add_command(checkpoint_cmd, "checkpoint")
 cli.add_command(resume_cmd, "resume")
 cli.add_command(wrap_up, "wrap-up")
 cli.add_command(audit_group, "audit")
+cli.add_command(bom_group, "bom")
 cli.add_command(compliance_group, "compliance")
 cli.add_command(verify_cmd, "verify")
 cli.add_command(chaos_group, "chaos")
@@ -910,6 +915,7 @@ cli.add_command(slo_cmd, "slo")
 cli.add_command(man_pages_cmd, "man-pages")
 cli.add_command(workflow_group, "workflow")
 cli.add_command(recipes_group, "recipes")
+cli.add_command(knowledge_group, "knowledge")
 cli.add_command(quickstart_cmd, "quickstart")
 cli.add_command(scaffold_cmd, "scaffold")
 cli.add_command(watch_cmd, "watch")