crprotocol 2.0.0__py3-none-any.whl

crp/cli/main.py

@@ -0,0 +1,329 @@
+# Copyright © 2025 Constantinos Vidiniotis. All rights reserved.
+# Licensed under Elastic License 2.0 — see LICENSE.md for details.
+"""CRP CLI entry point — ``crp init | dispatch | ingest | status | preview | serve``.
+
+UNIX-friendly: reads stdin, writes JSON to stdout, pipe-compatible.
+Requires the ``click`` package (``pip install crprotocol[cli]``).
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import uuid
+from typing import Any
+
+
+def _require_click():
+    """Import click with a friendly error if missing."""
+    try:
+        import click
+        return click
+    except ImportError as exc:
+        raise SystemExit(
+            "The CRP CLI requires 'click'.  Install with:  pip install crprotocol[cli]"
+        ) from exc
+
+
+# ── Session store (in-memory for CLI lifetime) ──────────────────────────
+
+_sessions: dict[str, dict] = {}
+
+
+def _get_session(session_id: str) -> dict:
+    """Retrieve a live session or exit with error."""
+    if session_id not in _sessions:
+        sys.stderr.write(f"Error: unknown session '{session_id}'\n")
+        raise SystemExit(1)
+    return _sessions[session_id]
+
+
+# ── Click application ───────────────────────────────────────────────────
+
+def cli() -> None:
+    """CRP CLI entry point — delegates to click group."""
+    # Fix Windows cp1252 encoding — ensure UTF-8 for Unicode output
+    if sys.platform == "win32":
+        import io
+        for stream_name in ("stdout", "stderr"):
+            stream = getattr(sys, stream_name)
+            if hasattr(stream, "buffer"):
+                wrapped = io.TextIOWrapper(
+                    stream.buffer, encoding="utf-8", errors="replace",
+                )
+                wrapped.reconfigure(line_buffering=True)
+                setattr(sys, stream_name, wrapped)
+
+    click = _require_click()
+
+    # Build the Click group lazily so the module can be imported
+    # without click being installed (for embedded library use).
+    @click.group(context_settings={"help_option_names": ["-h", "--help"]})
+    @click.version_option(package_name="crp")
+    def _cli():
+        """CRP — Context Relay Protocol CLI."""
+
+    # ── crp init ────────────────────────────────────────────────────
+
+    @_cli.command()
+    @click.option("--model", default="custom", help="Model name for diagnostics.")
+    @click.option("--context-window", default=128_000, type=int,
+                  help="Context window size in tokens.")
+    @click.option("--max-output", default=4096, type=int,
+                  help="Max output tokens per generation.")
+    @click.option("--timeout", default=86400, type=int,
+                  help="Session timeout in seconds.")
+    @click.option("--json", "as_json", is_flag=True, help="Output raw JSON.")
+    def init(model, context_window, max_output, timeout, as_json):
+        """Create a new CRP session and print the session ID."""
+        from crp.cli.startup import run_startup
+        from crp.providers.custom import CustomProvider
+
+        # Build a stub provider — real LLM endpoint comes via dispatch
+        provider = CustomProvider(
+            generate_fn=lambda msgs, **kw: ("", "stop"),
+            count_tokens_fn=lambda t: max(1, len(t) // 4),
+            context_size=context_window,
+            name=model,
+            max_output=max_output,
+        )
+
+        result, ctx = run_startup(
+            provider=provider,
+            config_overrides={"session_timeout": timeout},
+            skip_health=True,
+        )
+
+        session_id = str(uuid.uuid4())
+        _sessions[session_id] = {
+            "id": session_id,
+            "provider": provider,
+            "config": ctx.get("config"),
+            "emitter": ctx.get("emitter"),
+            "orchestrator": None,  # lazy
+        }
+
+        if as_json:
+            click.echo(json.dumps({
+                "session_id": session_id,
+                "model": model,
+                "context_window": context_window,
+                "startup_ok": result.ok,
+                "startup_ms": round(result.total_ms, 2),
+            }))
+        else:
+            click.echo(session_id)
+
+    # ── crp dispatch ────────────────────────────────────────────────
+
+    @_cli.command()
+    @click.option("--session", "session_id", default=None, help="Session ID (auto-creates if omitted).")
+    @click.option("--task", required=True, help="Task input text.")
+    @click.option("--system", default="You are a helpful assistant.",
+                  help="System prompt.")
+    @click.option("--json", "as_json", is_flag=True, help="Output JSON report.")
+    def dispatch(session_id, task, system, as_json):
+        """Dispatch a task to the LLM via CRP and print the output.
+
+        If --session is omitted a one-shot session is created automatically
+        so that ``crp dispatch --task "Hello"`` works without ``crp init``.
+        """
+        if session_id is None:
+            # Auto-init a one-shot session
+            from crp.cli.startup import run_startup
+            from crp.providers.custom import CustomProvider
+
+            provider = CustomProvider(
+                generate_fn=lambda msgs, **kw: ("", "stop"),
+                count_tokens_fn=lambda t: max(1, len(t) // 4),
+                context_size=128_000,
+            )
+            result, ctx = run_startup(
+                provider=provider, skip_health=True,
+            )
+            session_id = str(uuid.uuid4())
+            _sessions[session_id] = {
+                "id": session_id,
+                "provider": provider,
+                "config": ctx.get("config"),
+                "emitter": ctx.get("emitter"),
+                "orchestrator": None,
+            }
+        sess = _get_session(session_id)
+        orch = _ensure_orchestrator(sess)
+
+        output, report = orch.dispatch(system, task)
+
+        if as_json:
+            click.echo(json.dumps({
+                "session_id": report.session_id,
+                "window_id": report.window_id,
+                "output": output,
+                "facts_extracted": report.facts_extracted,
+            }))
+        else:
+            click.echo(output)
+
+    # ── crp ingest ──────────────────────────────────────────────────
+
+    @_cli.command()
+    @click.option("--session", "session_id", required=True, help="Session ID.")
+    @click.option("--label", default="stdin", help="Source label.")
+    @click.option("--json", "as_json", is_flag=True, help="Output JSON.")
+    @click.argument("file", default="-", type=click.File("r"))
+    def ingest(session_id, label, as_json, file):
+        """Ingest raw text (file or stdin) into the session."""
+        sess = _get_session(session_id)
+        orch = _ensure_orchestrator(sess)
+        text = file.read()
+        result = orch.ingest(text, source_label=label)
+
+        if as_json:
+            click.echo(json.dumps({
+                "facts_extracted": result.facts_extracted,
+                "source_label": result.source_label,
+                "fact_ids": result.fact_ids,
+            }))
+        else:
+            click.echo(f"Ingested {result.facts_extracted} facts from '{label}'")
+
+    # ── crp status ──────────────────────────────────────────────────
+
+    @_cli.command()
+    @click.option("--session", "session_id", required=True, help="Session ID.")
+    def status(session_id):
+        """Print session status as JSON."""
+        sess = _get_session(session_id)
+        orch = _ensure_orchestrator(sess)
+        st = orch.session_status()
+        click.echo(json.dumps({
+            "session_id": st.session_id,
+            "windows_completed": st.windows_completed,
+            "total_input_tokens": st.total_input_tokens,
+            "total_output_tokens": st.total_output_tokens,
+            "facts_in_warm_state": st.facts_in_warm_state,
+            "overhead_ratio": st.overhead_ratio,
+        }, indent=2))
+
+    # ── crp preview ─────────────────────────────────────────────────
+
+    @_cli.command()
+    @click.option("--session", "session_id", required=True, help="Session ID.")
+    @click.option("--task", required=True, help="Task input text.")
+    @click.option("--system", default="You are a helpful assistant.",
+                  help="System prompt.")
+    def preview(session_id, task, system):
+        """Preview envelope without dispatching — prints JSON."""
+        sess = _get_session(session_id)
+        orch = _ensure_orchestrator(sess)
+        ep = orch.preview_envelope(system, task)
+        click.echo(json.dumps({
+            "total_tokens": ep.total_tokens,
+            "envelope_tokens": ep.envelope_tokens,
+            "generation_reserve": ep.generation_reserve,
+            "facts_included": ep.facts_included,
+            "facts_available": ep.facts_available,
+            "saturation": round(ep.saturation, 4),
+        }, indent=2))
+
+    # ── crp serve (HTTP sidecar for inter-LLM context sharing) ────
+
+    @_cli.command()
+    @click.option("--port", default=9470, type=int, help="Port number.")
+    @click.option("--bind-all", is_flag=True, default=False,
+                  help="Bind to 0.0.0.0 instead of 127.0.0.1. Requires --auth-token unless --allow-unauthenticated is set.")
+    @click.option("--auth-token", default=None, help="Bearer token for authentication (strongly recommended).")
+    @click.option("--allow-unauthenticated", is_flag=True, default=False,
+                  help="Allow running without auth token (NOT recommended for --bind-all).")
+    @click.option("--max-sessions", default=64, type=int, help="Maximum concurrent sessions.")
+    @click.option("--rate-limit", default=120, type=int, help="Max requests per IP per rate window.")
+    def serve(port, bind_all, auth_token, allow_unauthenticated, max_sessions, rate_limit):
+        """Start the CRP HTTP sidecar for inter-LLM context sharing.
+
+        The sidecar is OPTIONAL — it is never started automatically.
+        It exposes CRP sessions over HTTP, enabling multiple applications
+        and LLMs to share extracted knowledge.
+
+        \b
+        SECURITY:
+          - Binds to 127.0.0.1 (loopback) by default
+          - --auth-token enables bearer-token authentication
+          - --bind-all requires --auth-token (or explicit --allow-unauthenticated)
+          - Per-IP rate limiting (default: 120 req/60s)
+          - Session ownership: only the token that created a session can access it
+          - 10 MB request body limit
+          - No HTTPS — deploy behind a TLS reverse proxy for production
+
+        \b
+        ENDPOINTS (all 6 dispatch variants + knowledge sharing):
+          POST /sessions                          Create session
+          POST /sessions/:id/dispatch             Basic dispatch
+          POST /sessions/:id/dispatch/tools       Tool-mediated dispatch
+          POST /sessions/:id/dispatch/reflexive   Reflexive dispatch
+          POST /sessions/:id/dispatch/progressive Progressive dispatch
+          POST /sessions/:id/dispatch/stream-augmented  Stream-augmented
+          POST /sessions/:id/dispatch/agentic     Agentic dispatch
+          POST /sessions/:id/ingest               Ingest text
+          GET  /sessions/:id/facts                Query facts
+          POST /sessions/:id/facts/share          SHARE facts between sessions
+          POST /sessions/:id/facts/feedback       Boost/penalize/reject facts
+          POST /sessions/:id/providers            Register fallback provider
+          POST /sessions/:id/estimate             Cost estimation
+          GET  /sessions/:id/status               Session status
+          GET  /sessions/:id/envelope             Envelope preview
+          POST /sessions/:id/close                Close session
+          GET  /sessions                          List sessions (owned only)
+          GET  /health                            Health check
+
+        The /facts/share endpoint is the core differentiator — it enables
+        two LLMs using CRP to share each other's extracted knowledge.
+        """
+        from crp.cli.sidecar import start_sidecar
+
+        host = "0.0.0.0" if bind_all else "127.0.0.1"
+
+        # Security gate: --bind-all requires auth unless explicitly waived
+        if bind_all and not auth_token and not allow_unauthenticated:
+            click.echo("ERROR: --bind-all requires --auth-token for security.", err=True)
+            click.echo("  Use --allow-unauthenticated to override (NOT recommended).", err=True)
+            raise SystemExit(1)
+
+        if bind_all and not auth_token:
+            click.echo("WARNING: Binding to 0.0.0.0 WITHOUT authentication!", err=True)
+            click.echo("  Any process on the network can access CRP sessions.", err=True)
+
+        click.echo(f"CRP sidecar starting on {host}:{port}")
+        click.echo(f"  Auth: {'Bearer token required' if auth_token else 'DISABLED'}")
+        click.echo(f"  Max sessions: {max_sessions}")
+        click.echo(f"  Rate limit: {rate_limit} req/60s per IP")
+        click.echo()
+        click.echo(f"  Dispatch variants: basic, tools, reflexive, progressive, stream-augmented, agentic")
+        click.echo(f"  POST /sessions/:id/facts/share  ← Inter-LLM context sharing")
+        click.echo(f"  POST /sessions/:id/facts/feedback  ← Fact confidence adjustment")
+        click.echo(f"  GET  /health")
+        click.echo()
+
+        server = start_sidecar(host=host, port=port, auth_token=auth_token,
+                               max_sessions=max_sessions, rate_limit=rate_limit)
+        try:
+            server.serve_forever()
+        except KeyboardInterrupt:
+            click.echo("\nShutting down sidecar...")
+            server.shutdown()
+
+    _cli(standalone_mode=True)
+
+
+# ── Helpers ─────────────────────────────────────────────────────────────
+
+def _ensure_orchestrator(sess: dict) -> Any:  # type: ignore[type-arg]
+    """Lazily build the orchestrator for this session."""
+    if sess["orchestrator"] is None:
+        from crp.core.orchestrator import CRPOrchestrator
+
+        orch = CRPOrchestrator(
+            provider=sess["provider"],
+            config=sess["config"],
+        )
+        sess["orchestrator"] = orch
+    return sess["orchestrator"]