flonat-research 0.1.0

package/packages/cli-council/src/cli_council/backends/base.py

@@ -0,0 +1,81 @@
+"""Abstract base for CLI backends."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import shutil
+from abc import ABC, abstractmethod
+from time import perf_counter
+
+from cli_council.config import STAGE_TIMEOUT
+
+logger = logging.getLogger(__name__)
+
+
+class CLIBackend(ABC):
+    """Base class for CLI tool backends."""
+
+    name: str = ""
+    command: str = ""
+
+    @abstractmethod
+    def build_args(self, prompt: str, *, model: str | None = None) -> list[str]:
+        """Build the full argument list for subprocess execution."""
+
+    def is_available(self) -> bool:
+        """Check if the CLI tool is installed and on PATH."""
+        return shutil.which(self.command) is not None
+
+    async def run(
+        self,
+        prompt: str,
+        *,
+        model: str | None = None,
+        timeout: int = STAGE_TIMEOUT,
+        cwd: str | None = None,
+    ) -> tuple[str, int]:
+        """Execute the CLI tool and return (output_text, elapsed_ms).
+
+        Raises RuntimeError if the command fails or times out.
+        """
+        args = self.build_args(prompt, model=model)
+        logger.info("Running %s: %s", self.name, " ".join(args[:4]) + "...")
+
+        # Clean environment: unset CLAUDECODE to allow nested claude calls
+        env = {k: v for k, v in os.environ.items() if k != "CLAUDECODE"}
+
+        t0 = perf_counter()
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                *args,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                cwd=cwd,
+                env=env,
+            )
+            stdout, stderr = await asyncio.wait_for(
+                proc.communicate(), timeout=timeout,
+            )
+        except asyncio.TimeoutError:
+            proc.kill()
+            elapsed = int((perf_counter() - t0) * 1000)
+            raise RuntimeError(
+                f"{self.name} timed out after {timeout}s"
+            ) from None
+
+        elapsed = int((perf_counter() - t0) * 1000)
+        output = stdout.decode("utf-8", errors="replace").strip()
+
+        if proc.returncode != 0:
+            err = stderr.decode("utf-8", errors="replace").strip()
+            logger.warning(
+                "%s exited with code %d: %s",
+                self.name, proc.returncode, err[:200],
+            )
+            # Some backends write useful output to stderr on non-zero exit
+            if not output and err:
+                output = err
+
+        return output, elapsed

package/packages/cli-council/src/cli_council/backends/claude.py

@@ -0,0 +1,25 @@
+"""Claude Code CLI backend."""
+
+from __future__ import annotations
+
+from cli_council.backends.base import CLIBackend
+from cli_council.config import BACKENDS
+
+
+class ClaudeBackend(CLIBackend):
+    """Wrapper for Anthropic's Claude Code CLI (claude -p)."""
+
+    name = "claude"
+    command = "claude"
+
+    def __init__(self, model: str | None = None) -> None:
+        spec = BACKENDS["claude"]
+        self.default_model = model or spec.default_model
+
+    def build_args(self, prompt: str, *, model: str | None = None) -> list[str]:
+        effective_model = model or self.default_model
+        return [
+            "claude",
+            "-p", prompt,
+            "--model", effective_model,
+        ]

package/packages/cli-council/src/cli_council/backends/codex.py

@@ -0,0 +1,27 @@
+"""Codex CLI backend."""
+
+from __future__ import annotations
+
+from cli_council.backends.base import CLIBackend
+from cli_council.config import BACKENDS
+
+
+class CodexBackend(CLIBackend):
+    """Wrapper for OpenAI's Codex CLI (codex exec)."""
+
+    name = "codex"
+    command = "codex"
+
+    def __init__(self, model: str | None = None) -> None:
+        spec = BACKENDS["codex"]
+        self.default_model = model or spec.default_model
+
+    def build_args(self, prompt: str, *, model: str | None = None) -> list[str]:
+        effective_model = model or self.default_model
+        args = ["codex", "exec"]
+        # Skip -m flag when using default — ChatGPT accounts don't support
+        # explicit model selection but use the best available (GPT-5).
+        if effective_model != "default":
+            args.extend(["-m", effective_model])
+        args.extend(["--full-auto", prompt])
+        return args

package/packages/cli-council/src/cli_council/backends/gemini.py

