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

buildlog/embeddings.py

@@ -46,20 +46,112 @@ Embedding = list[float]
 BackendName = Literal["token", "sentence-transformers", "openai"]
 
 # Stop words to filter in token-based approach
-STOP_WORDS: Final[frozenset[str]] = frozenset({
-    "a", "an", "the", "is", "are", "was", "were", "be", "been", "being",
-    "have", "has", "had", "do", "does", "did", "will", "would", "could",
-    "should", "may", "might", "must", "shall", "can", "need", "dare",
-    "ought", "used", "to", "of", "in", "for", "on", "with", "at", "by",
-    "from", "as", "into", "through", "during", "before", "after", "above",
-    "below", "between", "under", "again", "further", "then", "once",
-    "here", "there", "when", "where", "why", "how", "all", "each", "few",
-    "more", "most", "other", "some", "such", "no", "nor", "not", "only",
-    "own", "same", "so", "than", "too", "very", "just", "also", "now",
-    "always", "never", "often", "still", "already", "ever",
-    "it", "its", "this", "that", "these", "those", "i", "you", "he",
-    "she", "we", "they", "what", "which", "who", "whom", "whose",
-})
+STOP_WORDS: Final[frozenset[str]] = frozenset(
+    {
+        "a",
+        "an",
+        "the",
+        "is",
+        "are",
+        "was",
+        "were",
+        "be",
+        "been",
+        "being",
+        "have",
+        "has",
+        "had",
+        "do",
+        "does",
+        "did",
+        "will",
+        "would",
+        "could",
+        "should",
+        "may",
+        "might",
+        "must",
+        "shall",
+        "can",
+        "need",
+        "dare",
+        "ought",
+        "used",
+        "to",
+        "of",
+        "in",
+        "for",
+        "on",
+        "with",
+        "at",
+        "by",
+        "from",
+        "as",
+        "into",
+        "through",
+        "during",
+        "before",
+        "after",
+        "above",
+        "below",
+        "between",
+        "under",
+        "again",
+        "further",
+        "then",
+        "once",
+        "here",
+        "there",
+        "when",
+        "where",
+        "why",
+        "how",
+        "all",
+        "each",
+        "few",
+        "more",
+        "most",
+        "other",
+        "some",
+        "such",
+        "no",
+        "nor",
+        "not",
+        "only",
+        "own",
+        "same",
+        "so",
+        "than",
+        "too",
+        "very",
+        "just",
+        "also",
+        "now",
+        "always",
+        "never",
+        "often",
+        "still",
+        "already",
+        "ever",
+        "it",
+        "its",
+        "this",
+        "that",
+        "these",
+        "those",
+        "i",
+        "you",
+        "he",
+        "she",
+        "we",
+        "they",
+        "what",
+        "which",
+        "who",
+        "whom",
+        "whose",
+    }
+)
 
 # Common synonyms for normalization
 SYNONYMS: Final[dict[str, str]] = {
@@ -249,7 +341,7 @@ class SentenceTransformerBackend(EmbeddingBackend):
                     "Install with: pip install buildlog[embeddings]"
                 ) from e
 
-            self._model = SentenceTransformer(self._model_name)
+            self._model = SentenceTransformer(self._model_name)  # type: ignore[assignment]
 
         return self._model
 
@@ -298,7 +390,7 @@ class OpenAIBackend(EmbeddingBackend):
                     "Install with: pip install openai"
                 ) from e
 
-            self._client = openai.OpenAI()
+            self._client = openai.OpenAI()  # type: ignore[assignment]
 
         return self._client
 

buildlog/mcp/tools.py

