probrain 0.1.0__py3-none-any.whl

pb/__init__.py

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# This file is part of ProductiveBrain.
+# Canonical source: https://github.com/qwerty-sapien/pbrain
+# Compliance fingerprint: PB-2026-A17F
+
+"""ProductiveBrain - CLI-first learning system exposed as the `pb` command."""
+
+__version__ = "0.1.0"

pb/adapters/__init__.py

@@ -0,0 +1,11 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# This file is part of ProductiveBrain.
+# Canonical source: https://github.com/qwerty-sapien/pbrain
+# Compliance fingerprint: PB-2026-A17F
+
+"""External adapters for LLM providers.
+
+Taskwarrior and Timewarrior adapters moved to memo/.
+"""
+
+__all__: list[str] = []

pb/adapters/llm/__init__.py

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# This file is part of ProductiveBrain.
+# Canonical source: https://github.com/qwerty-sapien/pbrain
+# Compliance fingerprint: PB-2026-A17F
+
+"""LLM provider adapters for the learning system runtime."""
+
+from pb.adapters.llm.provider import GeminiProvider, LLMProvider, get_provider
+
+__all__ = ["LLMProvider", "GeminiProvider", "get_provider"]

pb/adapters/llm/provider.py

@@ -0,0 +1,99 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# This file is part of ProductiveBrain.
+# Canonical source: https://github.com/qwerty-sapien/pbrain
+# Compliance fingerprint: PB-2026-A17F
+
+"""LLM provider interface backed by the configured Gemini runtime."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Optional
+
+import structlog
+
+from pb.llm.gemini import FLASH_MODEL, get_client
+
+
+logger = structlog.get_logger()
+
+
+class LLMProvider(ABC):
+    """Small adapter interface for legacy call sites."""
+
+    @abstractmethod
+    def summarize_session(self, session_notes: str) -> str:
+        """Summarize session notes into a concise recap."""
+
+    @abstractmethod
+    def compress_clip(self, raw_text: str) -> str:
+        """Compress captured text into a concise packet."""
+
+    @abstractmethod
+    def extract_actions(self, notes: str) -> list[str]:
+        """Extract explicit next actions from notes."""
+
+    @abstractmethod
+    def draft_session_summary(self, context: str) -> str:
+        """Draft a concise session summary from context."""
+
+
+class GeminiProvider(LLMProvider):
+    """Gemini-backed provider. Raises when credentials are unavailable."""
+
+    def __init__(self, model: str = FLASH_MODEL):
+        self.model = model
+        self._client = get_client()
+        if not self._client.is_available():
+            raise RuntimeError(
+                "pb requires an LLM for this workflow.\n\n"
+                "Run:\n"
+                "  pb init llm\n\n"
+                "Then configure Gemini credentials via GEMINI_API_KEY or GOOGLE_CLOUD_PROJECT."
+            )
+
+    def _generate(self, prompt: str, *, max_output_tokens: int = 800) -> str:
+        result = self._client.generate_with_model(
+            prompt,
+            self.model,
+            timeout=30,
+            max_output_tokens=max_output_tokens,
+        )
+        if not result or not result.strip():
+            raise RuntimeError("Gemini returned an empty response.")
+        return result.strip()
+
+    def summarize_session(self, session_notes: str) -> str:
+        return self._generate(
+            "Summarize this learning session in 4-6 tight sentences. "
+            "Focus on what was learned, what degraded, and the next adjustment.\n\n"
+            f"{session_notes}",
+        )
+
+    def compress_clip(self, raw_text: str) -> str:
+        return self._generate(
+            "Compress this learning artifact into a concise study note. Preserve specific facts and action items.\n\n"
+            f"{raw_text}",
+        )
+
+    def extract_actions(self, notes: str) -> list[str]:
+        raw = self._generate(
+            "Extract up to five explicit next actions from these learning notes. "
+            "Return one action per line with no bullets or numbering.\n\n"
+            f"{notes}",
+            max_output_tokens=4000,
+        )
+        return [line.strip() for line in raw.splitlines() if line.strip()]
+
+    def draft_session_summary(self, context: str) -> str:
+        return self._generate(
+            "Draft a short markdown summary for this learning session. "
+            "Include summary, evidence, friction, and next action headings.\n\n"
+            f"{context}",
+        )
+
+
+def get_provider(provider_name: Optional[str] = None) -> LLMProvider:
+    """Return the configured Gemini-backed provider."""
+    logger.debug("llm.get_provider", requested=provider_name or "gemini", actual="gemini")
+    return GeminiProvider()

pb/agents/__init__.py

@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# This file is part of ProductiveBrain.
+# Canonical source: https://github.com/qwerty-sapien/pbrain
+# Compliance fingerprint: PB-2026-A17F
+
+"""Agent registry for the dispatch subsystem (Phase 10).
+
+Provides register/resolve/list helpers that mirror the pb/mcp/pending.py
+pattern but for AgentHandler instances rather than MCP tool implementations.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from pb.agents.base import AgentHandler
+
+_AGENT_REGISTRY: dict[str, "AgentHandler"] = {}
+_AGENTS_LOADED = False
+
+
+def register_agent(agent_id: str, handler: "AgentHandler") -> None:
+    """Register a specialised agent handler under its agent_id."""
+    _AGENT_REGISTRY[agent_id] = handler
+
+
+def _ensure_agents_loaded() -> None:
+    """Import all built-in agent modules so they self-register."""
+    global _AGENTS_LOADED
+    if _AGENTS_LOADED:
+        return
+    _AGENTS_LOADED = True
+    import pb.agents.accountability  # noqa: F401
+    import pb.agents.spawner  # noqa: F401
+    import pb.agents.review  # noqa: F401
+    import pb.agents.domain  # noqa: F401
+
+
+def resolve_agent(agent_id: str) -> Optional["AgentHandler"]:
+    """Look up a registered agent by ID.  Returns None if not found."""
+    _ensure_agents_loaded()
+    return _AGENT_REGISTRY.get(agent_id)
+
+
+def list_agents() -> list[str]:
+    """Return sorted list of registered agent IDs."""
+    return sorted(_AGENT_REGISTRY.keys())

