guardian-runtime 0.1.0__py3-none-any.whl

guardian/__init__.py

@@ -0,0 +1,51 @@
+"""
+Guardian Runtime — Local-first AI governance layer.
+
+Usage:
+    from guardian import Guardian
+
+    guardian = Guardian.from_policy("policy.yaml")
+    response = guardian.complete(model="gpt-4", messages=[...])
+"""
+from __future__ import annotations  # Python 3.9 compatibility
+
+from guardian.core.engine import GuardianEngine
+from guardian.core.policy import load_policy
+
+__version__ = "0.1.0"
+__all__ = ["Guardian"]
+
+
+class Guardian:
+    """Main entry point for Guardian Runtime."""
+
+    def __init__(self, engine: GuardianEngine):
+        self._engine = engine
+
+    @classmethod
+    def from_policy(cls, path: str) -> "Guardian":
+        """Load a Guardian instance from a YAML policy file."""
+        policy = load_policy(path)
+        engine = GuardianEngine(policy)
+        return cls(engine)
+
+    def complete(
+        self,
+        model: str,
+        messages: list,
+        agent_id: str = "default",
+        session_id: str | None = None,
+        **kwargs,
+    ):
+        """Wrap an LLM call with full Guardian governance."""
+        return self._engine.complete(
+            model=model,
+            messages=messages,
+            agent_id=agent_id,
+            session_id=session_id,
+            **kwargs,
+        )
+
+    def get_cost_report(self, agent_id: str = "default") -> dict:
+        """Return cost report for the given agent."""
+        return self._engine.get_cost_report(agent_id)

guardian/cli/main.py

@@ -0,0 +1,17 @@
+"""Guardian CLI — entry point for all `guardian` commands."""
+
+import click
+
+
+@click.group()
+@click.version_option(package_name="guardian-runtime")
+def cli():
+    """⛨ Guardian Runtime — Local-first AI governance."""
+    pass
+
+
+# Commands will be registered here as they are built
+# from guardian.cli.init import init_command
+# from guardian.cli.validate import validate_command
+# from guardian.cli.status import status_command
+# from guardian.cli.logs import logs_command

guardian/core/engine.py

@@ -0,0 +1,19 @@
+"""Guardian core engine — orchestrates the full request/response pipeline."""
+from __future__ import annotations  # Python 3.9 compatibility
+# TODO (Week 6): Implement GuardianEngine.complete() pipeline
+
+
+class GuardianEngine:
+    """Orchestrates: license check → input guard → LLM → output guard → log."""
+
+    def __init__(self, policy):
+        self.policy = policy
+        # TODO: initialize sub-components from policy
+
+    def complete(self, model, messages, agent_id="default", session_id=None, **kwargs):
+        """Full governed LLM call. Returns GuardianResponse."""
+        raise NotImplementedError("Engine not yet implemented — see ARCHITECTURE.md §4.2")
+
+    def get_cost_report(self, agent_id: str) -> dict:
+        """Return local cost report for the given agent."""
+        raise NotImplementedError

guardian/core/license.py

@@ -0,0 +1,21 @@
+"""License key validation and once-daily server sync."""
+from __future__ import annotations  # Python 3.9 compatibility
+# TODO (Week 6): Implement LicenseManager
+# See ARCHITECTURE.md §4.9 for full spec — especially fail-open and grace period logic
+
+
+class LicenseManager:
+    """Validates license locally and syncs with guardian-ai.dev once per day."""
+
+    LICENSE_SERVER_URL = "https://guardian-ai.dev/api/validate"
+
+    def check_or_sync(self):
+        """Called before every guardian.complete(). Syncs if >24h since last sync."""
+        raise NotImplementedError
+
+    def sync_with_server(self):
+        """POST { license_key, checks_used } → receive { valid, plan, limit, expiry }."""
+        raise NotImplementedError
+
+    def is_initialized(self) -> bool:
+        raise NotImplementedError