@@ -0,0 +1,26 @@
+"""Gemini CLI backend."""
+
+from __future__ import annotations
+
+from cli_council.backends.base import CLIBackend
+from cli_council.config import BACKENDS
+
+
+class GeminiBackend(CLIBackend):
+    """Wrapper for Google's Gemini CLI (gemini -p)."""
+
+    name = "gemini"
+    command = "gemini"
+
+    def __init__(self, model: str | None = None) -> None:
+        spec = BACKENDS["gemini"]
+        self.default_model = model or spec.default_model
+
+    def build_args(self, prompt: str, *, model: str | None = None) -> list[str]:
+        effective_model = model or self.default_model
+        return [
+            "gemini",
+            "-p", prompt,
+            "-m", effective_model,
+            "-o", "text",
+        ]

package/packages/cli-council/src/cli_council/checkpoint.py

@@ -0,0 +1,212 @@
+"""Checkpoint and file-based coordination for council runs.
+
+Inspired by:
+- Owlex (agentic-mcp-tools/owlex): session resumption across deliberation rounds
+- agents-council (MrLesk/agents-council): atomic file writes, cursor-based state
+
+Provides:
+- Atomic JSON writes (tmp + fsync + rename) for crash safety
+- Stage checkpointing: save after each stage, resume from last completed stage
+- Pending participant tracking
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import tempfile
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# Default checkpoint directory (gitignored in projects)
+DEFAULT_CHECKPOINT_DIR = ".council"
+
+
+@dataclass(frozen=True)
+class CheckpointMeta:
+    """Metadata for a checkpoint file."""
+
+    run_id: str
+    stage: int  # 1, 2, or 3
+    timestamp: str
+    backends: list[str]
+
+
+def _atomic_write_json(path: Path, data: dict) -> None:
+    """Write JSON atomically: tmp file -> fsync -> rename.
+
+    If the process crashes mid-write, the original file is preserved.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp_path = tempfile.mkstemp(
+        dir=str(path.parent), suffix=".tmp", prefix=".ckpt-",
+    )
+    try:
+        with os.fdopen(fd, "w") as f:
+            json.dump(data, f, indent=2, default=str)
+            f.flush()
+            os.fsync(f.fileno())
+        os.rename(tmp_path, str(path))
+    except BaseException:
+        # Clean up temp file on any failure
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+        raise
+
+
+def _read_json(path: Path) -> dict | None:
+    """Read a JSON checkpoint file, returning None if missing or corrupt."""
+    if not path.exists():
+        return None
+    try:
+        return json.loads(path.read_text())
+    except (json.JSONDecodeError, OSError) as exc:
+        logger.warning("Corrupt checkpoint %s: %s", path, exc)
+        return None
+
+
+def _make_run_id() -> str:
+    """Generate a timestamped run ID."""
+    return datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+
+
+@dataclass
+class CouncilCheckpointer:
+    """Manages checkpoint state for a council run.
+
+    Usage:
+        ckpt = CouncilCheckpointer(checkpoint_dir="/path/to/.council")
+        # Saves after each stage; can resume from last completed stage.
+    """
+
+    checkpoint_dir: Path
+    run_id: str = field(default_factory=_make_run_id)
+
+    def __post_init__(self) -> None:
+        self.checkpoint_dir = Path(self.checkpoint_dir)
+
+    # ---- Save ----
+
+    def save_stage1(self, assessments: list[dict], backends: list[str]) -> Path:
+        """Save Stage 1 assessments to checkpoint."""
+        path = self._stage_path(1)
+        data = {
+            "meta": {
+                "run_id": self.run_id,
+                "stage": 1,
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+                "backends": backends,
+            },
+            "assessments": assessments,
+        }
+        _atomic_write_json(path, data)
+        logger.info("Checkpoint saved: Stage 1 → %s", path)
+        return path
+
+    def save_stage2(
+        self,
+        peer_reviews: list[dict],
+        backends: list[str],
+        aggregate_rankings: list[dict] | None = None,
+    ) -> Path:
+        """Save Stage 2 peer reviews to checkpoint."""
+        path = self._stage_path(2)
+        data = {
+            "meta": {
+                "run_id": self.run_id,
+                "stage": 2,
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+                "backends": backends,
+            },
+            "peer_reviews": peer_reviews,
+            "aggregate_rankings": aggregate_rankings or [],
+        }
+        _atomic_write_json(path, data)
+        logger.info("Checkpoint saved: Stage 2 → %s", path)
+        return path
+
+    def save_stage3(self, synthesis: dict | str, chairman: str) -> Path:
+        """Save Stage 3 synthesis to checkpoint."""
+        path = self._stage_path(3)
+        data = {
+            "meta": {
+                "run_id": self.run_id,
+                "stage": 3,
+                "timestamp": datetime.now(timezone.utc).isoformat(),
+                "chairman": chairman,
+            },
+            "synthesis": synthesis,
+        }
+        _atomic_write_json(path, data)
+        logger.info("Checkpoint saved: Stage 3 → %s", path)
+        return path
+
+    # ---- Load / Resume ----
+
+    def last_completed_stage(self) -> int:
+        """Return the highest completed stage (0 if none)."""
+        for stage in (3, 2, 1):
+            if self._stage_path(stage).exists():
+                return stage
+        return 0
+
+    def load_stage1(self) -> list[dict] | None:
+        """Load Stage 1 assessments from checkpoint."""
+        data = _read_json(self._stage_path(1))
+        if data is None:
+            return None
+        return data.get("assessments")
+
+    def load_stage2(self) -> tuple[list[dict], list[dict]] | None:
+        """Load Stage 2 peer reviews + aggregate rankings from checkpoint."""
+        data = _read_json(self._stage_path(2))
+        if data is None:
+            return None
+        return data.get("peer_reviews", []), data.get("aggregate_rankings", [])
+
+    def load_stage3(self) -> dict | str | None:
+        """Load Stage 3 synthesis from checkpoint."""
+        data = _read_json(self._stage_path(3))
+        if data is None:
+            return None
+        return data.get("synthesis")
+
+    # ---- Pending participants ----
+
+    def pending_participants(
+        self, all_backends: list[str], responded: list[str],
+    ) -> list[str]:
+        """Return backends that haven't responded yet."""
+        return [b for b in all_backends if b not in set(responded)]
+
+    # ---- Discovery ----
+
+    def find_latest_run(self) -> str | None:
+        """Find the most recent run_id in the checkpoint directory."""
+        if not self.checkpoint_dir.exists():
+            return None
+        # Look for stage-1 files (every run has one)
+        stage1_files = sorted(self.checkpoint_dir.glob("*-stage1.json"), reverse=True)
+        if not stage1_files:
+            return None
+        # Extract run_id from filename: {run_id}-stage1.json
+        return stage1_files[0].stem.replace("-stage1", "")
+
+    def clean(self) -> None:
+        """Remove all checkpoint files for this run."""
+        for stage in (1, 2, 3):
+            path = self._stage_path(stage)
+            if path.exists():
+                path.unlink()
+                logger.info("Removed checkpoint: %s", path)
+
+    # ---- Internal ----
+
+    def _stage_path(self, stage: int) -> Path:
+        return self.checkpoint_dir / f"{self.run_id}-stage{stage}.json"

