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

buildlog/data/seeds/bragi.yaml

@@ -0,0 +1,61 @@
+# Bragi - LLM Prose Pattern Detection (named for the skald of the Aesir)
+# Detect and flag synthetic-sounding prose patterns common in LLM-generated text
+# These patterns aren't inherently wrong, but their overuse signals machine authorship
+
+persona: bragi
+version: 1
+
+rules:
+  - rule: "Em-dash usage"
+    category: prose
+    context: "Anywhere: headlines, parentheticals, contrasts, asides"
+    antipattern: "Any use of em dashes (—). Includes 'Not X — Y' pivots, parenthetical asides, and dramatic pauses."
+    rationale: "LLMs deploy em dashes constantly and poorly. Ban them outright. Use colons, semicolons, commas, parentheses, or separate sentences instead."
+
+  - rule: "Dismissive 'with' framing"
+    category: prose
+    context: "Feature descriptions, project summaries, demo introductions"
+    antipattern: "'A demo with persistence', 'a prototype with authentication' — reducing a significant feature to a prepositional afterthought"
+    rationale: "Makes complex work sound trivially assembled. Signals the author hasn't weighed the feature's actual cost."
+
+  - rule: "Tricolon and five-item enumerations"
+    category: prose
+    context: "Value propositions, team descriptions, capability lists"
+    antipattern: "'They execute, improvise, and forget' or 'fast, reliable, scalable, secure, and observable' — rhythmic clause lists"
+    rationale: "LLMs default to tricolons and pentalogies for rhetorical rhythm. Real technical writing itemizes what matters, not what sounds balanced."
+
+  - rule: "Performative honesty"
+    category: prose
+    context: "Status updates, retrospectives, project assessments"
+    antipattern: "'Being honest about where things are:', 'To be frank:', 'The truth is:' — flagging your own candor"
+    rationale: "If you have to announce you're being honest, the surrounding text is performing. Just state the thing."
+
+  - rule: "Self-referential pivot"
+    category: prose
+    context: "Comparative sections, differentiation arguments"
+    antipattern: "'This is where X diverges from...', 'This is where things get interesting' — narrating the structure of your own argument"
+    rationale: "Meta-commentary about your own text is a crutch. Make the point; don't announce you're about to make it."
+
+  - rule: "Punchy fragment marketing copy"
+    category: prose
+    context: "Taglines, hero sections, feature callouts"
+    antipattern: "'One knowledge base, every agent surface.' — sentence fragments styled as advertising slogans"
+    rationale: "Technical docs aren't ad copy. Fragment slogans trade precision for vibes."
+
+  - rule: "Colon-into-bold-statement"
+    category: prose
+    context: "Section transitions, key takeaways, framing statements"
+    antipattern: "'The question it answers: **How do you...**' — colon followed by a bolded rhetorical question or declaration"
+    rationale: "This is a formatting crutch that substitutes typographic emphasis for actual argumentative weight."
+
+  - rule: "Rhythmic parallel construction closers"
+    category: prose
+    context: "Paragraph endings, section closers, conclusions"
+    antipattern: "'decisions tied to outcomes, updated by evidence, grounded in practice' — parallel participial phrases as closers"
+    rationale: "These read as sermon cadences. They sound authoritative but say little. End with a concrete claim instead."
+
+  - rule: "Hedging with 'not' lists"
+    category: prose
+    context: "Definitions, scope statements, positioning"
+    antipattern: "'This is not X. Not Y. Not Z.' — defining something entirely by what it isn't, in staccato negation"
+    rationale: "Negative definition is evasive. Say what the thing is. Reserve negation for genuine disambiguation."

buildlog/llm.py

