bernstein 0.1.0__py3-none-any.whl

bernstein/__init__.py

@@ -0,0 +1,32 @@
+"""Bernstein — Multi-agent orchestration for CLI coding agents."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+__version__ = "0.1.0"
+
+_PACKAGE_DIR = Path(__file__).resolve().parent
+
+# Bundled default templates — present inside the wheel after pip install.
+# In dev/editable mode, fall back to <repo>/templates/ at the project root.
+_bundled_templates_dir = _PACKAGE_DIR / "_default_templates"
+if not _bundled_templates_dir.is_dir():
+    # Dev mode: src/bernstein/../../templates → <repo>/templates
+    _bundled_templates_dir = _PACKAGE_DIR.parent.parent / "templates"
+
+# Public access via uppercase constant
+_BUNDLED_TEMPLATES_DIR = _bundled_templates_dir
+
+
+def get_templates_dir(workdir: Path) -> Path:
+    """Return the templates directory for a project, with bundled fallback.
+
+    Checks ``workdir / "templates"`` first; falls back to the package's
+    bundled defaults so that ``bernstein`` works right after ``pip install``
+    without requiring ``bernstein init`` first.
+    """
+    local = workdir / "templates"
+    if local.is_dir():
+        return local
+    return _BUNDLED_TEMPLATES_DIR

bernstein/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as ``python -m bernstein``."""
+
+from bernstein.cli.main import cli
+
+cli()

bernstein/_default_templates/bernstein.yaml

@@ -0,0 +1,80 @@
+## bernstein.yaml — project seed file
+## Copy to your project root and edit before running `bernstein run`.
+
+# Required: high-level objective for this run.
+goal: >
+  Describe your project goal here.
+
+# CLI agent backend.  One of: claude, codex, gemini, qwen.
+cli: claude
+
+# Maximum number of agents running concurrently.
+max_agents: 4
+
+# Optional model override (e.g. opus, sonnet, gpt-4.1).
+# model: opus
+
+# Role team.  "auto" lets the manager choose; or list explicit roles.
+# team: auto
+# team:
+#   - backend
+#   - qa
+
+# Spending cap.  Accepts "$20", 20, or 20.0.
+# budget: "$20"
+
+# Constraints passed verbatim to every agent.
+# constraints:
+#   - "Python 3.12+ only"
+#   - "No external dependencies without approval"
+
+# Extra files appended to the manager's context.
+# context_files:
+#   - docs/DESIGN.md
+#   - CLAUDE.md
+
+# ---------------------------------------------------------------------------
+# Agent catalogs
+# ---------------------------------------------------------------------------
+# Bernstein can load agent role definitions from external catalogs.
+# Each entry specifies a source and how to map its fields to Bernstein's
+# schema.  Higher priority values are checked first.
+#
+# Default (no catalogs section): Agency remote catalog only, priority 100.
+catalogs:
+  # Agency catalog — pulls role definitions from a GitHub repo.
+  - name: agency
+    type: agency
+    enabled: true
+    source: https://github.com/msitarzewski/agency-agents
+    priority: 100
+
+  # Generic local catalog — YAML files with a custom field mapping.
+  # - name: internal-agents
+  #   type: generic
+  #   enabled: true
+  #   path: ./custom-agents/
+  #   format: yaml
+  #   glob: "**/*.yaml"
+  #   field_map:
+  #     id: agent_id
+  #     name: display_name
+  #     role: category
+  #     system_prompt: prompt
+  #   priority: 50
+
+# ---------------------------------------------------------------------------
+# MCP servers (passed to every spawned agent)
+# ---------------------------------------------------------------------------
+# mcp_servers:
+#   filesystem:
+#     command: npx
+#     args: ["-y", "@modelcontextprotocol/server-filesystem", "."]
+
+# ---------------------------------------------------------------------------
+# Webhook notifications
+# ---------------------------------------------------------------------------
+# notify:
+#   webhook: https://hooks.example.com/bernstein
+#   on_complete: true
+#   on_failure: true

bernstein/_default_templates/prompts/judge.md