package/packages/cli-council/src/cli_council/config.py

@@ -0,0 +1,51 @@
+"""Backend registry and defaults."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class BackendSpec:
+    """Specification for a CLI backend."""
+
+    name: str
+    command: str            # binary name
+    headless_flag: str      # flag for non-interactive mode
+    model_flag: str         # flag to select model (empty if not supported)
+    default_model: str      # default model name
+    output_flag: str        # flag for output format (empty if not needed)
+
+
+BACKENDS: dict[str, BackendSpec] = {
+    "gemini": BackendSpec(
+        name="gemini",
+        command="gemini",
+        headless_flag="-p",
+        model_flag="-m",
+        default_model="gemini-2.5-pro",
+        output_flag="-o text",
+    ),
+    "codex": BackendSpec(
+        name="codex",
+        command="codex",
+        headless_flag="exec",
+        model_flag="-m",
+        default_model="default",
+        output_flag="",
+    ),
+    "claude": BackendSpec(
+        name="claude",
+        command="claude",
+        headless_flag="-p",
+        model_flag="--model",
+        default_model="claude-sonnet-4-6",
+        output_flag="",
+    ),
+}
+
+DEFAULT_COUNCIL_BACKENDS: list[str] = ["gemini", "codex", "claude"]
+DEFAULT_CHAIRMAN: str = "claude"
+
+# Subprocess timeout in seconds per stage
+STAGE_TIMEOUT: int = 120