pb/agents/accountability.py

@@ -0,0 +1,254 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# This file is part of ProductiveBrain.
+# Canonical source: https://github.com/qwerty-sapien/pbrain
+# Compliance fingerprint: PB-2026-A17F
+
+"""Accountability agent — creates durable commitment records (Phase 10).
+
+Persists commitments to SQLite, enforces spam guard (>5/session),
+optionally surfaces avoidance when goals/commitments context is provided.
+
+Follows D-03: commitments are passive + contextual; no unsolicited nudging.
+Follows D-04: avoidance detection only surfaces in pb next / pb review context.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import structlog
+from pydantic import BaseModel, Field
+
+from pb.agents import register_agent
+from pb.agents.base import AgentHandler
+from pb.core.agent_instruction_judge import agent_instruction_suffix
+from pb.core.dispatch_models import AgentOutput, DispatchSession
+from pb.core.models import generate_internal_id, utc_now
+from pb.llm.structured import structured_output_call
+from pb.storage.database import get_connection
+
+logger = structlog.get_logger()
+
+_COMMITMENT_SPAM_THRESHOLD = 5
+
+
+class CommitmentExtraction(BaseModel):
+    """LLM extraction of commitment details from user intent."""
+
+    description: str = Field(description="What the user is committing to")
+    due_date: Optional[str] = Field(
+        default=None,
+        description="ISO date YYYY-MM-DD if mentioned, otherwise null",
+    )
+    is_commitment: bool = Field(
+        description="True if intent is genuinely an accountability request"
+    )
+    avoidance_note: str = Field(
+        default="",
+        description=(
+            "If context shows the user is avoiding an existing commitment, "
+            "describe which one and how many days since last touched. Empty string if none."
+        ),
+    )
+
+
+_EXTRACTION_SYSTEM_PROMPT = """\
+You are a commitment extraction assistant. Analyse the user's intent and determine:
+1. Whether it is a genuine accountability/commitment request (not just a todo or general chat).
+2. What specific commitment they are making, cleaned of filler words.
+3. If they mention a deadline, extract it as YYYY-MM-DD.
+4. If the provided context contains existing commitments or goals that the user appears to be
+   avoiding or neglecting (e.g. not mentioned, repeatedly deferred), note the most relevant one.
+   Pay special attention to items with approaching deadlines — a commitment due within 3 days
+   that the user is ignoring is more urgent than one due in a month.
+   Only flag avoidance when context data is provided — do NOT fabricate neglect signals.
+
+Accountability requests include: "keep me accountable for X", "I commit to Y", "hold me to Z",
+"remind me to do A by date", "make sure I finish B". Pure todos ("buy milk") are NOT commitments.
+"""
+
+
+class AccountabilityAgent(AgentHandler):
+    """Accountability specialised agent.
+
+    Creates durable commitment records in SQLite (ACCT-01).
+    Detects and notes avoidance patterns when context is available (ACCT-02).
+    Kicks back non-accountability requests to the dispatcher (in_scope=False).
+    """
+
+    agent_id: str = "accountability"
+    display_name: str = "Accountability"
+    model_tier: str = "mid"
+
+    async def handle(
+        self,
+        intent: str,
+        session: DispatchSession,
+        *,
+        context: Optional[dict] = None,
+    ) -> AgentOutput:
+        """Extract commitment from intent, persist to SQLite, surface avoidance if relevant.
+
+        Args:
+            intent: Raw user intent string.
+            session: Current dispatch session record.
+            context: Optional dict. May include "goals" and "commitments" for
+                     avoidance detection; keys match ReviewAgent convention.
+
+        Returns:
+            AgentOutput. in_scope=False if not an accountability request;
+            in_scope=True with persisted commitment and optional avoidance note otherwise.
+        """
+        ctx = context or {}
+        extraction = await self._extract_commitment(intent, ctx)
+
+        if extraction is None:
+            # LLM failed — try to proceed with a minimal commitment
+            logger.warning("accountability.extraction_failed", session_id=session.id)
+            return await self._persist_and_respond(
+                session_id=session.id,
+                description=intent.strip(),
+                due_date=None,
+                avoidance_note="",
+            )
+
+        if not extraction.is_commitment:
+            logger.info(
+                "accountability.not_a_commitment",
+                session_id=session.id,
+                intent=intent[:80],
+            )
+            return AgentOutput(
+                in_scope=False,
+                scope_reason="Not an accountability request",
+                response="",
+            )
+
+        return await self._persist_and_respond(
+            session_id=session.id,
+            description=extraction.description,
+            due_date=extraction.due_date,
+            avoidance_note=extraction.avoidance_note,
+        )
+
+    async def _extract_commitment(
+        self, intent: str, ctx: dict
+    ) -> Optional[CommitmentExtraction]:
+        """Call mid-tier LLM to extract structured commitment data."""
+        context_block = ""
+        goals = ctx.get("goals", [])
+        commitments = ctx.get("commitments", [])
+        deadline_todos = ctx.get("deadline_todos", [])
+        if goals or commitments or deadline_todos:
+            goals_summary = ", ".join(
+                getattr(g, "title", str(g)) for g in goals[:5]
+            )
+            commitments_summary = "; ".join(
+                (c.get("description", "") if isinstance(c, dict) else str(c))
+                for c in commitments[:5]
+            )
+            deadline_lines = []
+            for t in deadline_todos[:5]:
+                due = getattr(t, "due_date", None)
+                due_str = due.strftime("%Y-%m-%d") if due else "no deadline"
+                deadline_lines.append(f"{getattr(t, 'title', '?')} (due {due_str})")
+            deadline_summary = "; ".join(deadline_lines) if deadline_lines else "none"
+
+            context_block = (
+                f"\n\nContext (use only for avoidance detection):\n"
+                f"Active goals: {goals_summary or 'none'}\n"
+                f"Existing commitments: {commitments_summary or 'none'}\n"
+                f"Deadline-approaching tasks: {deadline_summary}"
+            )
+
+        prompt = (
+            f"User intent: {intent!r}{context_block}\n\n"
+            f"Extract commitment details."
+        )
+        try:
+            return await structured_output_call(
+                prompt,
+                CommitmentExtraction,
+                system_prompt=_EXTRACTION_SYSTEM_PROMPT
+                + agent_instruction_suffix(self.agent_id),
+                tier="mid",
+            )
+        except Exception as exc:
+            logger.warning("accountability.llm_error", error=str(exc))
+            return None
+
+    async def _persist_and_respond(
+        self,
+        *,
+        session_id: str,
+        description: str,
+        due_date: Optional[str],
+        avoidance_note: str,
+    ) -> AgentOutput:
+        """Insert commitment into SQLite and build response."""
+        commitment_id = generate_internal_id()
+        created_at = utc_now().isoformat()
+
+        try:
+            with get_connection() as conn:
+                # T-10-09: fully parameterised INSERT, no string interpolation
+                conn.execute(
+                    "INSERT INTO commitments "
+                    "(id, description, created_at, due_date, status, session_id) "
+                    "VALUES (?, ?, ?, ?, ?, ?)",
+                    (commitment_id, description, created_at, due_date, "active", session_id),
+                )
+                conn.commit()
+
+                # Commitment spam guard (T-10-09)
+                row = conn.execute(
+                    "SELECT COUNT(*) FROM commitments WHERE session_id = ?",
+                    (session_id,),
+                ).fetchone()
+                session_count: int = row[0] if row else 0
+
+        except Exception as exc:
+            logger.warning(
+                "accountability.persist_error",
+                error=str(exc),
+                session_id=session_id,
+            )
+            return AgentOutput(
+                in_scope=True,
+                response=f"I tried to record your commitment ({description}) but hit a storage error. Please try again.",
+                status="complete",
+            )
+
+        logger.info(
+            "accountability.commitment_created",
+            commitment_id=commitment_id,
+            session_id=session_id,
+            due_date=due_date,
+        )
+
+        due_suffix = f" by {due_date}" if due_date else ""
+        response = (
+            f"Committed: {description}{due_suffix}. "
+            f"I'll surface this in your next review and recommendations."
+        )
+
+        if session_count > _COMMITMENT_SPAM_THRESHOLD:
+            response += (
+                f"\n\nYou've created {_COMMITMENT_SPAM_THRESHOLD}+ commitments this session. "
+                f"Are these all real commitments?"
+            )
+
+        # D-04: avoidance note only surfaces when caller explicitly passes context
+        # (i.e. called from pb next / pb review context, not from a cold do "...")
+        if avoidance_note:
+            response += f"\n\nNote: {avoidance_note}"
+
+        return AgentOutput(
+            in_scope=True,
+            response=response,
+            status="complete",
+        )
+
+
+# Register at module level so importing this module side-effects the registry
+register_agent("accountability", AccountabilityAgent())

pb/agents/base.py

@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# This file is part of ProductiveBrain.
+# Canonical source: https://github.com/qwerty-sapien/pbrain
+# Compliance fingerprint: PB-2026-A17F
+
+"""AgentHandler ABC — contract all specialised agents implement (Phase 10)."""
+
+from __future__ import annotations
+
+import abc
+from typing import Optional
+
+import structlog
+
+from pb.core.dispatch_models import AgentOutput, DispatchSession, InteractionEnvelope
+
+logger = structlog.get_logger()
+
+
+class AgentHandler(abc.ABC):
+    """Abstract base class for all specialised dispatch agents.
+
+    Every agent must declare its ``agent_id``, ``display_name``, and implement
+    ``handle()`` to process a user intent within a session context.
+    """
+
+    agent_id: str
+    display_name: str
+    model_tier: str = "mid"  # lite | mid | heavy
+
+    @abc.abstractmethod
+    async def handle(
+        self,
+        intent: str,
+        session: DispatchSession,
+        *,
+        context: Optional[dict] = None,
+    ) -> AgentOutput:
+        """Process user intent and return structured output.
+
+        Args:
+            intent: The raw user intent string.
+            session: The current dispatch session record.
+            context: Optional extra context dict (e.g. goal data, history).
+
+        Returns:
+            AgentOutput with in_scope flag, response, options, and status.
+        """
+        ...
+
+    def to_envelope(
+        self, session: DispatchSession, output: AgentOutput
+    ) -> InteractionEnvelope:
+        """Convert AgentOutput to the uniform InteractionEnvelope wire format.
+
+        scope_reason stays in AgentOutput (internal).  It is intentionally NOT
+        propagated to the envelope (T-10-03 mitigation).
+        """
+        return InteractionEnvelope(
+            session_id=session.id,
+            status=output.status,
+            prompt=output.response,
+            options=output.options,
+            fields=output.fields,
+        )

pb/agents/colors.py

@@ -0,0 +1,70 @@
+"""Unique quaternary colors for agent labels in terminal output.
+
+Each registered agent gets a distinct Rich color name from a 24-color
+quaternary palette. When more than 24 agents exist, the color of the
+agent inactive for the longest period is recycled.
+"""
+from __future__ import annotations
+
+import time
+
+_QUATERNARY_PALETTE: list[str] = [
+    "bright_cyan",
+    "bright_magenta",
+    "bright_yellow",
+    "bright_green",
+    "dodger_blue2",
+    "dark_orange",
+    "medium_purple1",
+    "spring_green2",
+    "deep_pink2",
+    "chartreuse2",
+    "cornflower_blue",
+    "indian_red1",
+    "turquoise2",
+    "orchid1",
+    "gold1",
+    "pale_green1",
+    "hot_pink",
+    "sky_blue1",
+    "salmon1",
+    "medium_spring_green",
+    "plum2",
+    "light_goldenrod2",
+    "aquamarine1",
+    "light_coral",
+]
+
+_PALETTE_SIZE = len(_QUATERNARY_PALETTE)
+
+_agent_color_map: dict[str, str] = {}
+_agent_last_seen: dict[str, float] = {}
+
+
+def color_for_agent(agent_id: str) -> str:
+    """Return a unique Rich color name for the given agent ID.
+
+    Deterministic for known agents. If the palette is full, evicts the
+    agent with the oldest last-seen timestamp and reassigns its color.
+    """
+    now = time.monotonic()
+    _agent_last_seen[agent_id] = now
+
+    if agent_id in _agent_color_map:
+        return _agent_color_map[agent_id]
+
+    used_colors = set(_agent_color_map.values())
+    for color in _QUATERNARY_PALETTE:
+        if color not in used_colors:
+            _agent_color_map[agent_id] = color
+            return color
+
+    # Palette exhausted — evict the longest-inactive agent
+    oldest_agent = min(
+        (aid for aid in _agent_last_seen if aid != agent_id and aid in _agent_color_map),
+        key=lambda aid: _agent_last_seen[aid],
+    )
+    recycled_color = _agent_color_map.pop(oldest_agent)
+    _agent_last_seen.pop(oldest_agent, None)
+    _agent_color_map[agent_id] = recycled_color
+    return recycled_color