guardian/core/policy.py

@@ -0,0 +1,290 @@
+"""YAML policy loader and Pydantic schema validation.
+
+Reads a guardian_policy.yaml file, validates it against a strict Pydantic V2
+schema, and returns a Policy object that every Guardian component uses.
+
+If the YAML has typos, missing fields, or wrong types, Pydantic will raise a
+clear PolicyValidationError with details.
+
+See ARCHITECTURE.md §4.7 for full specification.
+"""
+from __future__ import annotations  # Python 3.9 compatibility
+
+from enum import Enum
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import yaml
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+
+# ---------------------------------------------------------------------------
+# Enums for strict validation
+# ---------------------------------------------------------------------------
+
+class PIIAction(str, Enum):
+    """Action to take when PII is detected."""
+    BLOCK = "block"
+    REDACT = "redact"
+    FLAG = "flag"
+
+
+class LogSink(str, Enum):
+    """Where to write Guardian logs."""
+    JSONL = "jsonl"
+    CONSOLE = "console"
+    BOTH = "both"
+
+
+class LogLevel(str, Enum):
+    """What severity of events to log."""
+    ALL = "ALL"
+    VIOLATIONS_ONLY = "VIOLATIONS_ONLY"
+    HIGH_SEVERITY = "HIGH_SEVERITY"
+
+
+class HallucinationProvider(str, Enum):
+    """Supported LLM providers for hallucination detection (BYOM)."""
+    OPENAI = "openai"
+    ANTHROPIC = "anthropic"
+    OLLAMA = "ollama"
+    GEMINI = "gemini"
+
+
+class LoopAction(str, Enum):
+    """Action to take when a prompt loop is detected."""
+    BLOCK = "block"
+    BLOCK_AND_ALERT = "block_and_alert"
+
+
+# Valid PII entity names — must match PIIType enum values in pii.py
+VALID_PII_ENTITIES = frozenset({
+    "ssn", "credit_card", "email", "phone",
+    "aadhaar", "pan", "upi_id", "passport", "secret",
+})
+
+
+# ---------------------------------------------------------------------------
+# Exceptions
+# ---------------------------------------------------------------------------
+
+class PolicyValidationError(Exception):
+    """Raised when a YAML policy file fails schema validation.
+
+    Attributes:
+        errors: List of Pydantic validation error dicts.
+    """
+
+    def __init__(self, message: str, errors: Optional[List[Dict[str, Any]]] = None):
+        super().__init__(message)
+        self.errors = errors or []
+
+
+# ---------------------------------------------------------------------------
+# Config sub-models
+# ---------------------------------------------------------------------------
+
+class ScopeConfig(BaseModel):
+    """Topic-scoping configuration for the Input Guard."""
+    allowed_topics: List[str] = Field(default_factory=list)
+    block_message: str = "This topic is outside my scope."
+
+
+class InputGuardConfig(BaseModel):
+    """Configuration for the Input Guard pipeline."""
+    pii_detection: bool = True
+    pii_entities: List[str] = Field(
+        default_factory=lambda: list(VALID_PII_ENTITIES),
+        description="List of PII entity types to detect.",
+    )
+    pii_action: PIIAction = PIIAction.BLOCK
+    jailbreak_detection: bool = True
+    scope: Optional[ScopeConfig] = None
+
+    @field_validator("pii_entities")
+    @classmethod
+    def validate_pii_entities(cls, v: List[str]) -> List[str]:
+        """Ensure every entity name matches a known PIIType value."""
+        invalid = [e for e in v if e not in VALID_PII_ENTITIES]
+        if invalid:
+            raise ValueError(
+                f"Unknown PII entities: {invalid}. "
+                f"Valid values: {sorted(VALID_PII_ENTITIES)}"
+            )
+        return v
+
+
+class OutputGuardConfig(BaseModel):
+    """Configuration for the Output Guard pipeline."""
+    hallucination_check: bool = False
+    hallucination_provider: HallucinationProvider = HallucinationProvider.OPENAI
+    hallucination_model: str = "gpt-4o-mini"
+    pii_detection: bool = True
+    profanity_filter: bool = False
+    competitor_block: List[str] = Field(default_factory=list)
+
+
+class AutoDowngradeConfig(BaseModel):
+    """Auto-downgrade model when budget threshold is reached."""
+    enabled: bool = False
+    threshold: float = Field(default=0.80, ge=0.0, le=1.0)
+    target_model: str = "gpt-3.5-turbo"
+
+
+class LoopConfig(BaseModel):
+    """Semantic loop detection settings."""
+    max_retries: int = Field(default=3, ge=1)
+    similarity_threshold: float = Field(default=0.90, ge=0.0, le=1.0)
+    action: LoopAction = LoopAction.BLOCK_AND_ALERT
+
+
+class CostConfig(BaseModel):
+    """FinOps budget and cost control settings."""
+    daily_budget: float = Field(default=10.00, ge=0.0)
+    monthly_budget: Optional[float] = Field(default=None, ge=0.0)
+    per_session_limit: float = Field(default=0.50, ge=0.0)
+    currency: str = "USD"
+    auto_downgrade: Optional[AutoDowngradeConfig] = None
+    loop_detection: Optional[LoopConfig] = None
+
+
+class RateLimitConfig(BaseModel):
+    """Rate limit for a specific tool."""
+    max_calls: int = Field(ge=1)
+    per: str = "session"  # "session" | "minute" | "hour"
+    cooldown_seconds: int = Field(default=0, ge=0)
+
+
+class ArgRuleConfig(BaseModel):
+    """Argument validation rule for a tool parameter."""
+    type: str = "string"  # "string" | "int" | "enum"
+    pattern: Optional[str] = None
+    values: Optional[List[str]] = None
+
+
+class ToolConfig(BaseModel):
+    """Tool governance configuration."""
+    allowed: List[str] = Field(default_factory=list)
+    denied: List[str] = Field(default_factory=list)
+    rate_limits: Dict[str, RateLimitConfig] = Field(default_factory=dict)
+    argument_validation: Dict[str, Dict[str, ArgRuleConfig]] = Field(
+        default_factory=dict
+    )
+
+
+class LoggingConfig(BaseModel):
+    """Logging configuration."""
+    sink: LogSink = LogSink.JSONL
+    log_level: LogLevel = LogLevel.ALL
+    retention_days: int = Field(default=30, ge=1)
+
+
+class AlertConfig(BaseModel):
+    """Alert/notification configuration (v0.2+)."""
+    slack_webhook: Optional[str] = None
+    email: Optional[str] = None
+
+
+class ComplianceConfig(BaseModel):
+    """Compliance framework configuration."""
+    frameworks: List[str] = Field(default_factory=list)  # e.g. ["dpdp", "gdpr"]
+
+
+# ---------------------------------------------------------------------------
+# Agent-level policy
+# ---------------------------------------------------------------------------
+
+class AgentPolicy(BaseModel):
+    """Complete policy for a single agent."""
+    input_guard: Optional[InputGuardConfig] = None
+    output_guard: Optional[OutputGuardConfig] = None
+    cost: Optional[CostConfig] = None
+    tools: Optional[ToolConfig] = None
+
+
+# ---------------------------------------------------------------------------
+# Root Policy model
+# ---------------------------------------------------------------------------
+
+class Policy(BaseModel):
+    """Root policy model — represents a complete guardian_policy.yaml file.
+
+    Usage:
+        policy = load_policy("guardian_policy.yaml")
+        agent_config = policy.get_agent("support-bot")
+    """
+    version: str = "1.0"
+    name: str = "default"
+    environment: Optional[str] = None  # "dev" | "staging" | "production"
+    agents: Dict[str, AgentPolicy] = Field(default_factory=dict)
+    logging: Optional[LoggingConfig] = None
+    alerts: Optional[AlertConfig] = None
+    compliance: Optional[ComplianceConfig] = None
+
+    @model_validator(mode="after")
+    def ensure_default_agent(self) -> "Policy":
+        """Ensure there is at least a 'default' agent entry."""
+        if not self.agents:
+            self.agents = {"default": AgentPolicy()}
+        return self
+
+    def get_agent(self, agent_id: str) -> AgentPolicy:
+        """Get configuration for a specific agent, falling back to 'default'.
+
+        Args:
+            agent_id: The agent identifier to look up.
+
+        Returns:
+            AgentPolicy for the given agent, or the 'default' agent if not found.
+        """
+        if agent_id in self.agents:
+            return self.agents[agent_id]
+        return self.agents.get("default", AgentPolicy())
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def load_policy(path: str | Path) -> Policy:
+    """Load and validate a Guardian YAML policy file.
+
+    Args:
+        path: Path to the YAML policy file.
+
+    Returns:
+        A fully validated Policy object.
+
+    Raises:
+        FileNotFoundError: If the YAML file does not exist.
+        PolicyValidationError: If the YAML content fails schema validation.
+    """
+    path = Path(path)
+
+    if not path.exists():
+        raise FileNotFoundError(f"Policy file not found: {path}")
+
+    with open(path, "r") as f:
+        raw = yaml.safe_load(f)
+
+    if raw is None:
+        raise PolicyValidationError(
+            f"Policy file is empty: {path}"
+        )
+
+    if not isinstance(raw, dict):
+        raise PolicyValidationError(
+            f"Policy file must contain a YAML mapping, got {type(raw).__name__}: {path}"
+        )
+
+    try:
+        return Policy.model_validate(raw)
+    except Exception as e:
+        # Re-wrap Pydantic ValidationError into our own exception
+        errors = []
+        if hasattr(e, "errors"):
+            errors = e.errors()  # type: ignore[union-attr]
+        raise PolicyValidationError(
+            f"Policy validation failed for {path}: {e}",
+            errors=errors,
+        ) from e

