buildlog 0.6.1__py3-none-any.whl → 0.8.0__py3-none-any.whl

buildlog/distill.py

@@ -8,6 +8,7 @@ __all__ = [
     "distill_all",
     "format_output",
     "parse_improvements",
+    "parse_improvements_llm",
     "parse_date_from_filename",
     "iter_buildlog_entries",
 ]
@@ -19,7 +20,10 @@ from collections.abc import Iterator
 from dataclasses import dataclass, field
 from datetime import date, datetime, timezone
 from pathlib import Path
-from typing import Final, Literal, TypedDict
+from typing import TYPE_CHECKING, Final, Literal, TypedDict
+
+if TYPE_CHECKING:
+    from buildlog.llm import ExtractedRule, LLMBackend
 
 logger = logging.getLogger(__name__)
 
@@ -191,6 +195,36 @@ def parse_improvements(content: str) -> dict[str, list[str]]:
     return result
 
 
+def parse_improvements_llm(content: str, backend: LLMBackend) -> list[ExtractedRule]:
+    """Extract improvements using an LLM backend for richer extraction.
+
+    Sends the Improvements section to the LLM for structured extraction
+    of rules with severity, scope, applicability, and defensibility fields.
+
+    Args:
+        content: The full markdown content of a buildlog entry.
+        backend: An LLM backend implementing the LLMBackend protocol.
+
+    Returns:
+        List of ExtractedRule objects with rich metadata.
+    """
+    # Extract the Improvements section
+    improvements_match = re.search(
+        r"^##\s+Improvements\s*\n(.*?)(?=^#{1,2}\s|\Z)",
+        content,
+        re.MULTILINE | re.DOTALL,
+    )
+
+    if not improvements_match:
+        return []
+
+    improvements_text = improvements_match.group(1).strip()
+    if not improvements_text:
+        return []
+
+    return backend.extract_rules(improvements_text)
+
+
 def parse_date_from_filename(filename: str) -> str | None:
     """Extract date from buildlog filename (YYYY-MM-DD-slug.md format)."""
     match = re.match(r"^(\d{4}-\d{2}-\d{2})-", filename)
@@ -290,6 +324,7 @@ def distill_all(
     buildlog_dir: Path,
     since: date | None = None,
     category_filter: str | None = None,
+    llm: bool = False,
 ) -> DistillResult:
     """Parse all buildlog entries and aggregate patterns.
 
@@ -297,10 +332,23 @@ def distill_all(
         buildlog_dir: Path to the buildlog directory.
         since: If provided, only include entries from this date onward.
         category_filter: If provided, only include patterns from this category.
+        llm: If True and an LLM backend is available, use LLM extraction.
+            Falls back to regex on failure or if no backend is available.
 
     Returns:
         DistillResult with aggregated patterns and statistics.
     """
+    # Resolve LLM backend if requested
+    llm_backend: LLMBackend | None = None
+    if llm:
+        from buildlog.llm import get_llm_backend
+
+        llm_backend = get_llm_backend(buildlog_dir=buildlog_dir)
+        if llm_backend is None:
+            logger.warning(
+                "--llm requested but no LLM provider available, using regex fallback"
+            )
+
     patterns: dict[str, list[PatternDict]] = {cat: [] for cat in CATEGORIES}
     by_month: dict[str, int] = {}
     entry_count = 0