@@ -0,0 +1,39 @@
+# LLM Judge — Task Completion Verification
+
+You are a strict but fair judge evaluating whether a coding task was completed correctly.
+
+## Task
+
+**Title:** {{TASK_TITLE}}
+**Description:**
+{{TASK_DESCRIPTION}}
+
+## Evaluation Criteria
+
+{{CRITERIA}}
+
+## Git Diff (changes made)
+
+```diff
+{{GIT_DIFF}}
+```
+
+## Instructions
+
+Evaluate whether the changes satisfy the task description and criteria above.
+
+Consider:
+1. **Correctness** — Do the changes implement what was requested?
+2. **Completeness** — Are all aspects of the task addressed?
+3. **Quality** — Is the code well-structured and following conventions?
+
+Respond with ONLY a JSON object (no markdown fences, no text before or after):
+
+{"verdict": "accept", "confidence": 0.95, "feedback": "All criteria met."}
+
+Rules:
+- `verdict`: "accept" if the task is substantially complete and correct, "retry" if there are clear gaps or errors.
+- `confidence`: float from 0.0 to 1.0 reflecting certainty in your verdict.
+- `feedback`: Specific actionable explanation. If "retry", describe exactly what needs fixing.
+
+Output ONLY the JSON object.

bernstein/_default_templates/prompts/plan.md

@@ -0,0 +1,63 @@
+# Task Planning
+
+You are the Manager of a multi-agent coding team. Your job is to decompose the goal into specific, actionable tasks that specialist agents can execute independently.
+
+## Goal
+
+{{GOAL}}
+
+## Project context
+
+{{CONTEXT}}
+
+## Available roles
+
+{{AVAILABLE_ROLES}}
+
+## Existing tasks
+
+{{EXISTING_TASKS}}
+
+## Instructions
+
+Break the goal into tasks. Each task should be completable by a single agent in 30-120 minutes.
+
+Rules:
+1. Never assign two tasks to the same files — prevent merge conflicts.
+2. Include test-writing in implementation tasks or as separate QA tasks.
+3. Order tasks by dependency — foundational work first.
+4. Use the most appropriate role for each task.
+5. Keep tasks focused: one concern per task.
+6. If existing tasks already cover part of the goal, do not duplicate them.
+7. Every task must have at least one completion signal so the janitor can verify it.
+
+Output a JSON array of tasks. Each task object must have exactly these fields:
+
+```json
+[
+  {
+    "title": "Short actionable title",
+    "description": "Detailed description including acceptance criteria",
+    "role": "one of the available roles",
+    "priority": 2,
+    "scope": "small | medium | large",
+    "complexity": "low | medium | high",
+    "estimated_minutes": 60,
+    "depends_on": ["title of dependency task, if any"],
+    "owned_files": ["src/path/to/file.py"],
+    "completion_signals": [
+      {"type": "path_exists", "value": "src/path/to/file.py"},
+      {"type": "test_passes", "value": "pytest tests/test_file.py -x"}
+    ]
+  }
+]
+```
+
+Completion signal types:
+- `path_exists` — a file or directory must exist
+- `glob_exists` — at least one file matching a glob must exist
+- `test_passes` — a shell command must exit 0
+- `file_contains` — a file must contain a given string
+- `llm_review` — requires LLM review (use sparingly)
+
+Output ONLY the JSON array. No markdown fences, no explanation before or after.

bernstein/_default_templates/prompts/review.md

@@ -0,0 +1,45 @@
+# Task Review
+
+You are the Manager reviewing completed work from a specialist agent.
+
+## Task
+
+**Title:** {{TASK_TITLE}}
+**Role:** {{TASK_ROLE}}
+**Description:**
+{{TASK_DESCRIPTION}}
+
+## Completion signals
+
+{{COMPLETION_SIGNALS}}
+
+## Agent's result summary
+
+{{RESULT_SUMMARY}}
+
+## Project context
+
+{{CONTEXT}}
+
+## Instructions
+
+Review the completed work and decide:
+
+1. **approve** — the work meets acceptance criteria and is ready to merge.
+2. **request_changes** — the work is on the right track but needs specific fixes.
+3. **reject** — the work is fundamentally wrong and should be redone from scratch.
+
+Output a JSON object with exactly these fields:
+
+```json
+{
+  "verdict": "approve | request_changes | reject",
+  "reasoning": "Brief explanation of your decision",
+  "feedback": "Specific actionable feedback for the agent (empty string if approved)",
+  "follow_up_tasks": []
+}
+```
+
+For `follow_up_tasks`, use the same task format as planning (title, description, role, etc.). Only include follow-up tasks if the review reveals additional work needed beyond the original scope.
+
+Output ONLY the JSON object. No markdown fences, no explanation before or after.