guardian/core/storage.py

@@ -0,0 +1,27 @@
+"""Local ~/.guardian/ file manager — config.json and usage.json."""
+from __future__ import annotations  # Python 3.9 compatibility
+# TODO (Week 6): Implement LocalStorage
+# See ARCHITECTURE.md §4.8 for full spec
+
+
+class LocalStorage:
+    """Manages ~/.guardian/config.json and ~/.guardian/usage.json."""
+
+    def save_license(self, key: str, plan: str, limit: int, expiry: str | None = None):
+        raise NotImplementedError
+
+    def load_license(self) -> dict | None:
+        raise NotImplementedError
+
+    def increment_usage(self) -> int:
+        raise NotImplementedError
+
+    def get_usage(self) -> dict:
+        raise NotImplementedError
+
+    def check_usage_limit(self) -> tuple[bool, int, int]:
+        """Returns (within_limit, current_count, plan_limit)."""
+        raise NotImplementedError
+
+    def mark_synced(self, timestamp: str):
+        raise NotImplementedError

guardian/finops/cost_calculator.py

@@ -0,0 +1,29 @@
+"""Per-model cost tables and cost estimation."""
+# TODO (Week 4): Implement estimate_cost()
+# See ARCHITECTURE.md §4.5 — keep this table updated as providers change pricing
+
+# Cost per 1,000 tokens in USD
+MODEL_COST_PER_1K: dict[str, dict[str, float]] = {
+    # OpenAI
+    "gpt-4o":            {"input": 0.005,   "output": 0.015},
+    "gpt-4o-mini":       {"input": 0.00015, "output": 0.0006},
+    "gpt-4-turbo":       {"input": 0.01,    "output": 0.03},
+    "gpt-4":             {"input": 0.03,    "output": 0.06},
+    "gpt-3.5-turbo":     {"input": 0.0005,  "output": 0.0015},
+    # Anthropic
+    "claude-3-5-sonnet": {"input": 0.003,   "output": 0.015},
+    "claude-3-opus":     {"input": 0.015,   "output": 0.075},
+    "claude-3-haiku":    {"input": 0.00025, "output": 0.00125},
+    # Google
+    "gemini-1-5-pro":    {"input": 0.00125, "output": 0.005},
+    "gemini-1-5-flash":  {"input": 0.000075,"output": 0.0003},
+}
+
+
+def estimate_cost(input_tokens: int, output_tokens: int = 0, model: str = "gpt-4o") -> float:
+    """Estimate cost in USD for given token counts and model."""
+    raise NotImplementedError
+
+
+def get_supported_models() -> list[str]:
+    return list(MODEL_COST_PER_1K.keys())