@@ -318,6 +366,37 @@ def distill_all(
         month_key = _extract_month_key(date_str)
         by_month[month_key] = by_month.get(month_key, 0) + 1
 
+        # Try LLM extraction first, fall back to regex
+        if llm_backend is not None:
+            try:
+                extracted = parse_improvements_llm(content, llm_backend)
+                if extracted:
+                    # Convert ExtractedRule objects to standard PatternDict format
+                    for rule in extracted:
+                        cat = (
+                            rule.category
+                            if rule.category in CATEGORIES
+                            else "architectural"
+                        )
+                        if cat not in patterns:
+                            patterns[cat] = []
+                        patterns[cat].append(
+                            PatternDict(
+                                insight=rule.rule,
+                                source=str(entry_path),
+                                date=date_str,
+                                context=context,
+                            )
+                        )
+                    continue  # Skip regex if LLM succeeded
+            except Exception as e:
+                logger.warning(
+                    "LLM extraction failed for %s, falling back to regex: %s",
+                    entry_path,
+                    e,
+                )
+
+        # Regex fallback (default behavior)
         try:
             improvements = parse_improvements(content)
         except re.error as e:

buildlog/engine/__init__.py

@@ -0,0 +1,61 @@
+"""Buildlog Engine — agent-agnostic core for rule learning and experiment tracking.
+
+This package provides the pure algorithmic core of buildlog without any
+CLI, copier, or agent-specific rendering dependencies. Use it when you
+want Thompson Sampling bandits, confidence scoring, embedding similarity,
+or experiment tracking in your own tools.
+
+Usage:
+    from buildlog.engine import ThompsonSamplingBandit, BetaParams
+    from buildlog.engine import calculate_confidence, ConfidenceMetrics
+    from buildlog.engine import start_session, end_session, log_mistake
+    from buildlog.engine.types import Skill, Session, Mistake, RewardEvent
+
+Install:
+    pip install buildlog          # engine is part of the base package
+    pip install buildlog[engine]  # same thing — documents the namespace
+"""
+
+from buildlog.engine.bandit import BetaParams, ThompsonSamplingBandit
+from buildlog.engine.confidence import (
+    ConfidenceConfig,
+    ConfidenceMetrics,
+    calculate_confidence,
+    get_confidence_tier,
+    merge_confidence_metrics,
+)
+from buildlog.engine.experiments import (
+    end_session,
+    experiment_report,
+    get_rewards,
+    log_mistake,
+    log_reward,
+    session_metrics,
+    start_session,
+)
+from buildlog.engine.types import Mistake, RewardEvent, Session, Skill
+
+__all__ = [
+    # Bandit
+    "ThompsonSamplingBandit",
+    "BetaParams",
+    # Confidence
+    "calculate_confidence",
+    "get_confidence_tier",
+    "merge_confidence_metrics",
+    "ConfidenceMetrics",
+    "ConfidenceConfig",
+    # Experiments
+    "start_session",
+    "end_session",
+    "log_mistake",
+    "log_reward",
+    "get_rewards",
+    "session_metrics",
+    "experiment_report",
+    # Types
+    "Skill",
+    "Session",
+    "Mistake",
+    "RewardEvent",
+]

buildlog/engine/bandit.py

@@ -0,0 +1,23 @@
+"""Re-export Thompson Sampling bandit from core.
+
+Provides clean access to the bandit without reaching into core internals.
+
+Usage:
+    from buildlog.engine.bandit import ThompsonSamplingBandit, BetaParams
+"""
+
+from buildlog.core.bandit import (
+    DEFAULT_CONTEXT,
+    DEFAULT_SEED_BOOST,
+    BanditState,
+    BetaParams,
+    ThompsonSamplingBandit,
+)
+
+__all__ = [
+    "ThompsonSamplingBandit",
+    "BetaParams",
+    "BanditState",
+    "DEFAULT_SEED_BOOST",
+    "DEFAULT_CONTEXT",
+]

buildlog/engine/confidence.py

@@ -0,0 +1,28 @@
+"""Re-export confidence scoring from buildlog.confidence.
+
+Provides clean access to confidence calculation without reaching into
+top-level module internals.
+
+Usage:
+    from buildlog.engine.confidence import calculate_confidence, ConfidenceMetrics
+"""
+
+from buildlog.confidence import (
+    ConfidenceConfig,
+    ConfidenceMetrics,
+    ConfidenceTier,
+    add_contradiction,
+    calculate_confidence,
+    get_confidence_tier,
+    merge_confidence_metrics,
+)
+
+__all__ = [
+    "calculate_confidence",
+    "get_confidence_tier",
+    "merge_confidence_metrics",
+    "add_contradiction",
+    "ConfidenceMetrics",
+    "ConfidenceConfig",
+    "ConfidenceTier",
+]

buildlog/engine/embeddings.py

@@ -0,0 +1,28 @@
+"""Re-export embedding backends from buildlog.embeddings.
+
+Provides clean access to embedding similarity without reaching into
+top-level module internals.
+
+Usage:
+    from buildlog.engine.embeddings import similarity, TokenBackend
+"""
+
+from buildlog.embeddings import (
+    EmbeddingBackend,
+    OpenAIBackend,
+    SentenceTransformerBackend,
+    TokenBackend,
+    compute_embeddings,
+    get_backend,
+    similarity,
+)
+
+__all__ = [
+    "EmbeddingBackend",
+    "TokenBackend",
+    "SentenceTransformerBackend",
+    "OpenAIBackend",
+    "get_backend",
+    "similarity",
+    "compute_embeddings",
+]