bernstein/adapters/__init__.py

@@ -0,0 +1 @@
+"""Adapters for different CLI agents (Claude Code, Codex, Gemini, etc.)."""

bernstein/adapters/base.py

@@ -0,0 +1,112 @@
+"""Base adapter for CLI coding agents."""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import signal
+import sys
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from bernstein.core.models import ApiTierInfo, ModelConfig
+
+
+@dataclass
+class SpawnResult:
+    """Result of spawning an agent process."""
+
+    pid: int
+    log_path: Path
+    proc: object | None = None  # subprocess.Popen, kept for poll()-based alive check
+
+
+def build_worker_cmd(
+    cmd: list[str],
+    *,
+    role: str,
+    session_id: str,
+    pid_dir: Path,
+    model: str = "",
+) -> list[str]:
+    """Wrap a CLI command with bernstein-worker for process visibility.
+
+    The worker sets the process title to "bernstein: <role> [<session>]"
+    and writes a PID metadata file for ``bernstein ps``.
+
+    Args:
+        cmd: The original CLI command to wrap.
+        role: Agent role (qa, backend, etc.).
+        session_id: Unique session identifier.
+        pid_dir: Directory for PID metadata JSON files.
+        model: Model name for metadata display.
+
+    Returns:
+        Wrapped command list.
+    """
+    return [
+        sys.executable,
+        "-m",
+        "bernstein.core.worker",
+        "--role",
+        role,
+        "--session",
+        session_id,
+        "--pid-dir",
+        str(pid_dir),
+        "--model",
+        model,
+        "--",
+        *cmd,
+    ]
+
+
+class CLIAdapter(ABC):
+    """Interface for launching and monitoring CLI coding agents.
+
+    Implement this for each supported CLI (Claude Code, Codex, Gemini, etc.).
+    """
+
+    @abstractmethod
+    def spawn(
+        self,
+        *,
+        prompt: str,
+        workdir: Path,
+        model_config: ModelConfig,
+        session_id: str,
+        mcp_config: dict[str, Any] | None = None,
+    ) -> SpawnResult:
+        """Launch an agent process with the given prompt."""
+        ...
+
+    def is_alive(self, pid: int) -> bool:
+        """Check if the agent process is still running."""
+        try:
+            os.kill(pid, 0)
+            return True
+        except OSError:
+            return False
+
+    def kill(self, pid: int) -> None:
+        """Terminate the agent process."""
+        with contextlib.suppress(OSError):
+            os.killpg(os.getpgid(pid), signal.SIGTERM)
+
+    @abstractmethod
+    def name(self) -> str:
+        """Human-readable name of this CLI adapter."""
+        ...
+
+    def detect_tier(self) -> ApiTierInfo | None:
+        """Detect the current API tier and remaining quota.
+
+        Returns:
+            ApiTierInfo if tier detection is supported and successful, None otherwise.
+            Subclasses should override this to return provider-specific tier info.
+        """
+        return None

bernstein/adapters/ci/__init__.py

@@ -0,0 +1 @@
+"""CI system adapters for log parsing and failure extraction."""

bernstein/adapters/ci/github_actions.py

