buildlog 0.3.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

buildlog/mcp/__init__.py

@@ -2,6 +2,7 @@
 
 from buildlog.mcp.tools import (
     buildlog_diff,
+    buildlog_learn_from_review,
     buildlog_promote,
     buildlog_reject,
     buildlog_status,
@@ -12,4 +13,5 @@ __all__ = [
     "buildlog_promote",
     "buildlog_reject",
     "buildlog_diff",
+    "buildlog_learn_from_review",
 ]

buildlog/mcp/server.py

@@ -6,8 +6,16 @@ from mcp.server.fastmcp import FastMCP
 
 from buildlog.mcp.tools import (
     buildlog_diff,
+    buildlog_end_session,
+    buildlog_experiment_report,
+    buildlog_learn_from_review,
+    buildlog_log_mistake,
+    buildlog_log_reward,
     buildlog_promote,
     buildlog_reject,
+    buildlog_rewards,
+    buildlog_session_metrics,
+    buildlog_start_session,
     buildlog_status,
 )
 
@@ -18,6 +26,16 @@ mcp.tool()(buildlog_status)
 mcp.tool()(buildlog_promote)
 mcp.tool()(buildlog_reject)
 mcp.tool()(buildlog_diff)
+mcp.tool()(buildlog_learn_from_review)
+mcp.tool()(buildlog_log_reward)
+mcp.tool()(buildlog_rewards)
+
+# Session tracking tools (experiment infrastructure)
+mcp.tool()(buildlog_start_session)
+mcp.tool()(buildlog_end_session)
+mcp.tool()(buildlog_log_mistake)
+mcp.tool()(buildlog_session_metrics)
+mcp.tool()(buildlog_experiment_report)
 
 
 def main() -> None:

buildlog/mcp/tools.py

@@ -9,7 +9,20 @@ from dataclasses import asdict
 from pathlib import Path
 from typing import Literal
 
-from buildlog.core import diff, promote, reject, status
+from buildlog.core import (
+    diff,
+    end_session,
+    get_experiment_report,
+    get_rewards,
+    get_session_metrics,
+    learn_from_review,
+    log_mistake,
+    log_reward,
+    promote,
+    reject,
+    start_session,
+    status,
+)
 
 
 def _validate_skill_ids(skill_ids: list[str]) -> list[str]:
@@ -95,3 +108,300 @@ def buildlog_diff(
     """
     result = diff(Path(buildlog_dir))
     return asdict(result)
+
+
+def buildlog_learn_from_review(
+    issues: list[dict],
+    source: str | None = None,
+    buildlog_dir: str = "buildlog",
+) -> dict:
+    """Capture learnings from code review feedback.
+
+    Call this after a review loop completes to persist learnings.
+    Each issue's rule_learned becomes a tracked learning that gains
+    confidence through reinforcement.
+
+    Args:
+        issues: List of issues with structure:
+            {
+                "severity": "critical|major|minor|nitpick",
+                "category": "architectural|workflow|tool_usage|domain_knowledge",
+                "description": "What's wrong",
+                "rule_learned": "Generalizable rule",
+                "location": "file:line (optional)",
+                "why_it_matters": "Why this matters (optional)",
+                "functional_principle": "FP principle (optional)"
+            }
+        source: Optional identifier (e.g., "PR#13")
+        buildlog_dir: Path to buildlog directory
+
+    Returns:
+        Result with new_learnings, reinforced_learnings, total processed
+
+    Example:
+        buildlog_learn_from_review(
+            issues=[
+                {
+                    "severity": "critical",
+                    "category": "architectural",
+                    "description": "Score bounds not validated",
+                    "rule_learned": "Validate invariants at function boundaries"
+                }
+            ],
+            source="PR#13"
+        )
+    """
+    result = learn_from_review(Path(buildlog_dir), issues, source)
+    return asdict(result)
+
+
+def buildlog_log_reward(
+    outcome: str,
+    rules_active: list[str] | None = None,
+    revision_distance: float | None = None,
+    error_class: str | None = None,
+    notes: str | None = None,
+    buildlog_dir: str = "buildlog",
+) -> dict:
+    """Log a reward signal for bandit learning.
+
+    Call this after agent work to provide feedback on the outcome.
+    This enables learning which rules are effective in which contexts.
+
+    Args:
+        outcome: Type of feedback:
+            - "accepted": Work was accepted as-is (reward=1.0)
+            - "revision": Work needed changes (reward=1-distance)
+            - "rejected": Work was rejected entirely (reward=0.0)
+        rules_active: List of rule IDs that were in context during the work
+        revision_distance: How much correction was needed (0-1, 0=minor tweak, 1=complete redo)
+        error_class: Category of error if applicable (e.g., "missing_test", "validation_boundary")
+        notes: Optional notes about the feedback
+        buildlog_dir: Path to buildlog directory
+
+    Returns:
+        Dict with reward_id, reward_value, total_events
+
+    Example:
+        # Work was accepted
+        buildlog_log_reward(outcome="accepted", rules_active=["arch-123", "wf-456"])
+
+        # Work needed revision
+        buildlog_log_reward(
+            outcome="revision",
+            revision_distance=0.3,
+            error_class="missing_test",
+            notes="Forgot to test error path"
+        )
+
+        # Work was rejected
+        buildlog_log_reward(outcome="rejected", notes="Completely wrong approach")
+    """
+    # Validate outcome
+    if outcome not in ("accepted", "revision", "rejected"):
+        return {
+            "reward_id": "",
+            "reward_value": 0.0,
+            "total_events": 0,
+            "message": "",
+            "error": f"Invalid outcome: {outcome}. Must be 'accepted', 'revision', or 'rejected'",
+        }
+
+    result = log_reward(
+        Path(buildlog_dir),
+        outcome=outcome,  # type: ignore[arg-type]
+        rules_active=rules_active,
+        revision_distance=revision_distance,
+        error_class=error_class,
+        notes=notes,
+        source="mcp",
+    )
+    return asdict(result)
+
+
+def buildlog_rewards(
+    limit: int | None = None,
+    buildlog_dir: str = "buildlog",
+) -> dict:
+    """Get reward events with summary statistics.
+
+    Returns recent reward events and aggregate statistics useful for
+    understanding learning progress.
+
+    Args:
+        limit: Maximum number of events to return (most recent first)
+        buildlog_dir: Path to buildlog directory
+
+    Returns:
+        Dict with:
+            - total_events: Total count of reward events
+            - accepted: Count of accepted outcomes
+            - revisions: Count of revision outcomes
+            - rejected: Count of rejected outcomes
+            - mean_reward: Average reward value
+            - events: List of recent events (limited)
+
+    Example:
+        buildlog_rewards(limit=10)  # Get 10 most recent events with stats
+    """
+    result = get_rewards(Path(buildlog_dir), limit)
+
+    # Convert events to dicts
+    return {
+        "total_events": result.total_events,
+        "accepted": result.accepted,
+        "revisions": result.revisions,
+        "rejected": result.rejected,
+        "mean_reward": result.mean_reward,
+        "events": [e.to_dict() for e in result.events],
+    }
+
+
+# -----------------------------------------------------------------------------
+# Session Tracking MCP Tools (Experiment Infrastructure)
+# -----------------------------------------------------------------------------
+
+
+def buildlog_start_session(
+    error_class: str | None = None,
+    notes: str | None = None,
+    buildlog_dir: str = "buildlog",
+) -> dict:
+    """Start a new experiment session.
+
+    Begins tracking for a learning experiment. Captures the current
+    set of active rules to measure learning over time.
+
+    Args:
+        error_class: Error class being targeted (e.g., "missing_test")
+        notes: Notes about this session
+        buildlog_dir: Path to buildlog directory
+
+    Returns:
+        Dict with session_id, error_class, rules_count, message
+
+    Example:
+        buildlog_start_session(error_class="missing_test")
+    """
+    result = start_session(
+        Path(buildlog_dir),
+        error_class=error_class,
+        notes=notes,
+    )
+    return asdict(result)
+
+
+def buildlog_end_session(
+    entry_file: str | None = None,
+    notes: str | None = None,
+    buildlog_dir: str = "buildlog",
+) -> dict:
+    """End the current experiment session.
+
+    Finalizes the session and calculates metrics including:
+    - Total mistakes logged
+    - Repeated mistakes (from prior sessions)
+    - Rules added during session
+
+    Args:
+        entry_file: Corresponding buildlog entry file, if any
+        notes: Additional notes to append
+        buildlog_dir: Path to buildlog directory
+
+    Returns:
+        Dict with session_id, duration_minutes, mistakes_logged,
+        repeated_mistakes, rules_at_start, rules_at_end, message
+
+    Example:
+        buildlog_end_session(entry_file="2026-01-21.md")
+    """
+    result = end_session(
+        Path(buildlog_dir),
+        entry_file=entry_file,
+        notes=notes,
+    )
+    return asdict(result)
+
+
+def buildlog_log_mistake(
+    error_class: str,
+    description: str,
+    corrected_by_rule: str | None = None,
+    buildlog_dir: str = "buildlog",
+) -> dict:
+    """Log a mistake during the current session.
+
+    Records the mistake and checks if it's a repeat of a prior mistake
+    (from earlier sessions). This enables measuring repeated-mistake rates.
+
+    Args:
+        error_class: Category of error (e.g., "missing_test")
+        description: Description of the mistake
+        corrected_by_rule: Rule ID that should have prevented this
+        buildlog_dir: Path to buildlog directory
+
+    Returns:
+        Dict with mistake_id, session_id, was_repeat, similar_prior, message
+
+    Example:
+        buildlog_log_mistake(
+            error_class="missing_test",
+            description="Forgot to add unit tests for new helper function"
+        )
+    """
+    result = log_mistake(
+        Path(buildlog_dir),
+        error_class=error_class,
+        description=description,
+        corrected_by_rule=corrected_by_rule,
+    )
+    return asdict(result)
+
+
+def buildlog_session_metrics(
+    session_id: str | None = None,
+    buildlog_dir: str = "buildlog",
+) -> dict:
+    """Get metrics for a session or all sessions.
+
+    Returns mistake rates and rule changes for analysis.
+
+    Args:
+        session_id: Specific session ID, or None for aggregate metrics
+        buildlog_dir: Path to buildlog directory
+
+    Returns:
+        Dict with session_id, total_mistakes, repeated_mistakes,
+        repeated_mistake_rate, rules_at_start, rules_at_end, rules_added
+
+    Example:
+        buildlog_session_metrics()  # Aggregate metrics
+        buildlog_session_metrics(session_id="session-20260121-140000")
+    """
+    result = get_session_metrics(
+        Path(buildlog_dir),
+        session_id=session_id,
+    )
+    return asdict(result)
+
+
+def buildlog_experiment_report(
+    buildlog_dir: str = "buildlog",
+) -> dict:
+    """Generate a comprehensive experiment report.
+
+    Returns summary statistics, per-session breakdown, and error class analysis.
+
+    Args:
+        buildlog_dir: Path to buildlog directory
+
+    Returns:
+        Dict with:
+            - summary: Overall statistics
+            - sessions: Per-session breakdown
+            - error_classes: Breakdown by error class
+
+    Example:
+        buildlog_experiment_report()
+    """
+    return get_experiment_report(Path(buildlog_dir))

buildlog/skills.py

@@ -33,6 +33,18 @@ from buildlog.embeddings import EmbeddingBackend, get_backend, get_default_backe
 
 logger = logging.getLogger(__name__)
 
+
+def _load_review_learnings(buildlog_dir: Path) -> dict:
+    """Load review learnings from .buildlog/review_learnings.json."""
+    learnings_path = buildlog_dir / ".buildlog" / "review_learnings.json"
+    if not learnings_path.exists():
+        return {"learnings": {}}
+    try:
+        return json.loads(learnings_path.read_text())
+    except (json.JSONDecodeError, OSError):
+        return {"learnings": {}}
+
+
 # Configuration constants
 MIN_SIMILARITY_THRESHOLD: Final[float] = 0.7
 HIGH_CONFIDENCE_FREQUENCY: Final[int] = 3
@@ -398,8 +410,9 @@ def generate_skills(
     since_date: date | None = None,
     embedding_backend: str | None = None,
     confidence_config: ConfidenceConfig | None = None,
+    include_review_learnings: bool = True,
 ) -> SkillSet:
-    """Generate skills from buildlog patterns.
+    """Generate skills from buildlog patterns and review learnings.
 
     Args:
         buildlog_dir: Path to the buildlog directory.
@@ -410,6 +423,9 @@ def generate_skills(
         confidence_config: Configuration for continuous confidence scoring.
             If provided, skills will include confidence_score and confidence_tier.
             If None, only discrete confidence levels (high/medium/low) are computed.
+        include_review_learnings: Whether to include learnings from code reviews.
+            When True, loads .buildlog/review_learnings.json and merges
+            review learnings into the skill set.
 
     Returns:
         SkillSet with generated skills.
@@ -468,6 +484,111 @@ def generate_skills(
         skills.sort(key=lambda s: (-s.frequency, s.rule))
         skills_by_category[category] = skills
 
+    # Merge review learnings if requested
+    if include_review_learnings:
+        review_data = _load_review_learnings(buildlog_dir)
+        learnings = review_data.get("learnings", {})
+
+        for learning_id, learning_dict in learnings.items():
+            category = learning_dict.get("category", "workflow")
+            rule = learning_dict.get("rule", "")
+
+            if not rule:
+                continue
+
+            # Parse timestamps for confidence calculation
+            first_seen_str = learning_dict.get("first_seen", "")
+            last_reinforced_str = learning_dict.get("last_reinforced", "")
+
+            try:
+                first_seen = datetime.fromisoformat(first_seen_str)
+                if first_seen.tzinfo is None:
+                    first_seen = first_seen.replace(tzinfo=timezone.utc)
+            except (ValueError, TypeError):
+                first_seen = datetime.now(timezone.utc)
+
+            try:
+                last_reinforced = datetime.fromisoformat(last_reinforced_str)
+                if last_reinforced.tzinfo is None:
+                    last_reinforced = last_reinforced.replace(tzinfo=timezone.utc)
+            except (ValueError, TypeError):
+                last_reinforced = datetime.now(timezone.utc)
+
+            # Get frequency from reinforcement count
+            frequency = learning_dict.get("reinforcement_count", 1)
+
+            # Check for duplicate rules in existing skills (by ID match)
+            existing_skill = None
+            if category in skills_by_category:
+                for skill in skills_by_category[category]:
+                    if skill.id == learning_id:
+                        existing_skill = skill
+                        break
+
+            if existing_skill is not None:
+                # Merge: boost the existing skill's frequency
+                existing_skill = Skill(
+                    id=existing_skill.id,
+                    category=existing_skill.category,
+                    rule=existing_skill.rule,
+                    frequency=existing_skill.frequency + frequency,
+                    confidence=existing_skill.confidence,
+                    sources=existing_skill.sources
+                    + [learning_dict.get("source", "review")],
+                    tags=existing_skill.tags,
+                    confidence_score=existing_skill.confidence_score,
+                    confidence_tier=existing_skill.confidence_tier,
+                )
+                # Replace in list
+                skills_by_category[category] = [
+                    existing_skill if s.id == existing_skill.id else s
+                    for s in skills_by_category[category]
+                ]
+            else:
+                # Create new skill from review learning
+                review_conf_score: float | None = None
+                review_conf_tier: str | None = None
+
+                if confidence_config is not None and t_now is not None:
+                    metrics = ConfidenceMetrics(
+                        reinforcement_count=frequency,
+                        last_reinforced=last_reinforced,
+                        contradiction_count=learning_dict.get("contradiction_count", 0),
+                        first_seen=first_seen,
+                    )
+                    review_conf_score = calculate_continuous_confidence(
+                        metrics, confidence_config, t_now
+                    )
+                    review_conf_tier = get_confidence_tier(
+                        review_conf_score, confidence_config
+                    ).value
+
+                # Calculate discrete confidence from most recent date
+                discrete_confidence = _calculate_confidence(
+                    frequency, last_reinforced.date()
+                )
+
+                skill = Skill(
+                    id=learning_id,
+                    category=category,
+                    rule=rule,
+                    frequency=frequency,
+                    confidence=discrete_confidence,
+                    sources=[learning_dict.get("source", "review")],
+                    tags=_extract_tags(rule),
+                    confidence_score=review_conf_score,
+                    confidence_tier=review_conf_tier,
+                )
+
+                # Add to category
+                if category not in skills_by_category:
+                    skills_by_category[category] = []
+                skills_by_category[category].append(skill)
+
+        # Re-sort categories after adding review learnings
+        for category in skills_by_category:
+            skills_by_category[category].sort(key=lambda s: (-s.frequency, s.rule))
+
     return SkillSet(
         generated_at=datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
         source_entries=result.entry_count,