guardian/finops/token_counter.py

@@ -0,0 +1,14 @@
+"""Token counting — tiktoken wrapper."""
+from __future__ import annotations  # Python 3.9 compatibility
+# TODO (Week 4): Implement token counting functions
+# See ARCHITECTURE.md §4.5
+
+
+def count_tokens(text: str, model: str = "gpt-4") -> int:
+    """Count tokens in text for the given model using tiktoken."""
+    raise NotImplementedError
+
+
+def count_messages_tokens(messages: list[dict], model: str = "gpt-4") -> int:
+    """Count total tokens for a list of chat messages including ChatML overhead."""
+    raise NotImplementedError

guardian/guards/validators/hallucination.py

@@ -0,0 +1,31 @@
+"""Hallucination detector — LLM-as-judge pattern."""
+from __future__ import annotations  # Python 3.9 compatibility
+# TODO (Week 5): Implement HallucinationDetector
+# See ARCHITECTURE.md §4.4.1
+# Note: uses developer's OpenAI API key for the judge call, NOT ours
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class HallucinationResult:
+    verdict: str  # "grounded" | "partially_grounded" | "hallucinated"
+    confidence: float
+    unsupported_claims: list[str] = field(default_factory=list)
+    explanation: str = ""
+
+    @property
+    def is_hallucination(self) -> bool:
+        return self.verdict == "hallucinated"
+
+
+class HallucinationDetector:
+    """Uses a small LLM (gpt-4o-mini) to verify response grounding in context."""
+
+    def __init__(self, judge_model: str = "gpt-4o-mini", threshold: float = 0.7):
+        self.judge_model = judge_model
+        self.threshold = threshold
+
+    def check(self, question: str, response: str, context: str) -> HallucinationResult:
+        """Judge whether the response is grounded in the provided context."""
+        raise NotImplementedError

guardian/guards/validators/jailbreak.py

@@ -0,0 +1,33 @@
+"""Jailbreak and prompt injection detector — 50+ patterns, zero external deps."""
+from __future__ import annotations  # Python 3.9 compatibility
+# TODO (Week 4): Implement JailbreakDetector
+# See ARCHITECTURE.md §4.3.2
+
+import re
+from dataclasses import dataclass
+
+
+@dataclass
+class JailbreakResult:
+    is_jailbreak: bool
+    confidence: float
+    pattern_matched: str | None
+    category: str | None  # "dan" | "instruction_override" | "role_play" | "encoding" | "extraction"
+
+
+# TODO (Week 4): Fill in all 50+ patterns from ARCHITECTURE.md §4.3.2
+JAILBREAK_PATTERNS: list[tuple[str, str]] = []
+
+
+class JailbreakDetector:
+    """Detects jailbreak attempts using compiled regex patterns."""
+
+    def __init__(self):
+        self._compiled = [
+            (re.compile(pattern, re.IGNORECASE), category)
+            for pattern, category in JAILBREAK_PATTERNS
+        ]
+
+    def detect(self, text: str) -> JailbreakResult:
+        """Return first matching jailbreak pattern, or is_jailbreak=False."""
+        raise NotImplementedError