@@ -0,0 +1,276 @@
+"""GitHub Actions CI adapter.
+
+Parses GitHub Actions log format, extracts job/step names and failure
+output, and maps results to ``CIFailure`` objects.  Supports log download
+via the ``gh`` CLI and the GitHub REST API.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import subprocess
+from dataclasses import dataclass, field
+
+from bernstein.core.ci_fix import CIFailure, parse_failures
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# GitHub Actions log structure helpers
+# ---------------------------------------------------------------------------
+
+# Matches the timestamp prefix on every GHA log line.
+# Example: 2024-01-15T10:30:00.0000000Z ##[group]Run ruff check src/
+_TS_PREFIX_RE = re.compile(r"^\d{4}-\d{2}-\d{2}T[\d:.]+Z\s*", re.MULTILINE)
+
+# Matches ##[group]<name> / ##[endgroup] blocks.
+_GROUP_RE = re.compile(
+    r"##\[group\](.+?)$\n(.*?)##\[endgroup\]",
+    re.MULTILINE | re.DOTALL,
+)
+
+# Matches ##[error] annotations.
+_ERROR_RE = re.compile(r"##\[error\](.+?)$", re.MULTILINE)
+
+
+@dataclass
+class GHAStep:
+    """A parsed GitHub Actions step extracted from the log.
+
+    Attributes:
+        name: Step name taken from the ``##[group]`` marker.
+        body: Body text between group/endgroup markers (stripped of timestamps).
+        errors: Any ``##[error]`` annotations found in the body.
+    """
+
+    name: str
+    body: str
+    errors: list[str] = field(default_factory=list[str])
+
+
+# ---------------------------------------------------------------------------
+# Parser
+# ---------------------------------------------------------------------------
+
+
+def _strip_timestamps(text: str) -> str:
+    """Remove the ISO-8601 timestamp prefix from every log line.
+
+    Args:
+        text: Raw GitHub Actions log text.
+
+    Returns:
+        Log text with timestamps removed.
+    """
+    return _TS_PREFIX_RE.sub("", text)
+
+
+def _extract_steps(raw_log: str) -> list[GHAStep]:
+    """Extract grouped steps from a GitHub Actions log.
+
+    Args:
+        raw_log: Full raw log (timestamps already stripped).
+
+    Returns:
+        List of ``GHAStep`` objects.
+    """
+    steps: list[GHAStep] = []
+    for m in _GROUP_RE.finditer(raw_log):
+        name = m.group(1).strip()
+        body = m.group(2).strip()
+        errors = _ERROR_RE.findall(body)
+        steps.append(GHAStep(name=name, body=body, errors=errors))
+    return steps
+
+
+def _extract_job_name(raw_log: str) -> str:
+    """Attempt to extract the job name from the log header.
+
+    GitHub Actions logs often start with a line like:
+        ``##[group]Run <job-name>``
+
+    Args:
+        raw_log: Raw (timestamp-stripped) log.
+
+    Returns:
+        Extracted job name, or ``"github_actions"`` as fallback.
+    """
+    m = re.search(r"##\[group\]Run\s+(.+?)$", raw_log, re.MULTILINE)
+    if m:
+        return m.group(1).strip()[:80]
+    return "github_actions"
+
+
+class GitHubActionsParser:
+    """CI log parser for GitHub Actions.
+
+    Parses the ``##[group]`` / ``##[endgroup]`` structure and ``##[error]``
+    annotations, then delegates to the core ``parse_failures`` function for
+    content-level classification.
+
+    Attributes:
+        name: Parser identifier (``"github_actions"``).
+    """
+
+    name: str = "github_actions"
+
+    def parse(self, raw_log: str) -> list[CIFailure]:
+        """Parse a GitHub Actions log into structured CI failures.
+
+        Strategy:
+        1. Strip timestamps so content matchers work on clean text.
+        2. Extract ``##[group]``/``##[endgroup]`` steps.
+        3. For each step that contains ``##[error]`` annotations, run the
+           core ``parse_failures`` on the step body.
+        4. If no steps are found (log may not use group markers), fall back
+           to parsing the whole log.
+
+        Args:
+            raw_log: Raw log output from a GitHub Actions run.
+
+        Returns:
+            List of ``CIFailure`` objects.
+        """
+        clean = _strip_timestamps(raw_log)
+        steps = _extract_steps(clean)
+
+        # If we found steps with errors, parse each one individually.
+        failing_steps = [s for s in steps if s.errors]
+        if failing_steps:
+            failures: list[CIFailure] = []
+            for step in failing_steps:
+                step_failures = parse_failures(step.body, job=step.name)
+                failures.extend(step_failures)
+            return failures
+
+        # Fallback: parse the entire log as a single block.
+        job = _extract_job_name(clean)
+        return parse_failures(clean, job=job)
+
+
+# ---------------------------------------------------------------------------
+# Log download
+# ---------------------------------------------------------------------------
+
+
+def download_github_actions_log(
+    run_url: str,
+    *,
+    timeout: int = 60,
+) -> str:
+    """Download the failed-step log from a GitHub Actions run.
+
+    Uses ``gh run view --log-failed`` which requires the ``gh`` CLI to be
+    installed and authenticated.
+
+    Args:
+        run_url: URL of the GitHub Actions run, e.g.
+            ``https://github.com/owner/repo/actions/runs/123456``.
+        timeout: Subprocess timeout in seconds.
+
+    Returns:
+        Raw log text from the failed steps.
+
+    Raises:
+        RuntimeError: If the ``gh`` command fails.
+    """
+    # Extract the run ID from the URL.
+    run_id = _extract_run_id(run_url)
+
+    result = subprocess.run(
+        ["gh", "run", "view", run_id, "--log-failed"],
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+    )
+    if result.returncode != 0:
+        msg = f"gh run view failed (exit {result.returncode}): {result.stderr.strip()[:200]}"
+        raise RuntimeError(msg)
+    return result.stdout
+
+
+def download_github_actions_log_api(
+    run_url: str,
+    *,
+    timeout: int = 60,
+) -> str:
+    """Download the failed-step log via ``gh api``.
+
+    This is an alternative to ``download_github_actions_log`` that uses the
+    GitHub REST API through ``gh api``, which can be more reliable in some
+    environments.
+
+    Args:
+        run_url: URL of the GitHub Actions run.
+        timeout: Subprocess timeout in seconds.
+
+    Returns:
+        Raw log text (JSON) from the API.
+
+    Raises:
+        RuntimeError: If the ``gh`` command fails.
+    """
+    run_id = _extract_run_id(run_url)
+
+    # First get the jobs for this run.
+    # Extract owner/repo from the URL.
+    m = re.match(r"https?://github\.com/([^/]+/[^/]+)/actions/runs/\d+", run_url)
+    if not m:
+        msg = f"Cannot parse owner/repo from URL: {run_url}"
+        raise ValueError(msg)
+    repo = m.group(1)
+
+    # Get failed jobs.
+    result = subprocess.run(
+        [
+            "gh",
+            "api",
+            f"repos/{repo}/actions/runs/{run_id}/jobs",
+            "--jq",
+            '.jobs[] | select(.conclusion == "failure") | .id',
+        ],
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+    )
+    if result.returncode != 0:
+        msg = f"gh api failed (exit {result.returncode}): {result.stderr.strip()[:200]}"
+        raise RuntimeError(msg)
+
+    job_ids = result.stdout.strip().splitlines()
+    if not job_ids:
+        return ""
+
+    # Download logs for each failed job.
+    logs: list[str] = []
+    for job_id in job_ids:
+        log_result = subprocess.run(
+            ["gh", "api", f"repos/{repo}/actions/jobs/{job_id}/logs"],
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+        if log_result.returncode == 0:
+            logs.append(log_result.stdout)
+
+    return "\n".join(logs)
+
+
+def _extract_run_id(run_url: str) -> str:
+    """Extract the numeric run ID from a GitHub Actions URL.
+
+    Args:
+        run_url: URL like ``https://github.com/owner/repo/actions/runs/123456``.
+
+    Returns:
+        The run ID as a string.
+
+    Raises:
+        ValueError: If the URL does not match the expected pattern.
+    """
+    m = re.search(r"/actions/runs/(\d+)", run_url)
+    if not m:
+        msg = f"Cannot extract run ID from URL: {run_url}"
+        raise ValueError(msg)
+    return m.group(1)