@smilintux/skcapstone 0.1.0 → 0.2.3

package/src/skcapstone/blueprints/registry.py

@@ -0,0 +1,164 @@
+"""
+Blueprint Registry — discovers, validates, and loads team blueprints.
+
+Searches three locations in priority order:
+1. User blueprints:  ~/.skcapstone/blueprints/teams/
+2. Vault blueprints: ~/.skcapstone/vaults/blueprints/teams/  (synced via skref)
+3. Built-in blueprints: shipped with the skcapstone package
+
+This follows the filesystem-context skill pattern: use the filesystem
+as the source of truth, keep it simple, add sophistication later.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Dict, List, Optional
+
+import yaml
+
+from .schema import BlueprintManifest
+
+logger = logging.getLogger(__name__)
+
+# Built-in blueprints ship alongside this module
+_BUILTIN_DIR = Path(__file__).parent / "builtins"
+
+
+class BlueprintRegistry:
+    """Discovers and manages agent team blueprints.
+
+    Args:
+        home: Agent home directory (default ~/.skcapstone).
+    """
+
+    def __init__(self, home: Optional[Path] = None) -> None:
+        self._home = (home or Path("~/.skcapstone")).expanduser()
+        self._cache: Dict[str, BlueprintManifest] = {}
+
+    # ------------------------------------------------------------------
+    # Discovery paths
+    # ------------------------------------------------------------------
+
+    @property
+    def _search_paths(self) -> List[Path]:
+        """Return blueprint directories in priority order."""
+        return [
+            self._home / "blueprints" / "teams",
+            self._home / "vaults" / "blueprints" / "teams",
+            _BUILTIN_DIR,
+        ]
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def scan(self) -> Dict[str, BlueprintManifest]:
+        """Scan all search paths and return discovered blueprints.
+
+        Later paths lose to earlier paths when slugs collide (user
+        overrides take priority over built-ins).
+
+        Returns:
+            Dict mapping slug to validated BlueprintManifest.
+        """
+        found: Dict[str, BlueprintManifest] = {}
+
+        # Reverse so built-ins load first, then get overridden
+        for search_dir in reversed(self._search_paths):
+            if not search_dir.is_dir():
+                continue
+            for yaml_file in sorted(search_dir.glob("*.yaml")):
+                try:
+                    bp = self._load_file(yaml_file)
+                    found[bp.slug] = bp
+                except Exception as exc:
+                    logger.warning("Skipping %s: %s", yaml_file, exc)
+
+            for yml_file in sorted(search_dir.glob("*.yml")):
+                try:
+                    bp = self._load_file(yml_file)
+                    found[bp.slug] = bp
+                except Exception as exc:
+                    logger.warning("Skipping %s: %s", yml_file, exc)
+
+        self._cache = found
+        return found
+
+    def list_blueprints(self) -> List[BlueprintManifest]:
+        """Return all discovered blueprints as a sorted list.
+
+        Returns:
+            List of BlueprintManifest objects sorted by name.
+        """
+        if not self._cache:
+            self.scan()
+        return sorted(self._cache.values(), key=lambda b: b.name)
+
+    def get(self, slug: str) -> Optional[BlueprintManifest]:
+        """Get a specific blueprint by slug.
+
+        Args:
+            slug: The blueprint identifier.
+
+        Returns:
+            BlueprintManifest or None if not found.
+        """
+        if not self._cache:
+            self.scan()
+        return self._cache.get(slug)
+
+    def save_blueprint(
+        self,
+        blueprint: BlueprintManifest,
+        location: str = "user",
+    ) -> Path:
+        """Save a blueprint to the user or vault directory.
+
+        Args:
+            blueprint: The validated blueprint to save.
+            location: 'user' for ~/.skcapstone/blueprints/teams/,
+                      'vault' for ~/.skcapstone/vaults/blueprints/teams/.
+
+        Returns:
+            Path to the written file.
+        """
+        if location == "vault":
+            target_dir = self._home / "vaults" / "blueprints" / "teams"
+        else:
+            target_dir = self._home / "blueprints" / "teams"
+
+        target_dir.mkdir(parents=True, exist_ok=True)
+        target_file = target_dir / f"{blueprint.slug}.yaml"
+
+        data = blueprint.model_dump(mode="json", exclude_none=True)
+        target_file.write_text(
+            yaml.dump(data, default_flow_style=False, sort_keys=False),
+            encoding="utf-8",
+        )
+
+        self._cache[blueprint.slug] = blueprint
+        return target_file
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _load_file(path: Path) -> BlueprintManifest:
+        """Parse and validate a single blueprint YAML file.
+
+        Args:
+            path: Path to the YAML file.
+
+        Returns:
+            Validated BlueprintManifest.
+
+        Raises:
+            ValueError: If the YAML is invalid or fails validation.
+        """
+        raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+        if not isinstance(raw, dict):
+            raise ValueError(f"Expected a YAML mapping, got {type(raw).__name__}")
+        return BlueprintManifest(**raw)

package/src/skcapstone/blueprints/schema.py

@@ -0,0 +1,229 @@
+"""
+Pydantic models for Agent Team Blueprint definitions.
+
+A BlueprintManifest defines a complete deployable team of AI agents,
+including their roles, models, resource requirements, networking,
+memory, and coordination settings. Provider-agnostic by design —
+the same blueprint deploys to local processes, Proxmox LXCs,
+Hetzner, AWS, GCP, or any future provider.
+
+Architecture references:
+- Context isolation per agent (multi-agent-patterns best practice)
+- Tiered model strategy (fast/code/reason/nuance)
+- Memory-systems: file-system -> vector -> graph progression
+- Hosted-agents: pre-built images, warm pools, snapshot/restore
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field, field_validator
+
+
+# ---------------------------------------------------------------------------
+# Enums
+# ---------------------------------------------------------------------------
+
+class ModelTier(str, Enum):
+    """Model selection tiers aligned with agent framework best practices."""
+
+    FAST = "fast"
+    CODE = "code"
+    REASON = "reason"
+    NUANCE = "nuance"
+    LOCAL = "local"
+    CUSTOM = "custom"
+
+
+class ProviderType(str, Enum):
+    """Infrastructure providers for agent deployment."""
+
+    LOCAL = "local"
+    PROXMOX = "proxmox"
+    HETZNER = "hetzner"
+    AWS = "aws"
+    GCP = "gcp"
+    DOCKER = "docker"
+
+
+class VMType(str, Enum):
+    """VM/container type for cloud/proxmox deployments."""
+
+    LXC = "lxc"
+    VM = "vm"
+    CONTAINER = "container"
+    PROCESS = "process"
+
+
+class AgentRole(str, Enum):
+    """Standard agent roles within a team."""
+
+    MANAGER = "manager"
+    WORKER = "worker"
+    RESEARCHER = "researcher"
+    CODER = "coder"
+    REVIEWER = "reviewer"
+    DOCUMENTARIAN = "documentarian"
+    SECURITY = "security"
+    OPS = "ops"
+    CUSTOM = "custom"
+
+
+# ---------------------------------------------------------------------------
+# Sub-models
+# ---------------------------------------------------------------------------
+
+class ResourceSpec(BaseModel):
+    """Compute resources allocated to an agent."""
+
+    memory: str = Field(default="2g", description="RAM allocation (e.g. '2g', '512m')")
+    cores: int = Field(default=1, ge=1, le=128, description="CPU cores")
+    disk: str = Field(default="10g", description="Disk allocation")
+    gpu: Optional[str] = Field(default=None, description="GPU type if needed")
+
+
+class AgentSpec(BaseModel):
+    """Specification for a single agent within a team blueprint.
+
+    Each agent gets its own context window (context isolation principle),
+    its own model tier, its own soul blueprint, and a defined skill set.
+    """
+
+    role: AgentRole = Field(default=AgentRole.WORKER, description="Functional role")
+    model: ModelTier = Field(default=ModelTier.FAST, description="Model tier")
+    model_name: Optional[str] = Field(
+        default=None,
+        description="Specific model override (e.g. 'kimi-k2.5', 'minimax-m2.1')",
+    )
+    vm_type: VMType = Field(default=VMType.PROCESS, description="Execution environment")
+    resources: ResourceSpec = Field(default_factory=ResourceSpec)
+    soul_blueprint: Optional[str] = Field(
+        default=None,
+        description="Path to soul blueprint YAML (e.g. 'souls/sentinel.yaml')",
+    )
+    skills: List[str] = Field(default_factory=list, description="Skill names")
+    depends_on: List[str] = Field(
+        default_factory=list,
+        description="Other agents this one depends on being ready first",
+    )
+    env: Dict[str, str] = Field(
+        default_factory=dict,
+        description="Extra environment variables for this agent",
+    )
+    description: Optional[str] = Field(default=None, description="What this agent does")
+    count: int = Field(
+        default=1, ge=1, le=50,
+        description="Number of instances of this agent to spawn",
+    )
+
+
+class NetworkConfig(BaseModel):
+    """Networking configuration for the team."""
+
+    mesh_vpn: str = Field(default="tailscale", description="VPN mesh provider")
+    discovery: str = Field(
+        default="skref_registry",
+        description="How agents discover each other",
+    )
+
+
+class StorageConfig(BaseModel):
+    """Storage and memory configuration for the team."""
+
+    skref_vault: Optional[str] = Field(
+        default=None,
+        description="Shared vault name for the team",
+    )
+    # Supported backends: "filesystem" (default, no deps) and "skvector" (via skmemory).
+    # "mem0" and "zep" are not yet implemented — no adapter classes exist.
+    memory_backend: str = Field(
+        default="filesystem",
+        description="Memory backend: filesystem, skvector",
+    )
+    memory_sync: bool = Field(
+        default=True,
+        description="Auto-sync agent memories to shared storage",
+    )
+
+
+class CoordinationConfig(BaseModel):
+    """How the team coordinates internally."""
+
+    queen: Optional[str] = Field(
+        default=None,
+        description="Managing agent (e.g. 'lumina')",
+    )
+    pattern: str = Field(
+        default="supervisor",
+        description="Architecture: supervisor, peer-to-peer, hierarchical",
+    )
+    heartbeat: str = Field(default="30m", description="Health check interval")
+    escalation: Optional[str] = Field(
+        default=None,
+        description="Who to escalate critical issues to",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Top-level Blueprint
+# ---------------------------------------------------------------------------
+
+class BlueprintManifest(BaseModel):
+    """Complete definition of a deployable agent team.
+
+    This is the YAML schema that users select from the blueprint store.
+    It contains everything needed to spin up a coordinated team of AI
+    agents on any supported infrastructure provider.
+    """
+
+    name: str = Field(description="Human-readable team name")
+    slug: str = Field(description="URL/filesystem-safe identifier")
+    version: str = Field(default="1.0.0")
+    description: str = Field(description="What this team does")
+    icon: str = Field(default="🤖", description="Display emoji")
+    author: str = Field(default="smilinTux")
+
+    agents: Dict[str, AgentSpec] = Field(
+        description="Named agents in this team (key = agent name)",
+    )
+
+    default_provider: ProviderType = Field(
+        default=ProviderType.LOCAL,
+        description="Default infrastructure provider",
+    )
+    network: NetworkConfig = Field(default_factory=NetworkConfig)
+    storage: StorageConfig = Field(default_factory=StorageConfig)
+    coordination: CoordinationConfig = Field(default_factory=CoordinationConfig)
+
+    tags: List[str] = Field(default_factory=list)
+    estimated_cost: Optional[str] = Field(
+        default=None,
+        description="Estimated monthly cost (e.g. '$12/mo compute')",
+    )
+
+    @field_validator("slug")
+    @classmethod
+    def slug_must_be_clean(cls, v: str) -> str:
+        """Ensure slug is filesystem/URL safe."""
+        import re
+        if not re.match(r"^[a-z0-9][a-z0-9\-]*[a-z0-9]$", v):
+            raise ValueError(
+                f"slug must be lowercase alphanumeric with hyphens: got '{v}'"
+            )
+        return v
+
+    @property
+    def agent_count(self) -> int:
+        """Total number of agent instances in this blueprint."""
+        return sum(spec.count for spec in self.agents.values())
+
+    @property
+    def model_summary(self) -> str:
+        """Comma-separated list of model tiers used."""
+        tiers = sorted({
+            spec.model_name or spec.model.value
+            for spec in self.agents.values()
+        })
+        return ", ".join(tiers)

package/src/skcapstone/changelog.py

@@ -0,0 +1,180 @@
+"""
+Changelog Generator — auto-document the Kingdom's progress.
+
+Reads the coordination board's completed tasks and generates
+a structured CHANGELOG.md grouped by date and category. Every
+completed task becomes a line item in the project's history.
+
+The board IS the changelog. No separate tracking needed.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections import defaultdict
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+from .coordination import Board, TaskStatus
+
+
+TAG_CATEGORIES = {
+    "feature": ["skcapstone", "skchat", "skcomm", "skmemory", "capauth", "cloud9", "skworld"],
+    "security": ["security", "encryption", "capauth", "integrity", "quantum-resistant", "pgp"],
+    "infrastructure": ["ci", "docker", "systemd", "daemon", "syncthing", "pypi", "packaging"],
+    "documentation": ["documentation", "docs", "readme", "quickstart", "api"],
+    "testing": ["testing", "integration", "e2e", "pytest"],
+    "ux": ["cli", "repl", "dashboard", "interactive", "rich"],
+    "p2p": ["p2p", "nostr", "mesh", "discovery", "transport"],
+    "emotional": ["cloud9", "soul", "trust", "feb", "emotional", "seeds", "anchor"],
+}
+
+
+def _categorize(tags: list[str]) -> str:
+    """Determine the changelog category from task tags.
+
+    Args:
+        tags: Task tags list.
+
+    Returns:
+        Category string (e.g., 'feature', 'security', 'infrastructure').
+    """
+    tag_set = set(t.lower() for t in tags)
+    best_category = "other"
+    best_score = 0
+
+    for category, keywords in TAG_CATEGORIES.items():
+        score = len(tag_set.intersection(keywords))
+        if score > best_score:
+            best_score = score
+            best_category = category
+
+    return best_category
+
+
+def _parse_date(iso_str: str) -> str:
+    """Extract YYYY-MM-DD from an ISO timestamp.
+
+    Args:
+        iso_str: ISO 8601 datetime string.
+
+    Returns:
+        Date string like '2026-02-24'.
+    """
+    try:
+        match = re.match(r"(\d{4}-\d{2}-\d{2})", iso_str)
+        if match:
+            return match.group(1)
+    except (TypeError, ValueError):
+        pass
+    return datetime.now(timezone.utc).strftime("%Y-%m-%d")
+
+
+def generate_changelog(
+    home: Path,
+    title: str = "SKCapstone Changelog",
+    include_agents: bool = True,
+) -> str:
+    """Generate a CHANGELOG.md from completed board tasks.
+
+    Groups tasks by date and category, with agent attribution.
+
+    Args:
+        home: Path to ~/.skcapstone.
+        title: Changelog title.
+        include_agents: Whether to show who completed each task.
+
+    Returns:
+        Markdown string for the changelog.
+    """
+    board = Board(home)
+    views = board.get_task_views()
+    agents = board.load_agents()
+
+    completed = [v for v in views if v.status == TaskStatus.DONE]
+
+    completed_by_agent: dict[str, list[str]] = defaultdict(list)
+    for a in agents:
+        for tid in a.completed_tasks:
+            completed_by_agent[tid].append(a.agent)
+
+    by_date: dict[str, list[dict]] = defaultdict(list)
+    for v in completed:
+        t = v.task
+        date = _parse_date(t.created_at)
+        category = _categorize(t.tags)
+        who = completed_by_agent.get(t.id, [v.claimed_by] if v.claimed_by else ["unknown"])
+
+        by_date[date].append({
+            "id": t.id,
+            "title": t.title,
+            "category": category,
+            "tags": t.tags,
+            "agents": who,
+            "priority": t.priority.value,
+        })
+
+    lines = [
+        f"# {title}",
+        "",
+        f"*Auto-generated from the coordination board — {datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M UTC')}*",
+        "",
+        f"**Total completed: {len(completed)}** across {len(set(a.agent for a in agents))} agents",
+        "",
+    ]
+
+    category_icons = {
+        "feature": "NEW",
+        "security": "SEC",
+        "infrastructure": "OPS",
+        "documentation": "DOC",
+        "testing": "TST",
+        "ux": "UX",
+        "p2p": "P2P",
+        "emotional": "SOUL",
+        "other": "---",
+    }
+
+    for date in sorted(by_date.keys(), reverse=True):
+        tasks = by_date[date]
+        lines.append(f"## {date}")
+        lines.append("")
+
+        by_cat: dict[str, list[dict]] = defaultdict(list)
+        for task in tasks:
+            by_cat[task["category"]].append(task)
+
+        for cat in ["feature", "security", "p2p", "emotional", "ux", "infrastructure", "testing", "documentation", "other"]:
+            if cat not in by_cat:
+                continue
+            icon = category_icons.get(cat, "---")
+            lines.append(f"### [{icon}] {cat.title()}")
+            lines.append("")
+            for task in by_cat[cat]:
+                agent_str = f" (@{', @'.join(task['agents'])})" if include_agents and task["agents"] else ""
+                lines.append(f"- **{task['title']}**{agent_str}")
+            lines.append("")
+
+    lines.append("---")
+    lines.append("")
+    lines.append("*Built by the Pengu Nation — staycuriousANDkeepsmilin*")
+
+    return "\n".join(lines)
+
+
+def write_changelog(home: Path, output: Optional[Path] = None) -> Path:
+    """Generate and write CHANGELOG.md.
+
+    Args:
+        home: Path to ~/.skcapstone.
+        output: Output file path. Defaults to project root CHANGELOG.md.
+
+    Returns:
+        Path to the written file.
+    """
+    content = generate_changelog(home)
+    out_path = output or Path.cwd() / "CHANGELOG.md"
+    out_path.write_text(content, encoding="utf-8")
+    return out_path