ref-agents 1.0.0__py3-none-any.whl

ref_agents/license_client.py

@@ -0,0 +1,247 @@
+"""REF license client — validates API keys against ref-license backend.
+
+Handles:
+- Key validation via POST /validate (with in-memory + file cache)
+- Paid asset fetching: GET /prompt/:name, /rule/:path, /config/:path
+- Graceful degrade: network error → cached status → free tier (never hard-fails)
+
+Environment:
+    REF_API_KEY          Single API key (sk_ref_...)
+    REF_LICENSE_URL      Override default server URL (optional)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+# ── Constants ────────────────────────────────────────────────────────────────
+
+REF_LICENSE_URL: str = os.environ.get(
+    "REF_LICENSE_URL", "https://ref-license.workers.dev"
+).rstrip("/")
+
+CACHE_TTL_SECONDS: int = 14_400  # 4 hrs — revalidate on next boot after this
+OFFLINE_GRACE_SECONDS: int = (
+    86_400  # 24 hrs — serve cached status if server unreachable
+)
+REQUEST_TIMEOUT_SECONDS: int = 5
+
+_CACHE_FILE = Path.home() / ".ref_cache" / "license.json"
+
+Plan = Literal["free", "paid"]
+
+
+# ── Data classes ─────────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class LicenseStatus:
+    """Result of a license validation check."""
+
+    valid: bool
+    plan: Plan
+    reason: str = ""
+
+    @property
+    def is_paid(self) -> bool:
+        """Return True if the active plan is paid."""
+        return self.valid and self.plan == "paid"
+
+
+_FREE = LicenseStatus(valid=False, plan="free", reason="no_key")
+_FREE_DEGRADED = LicenseStatus(valid=False, plan="free", reason="server_unreachable")
+
+
+# ── In-process cache ─────────────────────────────────────────────────────────
+
+_mem_status: LicenseStatus | None = None
+_mem_fetched_at: float = 0.0
+
+
+def _load_file_cache() -> tuple[LicenseStatus, float] | None:
+    """Read license status from disk cache.
+
+    Returns:
+        (status, fetched_at) tuple, or None if cache missing/corrupt.
+    """
+    try:
+        if not _CACHE_FILE.exists():
+            return None
+        data = json.loads(_CACHE_FILE.read_text())
+        status = LicenseStatus(
+            valid=bool(data["valid"]),
+            plan=data["plan"],
+            reason=data.get("reason", ""),
+        )
+        return status, float(data["fetched_at"])
+    except (KeyError, json.JSONDecodeError, OSError):
+        return None
+
+
+def _write_file_cache(status: LicenseStatus) -> None:
+    """Persist license status to disk for offline-grace support."""
+    try:
+        _CACHE_FILE.parent.mkdir(parents=True, exist_ok=True)
+        _CACHE_FILE.write_text(
+            json.dumps(
+                {
+                    "valid": status.valid,
+                    "plan": status.plan,
+                    "reason": status.reason,
+                    "fetched_at": time.time(),
+                }
+            )
+        )
+    except OSError as e:
+        logger.warning("license_cache_write_failed", error=str(e))
+
+
+# ── Network validation ────────────────────────────────────────────────────────
+
+
+def _fetch_from_server(api_key: str) -> LicenseStatus | None:
+    """Call POST /validate. Returns None on any network/parse error.
+
+    Args:
+        api_key: The REF_API_KEY value.
+
+    Returns:
+        LicenseStatus on success, None on failure.
+    """
+    url = f"{REF_LICENSE_URL}/validate"
+    payload = json.dumps({"key": api_key}).encode()
+    req = urllib.request.Request(
+        url,
+        data=payload,
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {api_key}",
+        },
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=REQUEST_TIMEOUT_SECONDS) as resp:
+            body = json.loads(resp.read())
+            valid = bool(body.get("valid", False))
+            plan: Plan = "paid" if body.get("plan") == "paid" else "free"
+            reason: str = body.get("reason", "")
+            return LicenseStatus(valid=valid, plan=plan, reason=reason)
+    except urllib.error.HTTPError as e:
+        logger.warning("license_validate_http_error", status=e.code)
+        return None
+    except (urllib.error.URLError, TimeoutError, json.JSONDecodeError, OSError) as e:
+        logger.warning("license_validate_network_error", error=str(e))
+        return None
+
+
+# ── Public API ────────────────────────────────────────────────────────────────
+
+
+def get_status() -> LicenseStatus:
+    """Return current license status.
+
+    Resolution order:
+    1. In-memory cache (TTL=4hrs)
+    2. Network validate → update both caches
+    3. File cache within offline grace period (24hrs)
+    4. Free tier (never hard-fails)
+
+    Returns:
+        LicenseStatus with valid/plan fields.
+    """
+    global _mem_status, _mem_fetched_at
+
+    api_key = os.environ.get("REF_API_KEY", "").strip()
+    if not api_key:
+        return _FREE
+
+    now = time.time()
+
+    # 1. In-memory cache still fresh
+    if _mem_status is not None and (now - _mem_fetched_at) < CACHE_TTL_SECONDS:
+        return _mem_status
+
+    # 2. Fetch from server
+    fetched = _fetch_from_server(api_key)
+    if fetched is not None:
+        _mem_status = fetched
+        _mem_fetched_at = now
+        _write_file_cache(fetched)
+        logger.info("license_validated", plan=fetched.plan, valid=fetched.valid)
+        return fetched
+
+    # 3. File cache within offline grace
+    cached = _load_file_cache()
+    if cached is not None:
+        status, fetched_at = cached
+        if (now - fetched_at) < OFFLINE_GRACE_SECONDS:
+            logger.warning(
+                "license_using_cached_offline", age_hours=(now - fetched_at) / 3600
+            )
+            _mem_status = status
+            _mem_fetched_at = now  # don't hammer server on every call
+            return status
+
+    # 4. Degrade to free — never hard-fail
+    logger.warning("license_degraded_to_free", reason="no_valid_cache")
+    return _FREE_DEGRADED
+
+
+def fetch_asset(
+    asset_type: Literal["prompt", "rule", "config"], path: str
+) -> str | None:
+    """Fetch a paid asset from the license server.
+
+    Args:
+        asset_type: One of "prompt", "rule", "config".
+        path: Asset path (e.g. "developer", "architecture/system_design", "languages/python").
+
+    Returns:
+        Asset text content, or None on error/not found.
+    """
+    api_key = os.environ.get("REF_API_KEY", "").strip()
+    if not api_key:
+        return None
+
+    url = f"{REF_LICENSE_URL}/{asset_type}/{path}"
+    req = urllib.request.Request(
+        url,
+        headers={"Authorization": f"Bearer {api_key}"},
+        method="GET",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=REQUEST_TIMEOUT_SECONDS) as resp:
+            return resp.read().decode("utf-8")
+    except (urllib.error.URLError, urllib.error.HTTPError, TimeoutError, OSError) as e:
+        logger.warning(
+            "asset_fetch_failed", asset_type=asset_type, path=path, error=str(e)
+        )
+        return None
+
+
+def upgrade_message(feature: str = "agent prompts") -> str:
+    """Return a clear upgrade prompt for free-tier users.
+
+    Args:
+        feature: Name of the gated feature.
+
+    Returns:
+        Human-readable upgrade message.
+    """
+    return (
+        f"⚠️ **REF Pro required** — {feature} require an active REF subscription.\n\n"
+        "Subscribe at **https://ref.dev** then set:\n"
+        "```\nexport REF_API_KEY=sk_ref_...\n```\n"
+        "Free tier: all scanners (`scan`, `log`, `workflow`, `validate`) remain available."
+    )

ref_agents/models/__init__.py

@@ -0,0 +1,22 @@
+"""REF-Agents data models.
+
+Provides structured data models for requirements, INVEST scoring, Gherkin,
+hierarchy, and version management.
+"""
+
+from ref_agents.models.gherkin import GherkinScenario, GherkinStep
+from ref_agents.models.hierarchy import Epic, Feature, Story
+from ref_agents.models.invest import INVESTScores, INVESTPrinciple
+from ref_agents.models.version import RequirementVersion, VersionStatus
+
+__all__ = [
+    "GherkinStep",
+    "GherkinScenario",
+    "INVESTPrinciple",
+    "INVESTScores",
+    "Epic",
+    "Feature",
+    "Story",
+    "RequirementVersion",
+    "VersionStatus",
+]

ref_agents/models/gherkin.py

@@ -0,0 +1,45 @@
+"""Gherkin/BDD format models for structured acceptance criteria."""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class GherkinStep(BaseModel):
+    """Single Gherkin step (Given/When/Then/And/But)."""
+
+    keyword: Literal["Given", "When", "Then", "And", "But"] = Field(
+        description="Gherkin keyword"
+    )
+    text: str = Field(description="Step text content")
+
+    def to_markdown(self) -> str:
+        """Convert step to markdown format."""
+        return f"**{self.keyword}** {self.text}"
+
+    def to_gherkin(self) -> str:
+        """Convert step to Gherkin text format."""
+        return f"{self.keyword} {self.text}"
+
+
+class GherkinScenario(BaseModel):
+    """Gherkin scenario with multiple steps."""
+
+    scenario: str = Field(description="Scenario title/description")
+    steps: list[GherkinStep] = Field(
+        default_factory=list, description="Ordered list of Gherkin steps"
+    )
+
+    def to_markdown(self) -> str:
+        """Convert scenario to markdown format."""
+        lines = [f"### {self.scenario}", ""]
+        for step in self.steps:
+            lines.append(step.to_markdown())
+        return "\n".join(lines)
+
+    def to_gherkin(self) -> str:
+        """Convert scenario to Gherkin text format."""
+        lines = [f"Scenario: {self.scenario}", ""]
+        for step in self.steps:
+            lines.append(step.to_gherkin())
+        return "\n".join(lines)

ref_agents/models/hierarchy.py

@@ -0,0 +1,80 @@
+"""Hierarchy models for Epic → Feature → Story structure."""
+
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class Epic(BaseModel):
+    """Epic model (top-level requirement grouping)."""
+
+    epic_id: str = Field(description="Unique epic identifier (e.g., EPIC-001)")
+    title: str = Field(description="Epic title")
+    description: str = Field(default="", description="Epic description")
+    status: str = Field(default="Draft", description="Epic status")
+
+    def to_dict(self) -> dict:
+        """Convert epic to dictionary."""
+        return {
+            "epic_id": self.epic_id,
+            "title": self.title,
+            "description": self.description,
+            "status": self.status,
+        }
+
+
+class Feature(BaseModel):
+    """Feature model (mid-level requirement grouping under Epic)."""
+
+    feature_id: str = Field(description="Unique feature identifier (e.g., FEAT-001)")
+    epic_id: str = Field(description="Parent epic identifier")
+    title: str = Field(description="Feature title")
+    description: str = Field(default="", description="Feature description")
+    status: str = Field(default="Draft", description="Feature status")
+
+    def to_dict(self) -> dict:
+        """Convert feature to dictionary."""
+        return {
+            "feature_id": self.feature_id,
+            "epic_id": self.epic_id,
+            "title": self.title,
+            "description": self.description,
+            "status": self.status,
+        }
+
+
+class Story(BaseModel):
+    """Story model (low-level requirement, can be flat or hierarchical)."""
+
+    story_id: str = Field(description="Unique story identifier (e.g., STORY-001)")
+    title: str = Field(description="Story title")
+    description: str = Field(default="", description="Story description")
+    user_story: str = Field(
+        default="", description="User story format: As a... I want... So that..."
+    )
+    epic_id: Optional[str] = Field(
+        default=None, description="Parent epic identifier (optional for flat stories)"
+    )
+    feature_id: Optional[str] = Field(
+        default=None,
+        description="Parent feature identifier (optional for flat stories)",
+    )
+    status: str = Field(default="Draft", description="Story status")
+    priority: str = Field(default="P2", description="Story priority (P1/P2/P3)")
+
+    def is_flat(self) -> bool:
+        """Check if story is flat (no epic/feature parent)."""
+        return self.epic_id is None and self.feature_id is None
+
+    def to_dict(self) -> dict:
+        """Convert story to dictionary."""
+        return {
+            "story_id": self.story_id,
+            "title": self.title,
+            "description": self.description,
+            "user_story": self.user_story,
+            "epic_id": self.epic_id,
+            "feature_id": self.feature_id,
+            "status": self.status,
+            "priority": self.priority,
+        }

ref_agents/models/invest.py

@@ -0,0 +1,59 @@
+"""INVEST scoring models for user story quality assessment.
+
+INVEST principles: Independent, Negotiable, Valuable, Estimable, Small, Testable.
+"""
+
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class INVESTPrinciple(str, Enum):
+    """INVEST principle enumeration."""
+
+    INDEPENDENT = "Independent"
+    NEGOTIABLE = "Negotiable"
+    VALUABLE = "Valuable"
+    ESTIMABLE = "Estimable"
+    SMALL = "Small"
+    TESTABLE = "Testable"
+
+
+class INVESTScores(BaseModel):
+    """INVEST scores for a user story.
+
+    Each principle scored 0-5:
+    - 0: Not met
+    - 1-2: Poor
+    - 3: Acceptable
+    - 4-5: Excellent
+    """
+
+    independent: int = Field(ge=0, le=5, description="Independent score (0-5)")
+    negotiable: int = Field(ge=0, le=5, description="Negotiable score (0-5)")
+    valuable: int = Field(ge=0, le=5, description="Valuable score (0-5)")
+    estimable: int = Field(ge=0, le=5, description="Estimable score (0-5)")
+    small: int = Field(ge=0, le=5, description="Small score (0-5)")
+    testable: int = Field(ge=0, le=5, description="Testable score (0-5)")
+
+    def overall_score(self) -> float:
+        """Calculate overall INVEST score (average of all principles)."""
+        return (
+            self.independent
+            + self.negotiable
+            + self.valuable
+            + self.estimable
+            + self.small
+            + self.testable
+        ) / 6.0
+
+    def to_dict(self) -> dict[str, int]:
+        """Convert scores to dictionary."""
+        return {
+            "independent": self.independent,
+            "negotiable": self.negotiable,
+            "valuable": self.valuable,
+            "estimable": self.estimable,
+            "small": self.small,
+            "testable": self.testable,
+        }

ref_agents/models/version.py

@@ -0,0 +1,49 @@
+"""Version management models for requirement tracking."""
+
+from datetime import datetime
+from enum import Enum
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class VersionStatus(str, Enum):
+    """Requirement version status."""
+
+    CURRENT = "Current"
+    SUPERSEDED = "Superseded"
+    DRAFT = "Draft"
+
+
+class RequirementVersion(BaseModel):
+    """Version metadata for a requirement artifact."""
+
+    artifact_id: str = Field(
+        description="Artifact identifier (STORY-XXX, EPIC-XXX, etc.)"
+    )
+    version: str = Field(description="Version identifier (semantic or git commit hash)")
+    status: VersionStatus = Field(
+        default=VersionStatus.CURRENT, description="Version status"
+    )
+    created_at: datetime = Field(
+        default_factory=datetime.now, description="Version creation timestamp"
+    )
+    modified_at: Optional[datetime] = Field(
+        default=None, description="Last modification timestamp"
+    )
+    git_commit: Optional[str] = Field(default=None, description="Git commit hash")
+    modified_by: Optional[str] = Field(
+        default=None, description="Last modifier (git user email)"
+    )
+
+    def to_dict(self) -> dict:
+        """Convert version to dictionary."""
+        return {
+            "artifact_id": self.artifact_id,
+            "version": self.version,
+            "status": self.status.value,
+            "created_at": self.created_at.isoformat(),
+            "modified_at": self.modified_at.isoformat() if self.modified_at else None,
+            "git_commit": self.git_commit,
+            "modified_by": self.modified_by,
+        }

ref_agents/prompts/__init__.py

@@ -0,0 +1,9 @@
+"""REF Agent Prompts Package.
+
+Contains prompt generators for all REF agents: discovery, architect,
+developer, tester, reviewer, and scrum master.
+
+Usage:
+    from ref_agents.prompts import start_agent
+    prompt = start_agent.get_developer_prompt()
+"""