@@ -39,17 +39,17 @@ def buildlog_status(
 
 def buildlog_promote(
     skill_ids: list[str],
-    target: Literal["claude_md", "settings_json"] = "claude_md",
+    target: Literal["claude_md", "settings_json", "skill"] = "claude_md",
     buildlog_dir: str = "buildlog",
 ) -> dict:
     """Promote skills to your agent's rules.
 
-    Writes selected skills to CLAUDE.md or .claude/settings.json
-    so your AI agent will follow these patterns.
+    Writes selected skills to CLAUDE.md, .claude/settings.json, or
+    .claude/skills/buildlog-learned/SKILL.md (Anthropic Agent Skills format).
 
     Args:
         skill_ids: List of skill IDs to promote (e.g., ["arch-b0fcb62a1e"])
-        target: Where to write rules ("claude_md" or "settings_json")
+        target: Where to write rules ("claude_md", "settings_json", or "skill")
         buildlog_dir: Path to buildlog directory
 
     Returns:

buildlog/render/__init__.py

@@ -3,39 +3,62 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Literal
+from typing import TYPE_CHECKING, Literal
 
 from buildlog.render.base import RenderTarget
 from buildlog.render.claude_md import ClaudeMdRenderer
 from buildlog.render.settings_json import SettingsJsonRenderer
+from buildlog.render.skill import SkillRenderer
+
+if TYPE_CHECKING:
+    from typing import Any
 
 __all__ = [
     "RenderTarget",
     "ClaudeMdRenderer",
     "SettingsJsonRenderer",
+    "SkillRenderer",
     "get_renderer",
+    "RENDERERS",
 ]
 
+# Registry of available renderers
+# Using RenderTarget Protocol allows easy extension without modifying types
+RENDERERS: dict[str, type[RenderTarget]] = {
+    "claude_md": ClaudeMdRenderer,
+    "settings_json": SettingsJsonRenderer,
+    "skill": SkillRenderer,
+}
+
 
 def get_renderer(
-    target: Literal["claude_md", "settings_json"],
+    target: Literal["claude_md", "settings_json", "skill"],
     path: Path | None = None,
-) -> ClaudeMdRenderer | SettingsJsonRenderer:
+    **kwargs: Any,
+) -> RenderTarget:
     """Get renderer for target.
 
     Args:
-        target: Target format - "claude_md" or "settings_json".
+        target: Target format - "claude_md", "settings_json", or "skill".
         path: Optional custom path for the target file.
+        **kwargs: Additional arguments passed to the renderer constructor.
+            Common kwargs (accepted by all renderers):
+                - tracking_path: Path to promoted.json for tracking promoted IDs.
+            Skill-specific kwargs:
+                - skill_name: Name of the skill directory (default: "buildlog-learned").
+                  Must not contain path separators.
 
     Returns:
-        Renderer instance.
+        Renderer instance implementing RenderTarget protocol.
 
     Raises:
         ValueError: If target is not recognized.
     """
-    if target == "claude_md":
-        return ClaudeMdRenderer(path=path)
-    elif target == "settings_json":
-        return SettingsJsonRenderer(path=path)
-    else:
-        raise ValueError(f"Unknown render target: {target}. Must be 'claude_md' or 'settings_json'")
+    if target not in RENDERERS:
+        available = ", ".join(f"'{k}'" for k in RENDERERS.keys())
+        raise ValueError(
+            f"Unknown render target: '{target}'. Must be one of: {available}"
+        )
+
+    renderer_cls = RENDERERS[target]
+    return renderer_cls(path=path, **kwargs)  # type: ignore[call-arg]

buildlog/render/claude_md.py

@@ -2,11 +2,11 @@
 
 from __future__ import annotations
 
-import json
 from datetime import datetime
 from pathlib import Path
 from typing import TYPE_CHECKING
 
+from buildlog.render.tracking import track_promoted
 from buildlog.skills import _to_imperative
 
 if TYPE_CHECKING:
@@ -79,28 +79,7 @@ class ClaudeMdRenderer:
         else:
             self.path.write_text(content)
 
-        # Track promoted skill IDs
-        self._track_promoted(skills)
+        # Track promoted skill IDs using shared utility
+        track_promoted(skills, self.tracking_path)
 
         return f"Appended {len(skills)} rules to {self.path}"
-
-    def _track_promoted(self, skills: list[Skill]) -> None:
-        """Track which skills have been promoted."""
-        self.tracking_path.parent.mkdir(parents=True, exist_ok=True)
-
-        # Load existing tracking data (handle corrupt JSON)
-        tracking = {"skill_ids": [], "promoted_at": {}}
-        if self.tracking_path.exists():
-            try:
-                tracking = json.loads(self.tracking_path.read_text())
-            except json.JSONDecodeError:
-                pass  # Start fresh if corrupted
-
-        # Add new skill IDs
-        now = datetime.now().isoformat()
-        for skill in skills:
-            if skill.id not in tracking["skill_ids"]:
-                tracking["skill_ids"].append(skill.id)
-                tracking["promoted_at"][skill.id] = now
-
-        self.tracking_path.write_text(json.dumps(tracking, indent=2))

buildlog/render/settings_json.py

@@ -7,6 +7,7 @@ from datetime import datetime
 from pathlib import Path
 from typing import TYPE_CHECKING
 
+from buildlog.render.tracking import track_promoted
 from buildlog.skills import _to_imperative
 
 if TYPE_CHECKING:
@@ -69,28 +70,7 @@ class SettingsJsonRenderer:
         # Write back
         self.path.write_text(json.dumps(settings, indent=2))
 
-        # Track promoted skill IDs
-        self._track_promoted(skills)
+        # Track promoted skill IDs using shared utility
+        track_promoted(skills, self.tracking_path)
 
         return f"Added {added} rules to {self.path} ({len(skills) - added} duplicates skipped)"
-
-    def _track_promoted(self, skills: list[Skill]) -> None:
-        """Track which skills have been promoted."""
-        self.tracking_path.parent.mkdir(parents=True, exist_ok=True)
-
-        # Load existing tracking data (handle corrupt JSON)
-        tracking = {"skill_ids": [], "promoted_at": {}}
-        if self.tracking_path.exists():
-            try:
-                tracking = json.loads(self.tracking_path.read_text())
-            except json.JSONDecodeError:
-                pass  # Start fresh if corrupted
-
-        # Add new skill IDs
-        now = datetime.now().isoformat()
-        for skill in skills:
-            if skill.id not in tracking["skill_ids"]:
-                tracking["skill_ids"].append(skill.id)
-                tracking["promoted_at"][skill.id] = now
-
-        self.tracking_path.write_text(json.dumps(tracking, indent=2))

buildlog/render/skill.py

@@ -0,0 +1,175 @@
+"""Render skills to Anthropic Agent Skills format.
+
+Creates .claude/skills/buildlog-learned/SKILL.md that can be loaded
+on-demand by Claude Code and other Anthropic tools.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from buildlog.render.tracking import track_promoted
+
+if TYPE_CHECKING:
+    from buildlog.skills import Skill
+
+
+class SkillRenderer:
+    """Creates .claude/skills/buildlog-learned/SKILL.md
+
+    This renderer produces Anthropic Agent Skills format, which allows
+    for on-demand loading of project-specific patterns by Claude.
+    """
+
+    def __init__(
+        self,
+        path: Path | None = None,
+        tracking_path: Path | None = None,
+        skill_name: str = "buildlog-learned",
+    ):
+        """Initialize renderer.
+
+        Args:
+            path: Path to SKILL.md file. Defaults to .claude/skills/{skill_name}/SKILL.md.
+            tracking_path: Path to promoted.json tracking file.
+                Defaults to .buildlog/promoted.json.
+            skill_name: Name of the skill directory. Defaults to "buildlog-learned".
+                Must not contain path separators or parent references.
+
+        Raises:
+            ValueError: If skill_name contains path traversal characters.
+        """
+        # Security: Validate skill_name to prevent path traversal
+        if "/" in skill_name or "\\" in skill_name or ".." in skill_name:
+            raise ValueError(
+                f"Invalid skill_name: {skill_name!r}. "
+                "Must not contain path separators or '..'."
+            )
+        self.skill_name = skill_name
+        self.path = path or Path(f".claude/skills/{skill_name}/SKILL.md")
+        self.tracking_path = tracking_path or Path(".buildlog/promoted.json")
+
+    def render(self, skills: list[Skill]) -> str:
+        """Render skills to SKILL.md format.
+
+        Args:
+            skills: List of skills to render.
+
+        Returns:
+            Confirmation message describing what was written.
+        """
+        if not skills:
+            return "No skills to promote"
+
+        # Group by confidence, then category
+        by_confidence: dict[str, dict[str, list[Skill]]] = {
+            "high": {},
+            "medium": {},
+            "low": {},
+        }
+        for skill in skills:
+            conf = skill.confidence
+            cat = skill.category
+            by_confidence[conf].setdefault(cat, []).append(skill)
+
+        # Build SKILL.md content
+        categories = sorted(set(s.category for s in skills))
+        category_display = ", ".join(self._category_title(c) for c in categories)
+
+        lines = [
+            "---",
+            f"name: {self.skill_name}",
+            f"description: Project-specific patterns learned from development history. "
+            f"Use when writing code, making architectural decisions, reviewing PRs, "
+            f"or ensuring consistency. Contains {len(skills)} rules across "
+            f"{category_display}.",
+            "---",
+            "",
+            "# Learned Patterns",
+            "",
+            f"*{len(skills)} rules extracted from buildlog entries on "
+            f"{datetime.now().strftime('%Y-%m-%d')}*",
+            "",
+        ]
+
+        # High confidence = Must Follow
+        if by_confidence["high"]:
+            lines.extend(
+                self._render_confidence_section(
+                    "Must Follow (High Confidence)",
+                    "These patterns have been reinforced multiple times.",
+                    by_confidence["high"],
+                )
+            )
+
+        # Medium confidence = Should Consider
+        if by_confidence["medium"]:
+            lines.extend(
+                self._render_confidence_section(
+                    "Should Consider (Medium Confidence)",
+                    "These patterns appear frequently but may have exceptions.",
+                    by_confidence["medium"],
+                )
+            )
+
+        # Low confidence = Worth Knowing
+        if by_confidence["low"]:
+            lines.extend(
+                self._render_confidence_section(
+                    "Worth Knowing (Low Confidence)",
+                    "Emerging patterns worth being aware of.",
+                    by_confidence["low"],
+                )
+            )
+
+        content = "\n".join(lines)
+
+        # Write file
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(content)
+
+        # Track promoted using shared utility
+        track_promoted(skills, self.tracking_path)
+
+        return f"Created skill at {self.path}"
+
+    def _category_title(self, category: str) -> str:
+        """Convert category slug to display title."""
+        titles = {
+            "architectural": "Architectural",
+            "workflow": "Workflow",
+            "tool_usage": "Tool Usage",
+            "domain_knowledge": "Domain Knowledge",
+        }
+        return titles.get(category, category.replace("_", " ").title())
+
+    def _render_confidence_section(
+        self,
+        title: str,
+        description: str,
+        by_category: dict[str, list[Skill]],
+    ) -> list[str]:
+        """Render a confidence-level section.
+
+        Args:
+            title: Section title (e.g., "Must Follow (High Confidence)").
+            description: Description of what this confidence level means.
+            by_category: Skills grouped by category.
+
+        Returns:
+            List of markdown lines for this section.
+        """
+        lines = [f"## {title}", "", description, ""]
+
+        for category, cat_skills in sorted(by_category.items()):
+            cat_title = self._category_title(category)
+            lines.append(f"### {cat_title}")
+            lines.append("")
+            for skill in cat_skills:
+                # Don't add confidence prefix - section already indicates confidence
+                lines.append(f"- {skill.rule}")
+            lines.append("")
+
+        return lines

buildlog/render/tracking.py

@@ -0,0 +1,43 @@
+"""Shared tracking utilities for render adapters."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from buildlog.skills import Skill
+
+__all__ = ["track_promoted"]
+
+
+def track_promoted(skills: list[Skill], tracking_path: Path) -> None:
+    """Track which skills have been promoted.
+
+    Writes skill IDs and promotion timestamps to a JSON file.
+    Handles corrupt JSON gracefully by starting fresh.
+
+    Args:
+        skills: Skills that were promoted.
+        tracking_path: Path to the tracking JSON file.
+    """
+    tracking_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Load existing tracking data (handle corrupt JSON)
+    tracking: dict = {"skill_ids": [], "promoted_at": {}}
+    if tracking_path.exists():
+        try:
+            tracking = json.loads(tracking_path.read_text())
+        except json.JSONDecodeError:
+            pass  # Start fresh if corrupted
+
+    # Add new skill IDs
+    now = datetime.now().isoformat()
+    for skill in skills:
+        if skill.id not in tracking["skill_ids"]:
+            tracking["skill_ids"].append(skill.id)
+            tracking["promoted_at"][skill.id] = now
+
+    tracking_path.write_text(json.dumps(tracking, indent=2))