@@ -28,8 +28,10 @@ __all__ = [
 import json
 import logging
 import os
+import time
 from dataclasses import dataclass, field
 from pathlib import Path
+from types import MappingProxyType
 from typing import Protocol, runtime_checkable
 
 logger = logging.getLogger(__name__)
@@ -84,6 +86,14 @@ class LLMConfig:
     base_url: str | None = None  # Override endpoint
     api_key: str | None = None  # From config or env var
 
+    def __repr__(self) -> str:
+        """Redact api_key to prevent accidental exposure in logs/tracebacks."""
+        key_display = "***" if self.api_key else "None"
+        return (
+            f"LLMConfig(provider={self.provider!r}, model={self.model!r}, "
+            f"base_url={self.base_url!r}, api_key={key_display})"
+        )
+
     @classmethod
     def from_buildlog_config(cls, buildlog_dir: Path) -> LLMConfig | None:
         """Read from .buildlog/config.yml [llm] section."""
@@ -225,6 +235,28 @@ def _parse_json_response(text: str) -> list | dict:
     return json.loads(text)
 
 
+# --- Rate limiting ---
+
+# Minimum seconds between API calls (per-backend instance).
+_MIN_CALL_INTERVAL = 0.5
+
+
+class _RateLimiter:
+    """Simple per-instance rate limiter to prevent API abuse."""
+
+    def __init__(self, min_interval: float = _MIN_CALL_INTERVAL):
+        self._min_interval = min_interval
+        self._last_call: float = 0.0
+
+    def wait(self) -> None:
+        """Block until min_interval has elapsed since last call."""
+        now = time.monotonic()
+        elapsed = now - self._last_call
+        if elapsed < self._min_interval:
+            time.sleep(self._min_interval - elapsed)
+        self._last_call = time.monotonic()
+
+
 # --- Implementations ---
 
 
@@ -235,6 +267,7 @@ class OllamaBackend:
         self._model = model
         self._base_url = base_url
         self._resolved_model: str | None = None
+        self._rate_limiter = _RateLimiter()
 
     def _get_model(self) -> str:
         """Resolve model name, auto-detecting largest if not specified."""
@@ -269,6 +302,7 @@ class OllamaBackend:
 
     def _chat(self, prompt: str) -> str:
         """Send a prompt to Ollama and return the response text."""
+        self._rate_limiter.wait()
         import ollama as ollama_lib
 
         kwargs = {
@@ -334,6 +368,11 @@ class AnthropicBackend:
         self._model = model or "claude-haiku-4-20250514"
         self._api_key = api_key or os.environ.get("ANTHROPIC_API_KEY")
         self._client = None
+        self._rate_limiter = _RateLimiter()
+
+    def __repr__(self) -> str:
+        """Redact API key from repr to prevent exposure in logs/tracebacks."""
+        return f"AnthropicBackend(model={self._model!r}, api_key=***)"
 
     def _get_client(self):
         """Lazy-load the Anthropic client."""
@@ -351,6 +390,7 @@ class AnthropicBackend:
 
     def _chat(self, prompt: str) -> str:
         """Send a prompt to Claude and return the response text."""
+        self._rate_limiter.wait()
         client = self._get_client()
         response = client.messages.create(
             model=self._model,
@@ -402,15 +442,22 @@ class AnthropicBackend:
 
 # --- Registry ---
 
-PROVIDERS: dict[str, type] = {
+_PROVIDERS: dict[str, type] = {
     "ollama": OllamaBackend,
     "anthropic": AnthropicBackend,
 }
+# Public read-only view. Use register_provider() to add entries.
+PROVIDERS: MappingProxyType[str, type] = MappingProxyType(_PROVIDERS)
 
 
 def register_provider(name: str, cls: type) -> None:
-    """Register a new LLM provider backend."""
-    PROVIDERS[name] = cls
+    """Register a new LLM provider backend.
+
+    This is the only sanctioned way to mutate the provider registry.
+    """
+    if not isinstance(name, str) or not name.strip():
+        raise ValueError("Provider name must be a non-empty string")
+    _PROVIDERS[name] = cls
 
 
 def get_llm_backend(
@@ -439,7 +486,7 @@ def get_llm_backend(
         logger.info("No LLM provider available, using regex fallback")
         return None
 
-    provider_cls = PROVIDERS.get(config.provider)
+    provider_cls = _PROVIDERS.get(config.provider)
     if provider_cls is None:
         logger.warning("Unknown LLM provider: %s", config.provider)
         return None

buildlog/mcp/__init__.py

@@ -1,17 +1,65 @@
 """MCP server for buildlog integration."""
 
 from buildlog.mcp.tools import (
+    buildlog_bandit_status,
+    buildlog_commit,
     buildlog_diff,
+    buildlog_distill,
+    buildlog_entry_list,
+    buildlog_entry_new,
+    buildlog_experiment_end,
+    buildlog_experiment_metrics,
+    buildlog_experiment_report,
+    buildlog_experiment_start,
+    buildlog_gauntlet_accept_risk,
+    buildlog_gauntlet_generate,
+    buildlog_gauntlet_issues,
+    buildlog_gauntlet_list_personas,
+    buildlog_gauntlet_loop,
+    buildlog_gauntlet_prompt,
+    buildlog_gauntlet_rules,
+    buildlog_init,
     buildlog_learn_from_review,
+    buildlog_log_mistake,
+    buildlog_log_reward,
+    buildlog_overview,
     buildlog_promote,
     buildlog_reject,
+    buildlog_rewards,
+    buildlog_skills,
+    buildlog_stats,
     buildlog_status,
+    buildlog_update,
 )
 
 __all__ = [
-    "buildlog_status",
-    "buildlog_promote",
-    "buildlog_reject",
+    "buildlog_bandit_status",
+    "buildlog_commit",
     "buildlog_diff",
+    "buildlog_distill",
+    "buildlog_entry_list",
+    "buildlog_entry_new",
+    "buildlog_experiment_end",
+    "buildlog_experiment_metrics",
+    "buildlog_experiment_report",
+    "buildlog_experiment_start",
+    "buildlog_gauntlet_accept_risk",
+    "buildlog_gauntlet_generate",
+    "buildlog_gauntlet_issues",
+    "buildlog_gauntlet_list_personas",
+    "buildlog_gauntlet_loop",
+    "buildlog_gauntlet_prompt",
+    "buildlog_gauntlet_rules",
+    "buildlog_init",
     "buildlog_learn_from_review",
+    "buildlog_log_mistake",
+    "buildlog_log_reward",
+    "buildlog_overview",
+    "buildlog_promote",
+    "buildlog_reject",
+    "buildlog_rewards",
+    "buildlog_skills",
+    "buildlog_stats",
+    "buildlog_status",
+    "buildlog_update",
 ]

buildlog/mcp/server.py

@@ -5,20 +5,35 @@ from __future__ import annotations
 from mcp.server.fastmcp import FastMCP
 
 from buildlog.mcp.tools import (
+    buildlog_bandit_status,
+    buildlog_commit,
     buildlog_diff,
+    buildlog_distill,
+    buildlog_entry_list,
+    buildlog_entry_new,
     buildlog_experiment_end,
     buildlog_experiment_metrics,
     buildlog_experiment_report,
     buildlog_experiment_start,
     buildlog_gauntlet_accept_risk,
+    buildlog_gauntlet_generate,
     buildlog_gauntlet_issues,
+    buildlog_gauntlet_list_personas,
+    buildlog_gauntlet_loop,
+    buildlog_gauntlet_prompt,
+    buildlog_gauntlet_rules,
+    buildlog_init,
     buildlog_learn_from_review,
     buildlog_log_mistake,
     buildlog_log_reward,
+    buildlog_overview,
     buildlog_promote,
     buildlog_reject,
     buildlog_rewards,
+    buildlog_skills,
+    buildlog_stats,
     buildlog_status,
+    buildlog_update,
 )
 
 mcp = FastMCP("buildlog")
@@ -43,6 +58,31 @@ mcp.tool()(buildlog_experiment_report)
 mcp.tool()(buildlog_gauntlet_issues)
 mcp.tool()(buildlog_gauntlet_accept_risk)
 
+# Bandit tools
+mcp.tool()(buildlog_bandit_status)
+
+# Entry & overview tools
+mcp.tool()(buildlog_gauntlet_rules)
+mcp.tool()(buildlog_overview)
+mcp.tool()(buildlog_entry_new)
+mcp.tool()(buildlog_entry_list)
+
+# P0: Gauntlet loop completion
+mcp.tool()(buildlog_commit)
+mcp.tool()(buildlog_gauntlet_prompt)
+mcp.tool()(buildlog_gauntlet_loop)
+
+# P1: Learning pipeline
+mcp.tool()(buildlog_distill)
+mcp.tool()(buildlog_skills)
+mcp.tool()(buildlog_stats)
+mcp.tool()(buildlog_gauntlet_list_personas)
+
+# P2: Nice-to-have
+mcp.tool()(buildlog_gauntlet_generate)
+mcp.tool()(buildlog_init)
+mcp.tool()(buildlog_update)
+
 
 def main() -> None:
     """Run the MCP server."""