verdant 0.1.0__py3-none-any.whl

verdant/__init__.py

@@ -0,0 +1,35 @@
+from .config import Settings, get_settings
+from .client import VerdantAPIError, VerdantClient
+from .models import (
+    AuditPayload,
+    BaselineStageOutput,
+    BiasSeverity,
+    BiasStageOutput,
+    ContextType,
+    ExplainStageOutput,
+    IntentStageOutput,
+    PipelineRunRequest,
+    PipelineStageOutputs,
+    RiskLevel,
+    TrustStageOutput,
+    WrapResult,
+)
+
+__all__ = [
+    "AuditPayload",
+    "BaselineStageOutput",
+    "BiasSeverity",
+    "BiasStageOutput",
+    "ContextType",
+    "ExplainStageOutput",
+    "IntentStageOutput",
+    "PipelineRunRequest",
+    "PipelineStageOutputs",
+    "RiskLevel",
+    "Settings",
+    "TrustStageOutput",
+    "VerdantAPIError",
+    "VerdantClient",
+    "WrapResult",
+    "get_settings",
+]

verdant/client.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+from typing import Any, Callable
+
+import httpx
+
+from .config import Settings, get_settings
+from .models import ContextType, WrapResult
+from .pipeline import VerdantPipeline
+
+
+class VerdantClient:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        settings: Settings | None = None,
+        pipeline: VerdantPipeline | None = None,
+    ) -> None:
+        self.settings = settings or get_settings()
+        updates: dict[str, Any] = {}
+        if api_key:
+            updates["verdant_api_key"] = api_key
+        if base_url:
+            updates["verdant_api_url"] = base_url
+        if updates:
+            self.settings = self.settings.model_copy(update=updates)
+        self.pipeline = pipeline or VerdantPipeline(self.settings)
+
+    @property
+    def _is_hosted(self) -> bool:
+        """Use the hosted API when both a base URL and a VERDANT key are configured."""
+        return bool(self.settings.verdant_api_url and self.settings.verdant_api_key)
+
+    async def wrap(
+        self,
+        fn: Callable[..., Any],
+        *,
+        context_type: str | ContextType | None = None,
+        input_text: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        **fn_kwargs: Any,
+    ) -> WrapResult:
+        """Wrap a local model call and run the reasoning pipeline in-process."""
+        return await self.pipeline.run(
+            fn=fn,
+            context_type=context_type,
+            input_text=input_text,
+            fn_kwargs=fn_kwargs,
+            metadata=metadata,
+        )
+
+    async def run(
+        self,
+        *,
+        context_type: str | ContextType,
+        input_text: str,
+        metadata: dict[str, Any] | None = None,
+    ) -> WrapResult:
+        """Run the reasoning pipeline for the given input.
+
+        In hosted mode (a ``verdant_api_url`` and ``verdant_api_key`` are set) this calls
+        the VERDANT API over HTTP, so provider (Claude/Gemini) keys stay server-side. Otherwise
+        it runs the pipeline in-process.
+        """
+        if self._is_hosted:
+            return await self._run_hosted(context_type=context_type, input_text=input_text, metadata=metadata)
+        return await self.pipeline.run(
+            context_type=context_type,
+            input_text=input_text,
+            metadata=metadata,
+        )
+
+    async def _run_hosted(
+        self,
+        *,
+        context_type: str | ContextType,
+        input_text: str,
+        metadata: dict[str, Any] | None,
+    ) -> WrapResult:
+        url = self.settings.verdant_api_url.rstrip("/") + "/pipeline/run"
+        context_value = context_type.value if isinstance(context_type, ContextType) else str(context_type)
+        payload = {
+            "context_type": context_value,
+            "input_text": input_text,
+            "metadata": metadata or {},
+        }
+        headers = {"Authorization": f"Bearer {self.settings.verdant_api_key}"}
+
+        async with httpx.AsyncClient(timeout=self.settings.request_timeout_seconds) as client:
+            response = await client.post(url, json=payload, headers=headers)
+
+        try:
+            body = response.json()
+        except ValueError:
+            body = None
+
+        if response.status_code >= 400:
+            message = None
+            if isinstance(body, dict) and body.get("error"):
+                message = body["error"].get("message")
+            raise VerdantAPIError(message or f"VERDANT API returned {response.status_code}", status_code=response.status_code)
+
+        if not isinstance(body, dict) or body.get("data") is None:
+            raise VerdantAPIError("VERDANT API returned an unexpected response.", status_code=response.status_code)
+
+        return WrapResult.model_validate(body["data"])
+
+
+class VerdantAPIError(RuntimeError):
+    def __init__(self, message: str, *, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code

verdant/config.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import os
+from functools import lru_cache
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+def _split_csv(value: str | None, default: list[str]) -> list[str]:
+    if not value:
+        return default
+    return [item.strip() for item in value.split(",") if item.strip()]
+
+
+class Settings(BaseModel):
+    model_config = ConfigDict(extra="ignore")
+
+    verdant_api_key: str = ""
+    verdant_api_url: str = ""
+    anthropic_api_key: str = ""
+    gemini_api_key: str = ""
+    supabase_url: str = ""
+    supabase_service_role_key: str = ""
+    redis_url: str = "redis://localhost:6379/0"
+    webhook_secret: str = ""
+    environment: str = "development"
+    log_level: str = "info"
+    trust_score_alert_threshold: int = Field(default=40, ge=0, le=100)
+    cors_origins: list[str] = Field(default_factory=lambda: ["*"])
+    claude_model: str = "claude-sonnet-4-6"
+    gemini_model: str = "gemini-2.5-flash"
+    request_timeout_seconds: float = 30.0
+    webhook_timeout_seconds: float = 10.0
+
+    @classmethod
+    def from_env(cls) -> "Settings":
+        return cls(
+            verdant_api_key=os.getenv("VERDANT_API_KEY", ""),
+            verdant_api_url=os.getenv("VERDANT_API_URL", ""),
+            anthropic_api_key=os.getenv("ANTHROPIC_API_KEY", ""),
+            gemini_api_key=os.getenv("GEMINI_API_KEY", ""),
+            supabase_url=os.getenv("SUPABASE_URL", ""),
+            supabase_service_role_key=os.getenv("SUPABASE_SERVICE_ROLE_KEY", ""),
+            redis_url=os.getenv("REDIS_URL", "redis://localhost:6379/0"),
+            webhook_secret=os.getenv("WEBHOOK_SECRET", ""),
+            environment=os.getenv("ENVIRONMENT", "development"),
+            log_level=os.getenv("LOG_LEVEL", "info"),
+            trust_score_alert_threshold=int(os.getenv("TRUST_SCORE_ALERT_THRESHOLD", "40")),
+            cors_origins=_split_csv(os.getenv("CORS_ORIGINS"), ["*"]),
+            claude_model=os.getenv("CLAUDE_MODEL", "claude-sonnet-4-6"),
+            gemini_model=os.getenv("GEMINI_MODEL", "gemini-2.5-flash"),
+            request_timeout_seconds=float(os.getenv("REQUEST_TIMEOUT_SECONDS", "30")),
+            webhook_timeout_seconds=float(os.getenv("WEBHOOK_TIMEOUT_SECONDS", "10")),
+        )
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    return Settings.from_env()

verdant/models.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class VerdantBaseModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", populate_by_name=True, protected_namespaces=())
+
+
+class ContextType(str, Enum):
+    hiring = "hiring"
+    lending = "lending"
+    content = "content"
+    healthcare = "healthcare"
+
+    @classmethod
+    def normalize(cls, value: str | ContextType | None) -> ContextType:
+        if isinstance(value, cls):
+            return value
+        if value is None:
+            return cls.content
+
+        normalized = str(value).strip().lower().replace(" ", "_").replace("-", "_")
+        aliases = {
+            "content_moderation": cls.content,
+            "content_moderation_review": cls.content,
+            "moderation": cls.content,
+        }
+        if normalized in aliases:
+            return aliases[normalized]
+
+        for member in cls:
+            if member.value == normalized:
+                return member
+        raise ValueError(f"Unsupported context type: {value}")
+
+
+class BiasSeverity(str, Enum):
+    low = "low"
+    medium = "medium"
+    high = "high"
+    critical = "critical"
+
+
+class RiskLevel(str, Enum):
+    low = "low"
+    medium = "medium"
+    high = "high"
+    critical = "critical"
+
+
+class IntentStageOutput(VerdantBaseModel):
+    detected_intent: str
+    context_type: ContextType
+    user_intent_summary: str
+    entities: list[str] = Field(default_factory=list)
+    signals: list[str] = Field(default_factory=list)
+    confidence: float = Field(ge=0.0, le=1.0)
+    needs_review: bool = False
+
+
+class BaselineStageOutput(VerdantBaseModel):
+    context_type: ContextType
+    baseline_name: str
+    baseline_version: str
+    demographic_focus: list[str] = Field(default_factory=list)
+    baseline_summary: str
+    policy_notes: list[str] = Field(default_factory=list)
+    baseline_data: dict[str, Any] = Field(default_factory=dict)
+    source: str = "supabase"
+    confidence: float = Field(ge=0.0, le=1.0)
+
+
+class BiasStageOutput(VerdantBaseModel):
+    flags: list[str] = Field(default_factory=list)
+    matched_patterns: list[str] = Field(default_factory=list)
+    severity: BiasSeverity = BiasSeverity.low
+    bias_score: int = Field(ge=0, le=100)
+    summary: str
+    confidence: float = Field(ge=0.0, le=1.0)
+
+    @field_validator("bias_score", mode="before")
+    @classmethod
+    def _clamp_bias_score(cls, value: Any) -> int:
+        return max(0, min(100, int(value)))
+
+
+class ExplainStageOutput(VerdantBaseModel):
+    plain_language_explanation: str
+    reasoning_summary: list[str] = Field(default_factory=list)
+    caveats: list[str] = Field(default_factory=list)
+    confidence: float = Field(ge=0.0, le=1.0)
+
+
+class TrustStageOutput(VerdantBaseModel):
+    trust_score: int = Field(ge=0, le=100)
+    risk_level: RiskLevel
+    score_breakdown: dict[str, float] = Field(default_factory=dict)
+    reasons: list[str] = Field(default_factory=list)
+    alerts: list[str] = Field(default_factory=list)
+    confidence: float = Field(ge=0.0, le=1.0)
+
+    @field_validator("trust_score", mode="before")
+    @classmethod
+    def _clamp_trust_score(cls, value: Any) -> int:
+        return max(0, min(100, int(value)))
+
+
+class PipelineStageOutputs(VerdantBaseModel):
+    intent: IntentStageOutput
+    baseline: BaselineStageOutput
+    bias: BiasStageOutput
+    explanation: ExplainStageOutput
+    trust: TrustStageOutput
+
+
+class AuditPayload(VerdantBaseModel):
+    audit_id: UUID | None = None
+    request_id: UUID = Field(default_factory=uuid4)
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    context_type: ContextType
+    input_text: str
+    output_text: str
+    raw_output: Any = None
+    clean_output: Any = None
+    stages: PipelineStageOutputs
+    trust_score: int = Field(ge=0, le=100)
+    flags: list[str] = Field(default_factory=list)
+    explanation: str
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    model_name: str = "claude-sonnet-4-6"
+    duration_ms: int = 0
+    error: str | None = None
+
+
+class WrapResult(VerdantBaseModel):
+    output: Any
+    audit: AuditPayload
+    trust_score: int = Field(ge=0, le=100)
+    flags: list[str] = Field(default_factory=list)
+    explanation: str
+
+
+class PipelineRunRequest(VerdantBaseModel):
+    input_text: str
+    context_type: ContextType
+    metadata: dict[str, Any] = Field(default_factory=dict)

verdant/pipeline.py

@@ -0,0 +1,274 @@
+from __future__ import annotations
+
+import asyncio
+import inspect
+import json
+import logging
+import time
+from typing import Any, Callable
+
+from .config import Settings, get_settings
+from .models import (
+    AuditPayload,
+    BaselineStageOutput,
+    BiasStageOutput,
+    ContextType,
+    ExplainStageOutput,
+    IntentStageOutput,
+    PipelineStageOutputs,
+    RiskLevel,
+    TrustStageOutput,
+    WrapResult,
+)
+from .services.cache_service import CacheService
+from .services.claude_service import ClaudeService
+from .services.db_service import DBService
+from .services.gemini_service import GeminiService
+from .stages.baseline import load_baseline
+from .stages.bias import match_bias_patterns
+from .stages.explain import generate_explanation
+from .stages.intent import extract_intent
+from .stages.trust import synthesize_trust_score
+
+logger = logging.getLogger(__name__)
+
+
+def _json_safe(value: Any) -> Any:
+    if hasattr(value, "model_dump"):
+        return value.model_dump(mode="json")
+    if isinstance(value, dict):
+        return {str(key): _json_safe(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [_json_safe(item) for item in value]
+    if isinstance(value, tuple):
+        return [_json_safe(item) for item in value]
+    if isinstance(value, set):
+        return [_json_safe(item) for item in value]
+    return str(value)
+
+
+def _stringify_output(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, str):
+        return value
+    if isinstance(value, dict):
+        if isinstance(value.get("output"), str):
+            return value["output"]
+        if "choices" in value:
+            choices = value.get("choices") or []
+            if choices:
+                first = choices[0]
+                message = first.get("message") if isinstance(first, dict) else getattr(first, "message", None)
+                if isinstance(message, dict) and isinstance(message.get("content"), str):
+                    return message["content"]
+                if hasattr(message, "content"):
+                    content = getattr(message, "content")
+                    if isinstance(content, str):
+                        return content
+        return json.dumps(value, ensure_ascii=False, default=str)
+    for attr in ("output_text", "text"):
+        attr_value = getattr(value, attr, None)
+        if isinstance(attr_value, str):
+            return attr_value
+    if hasattr(value, "model_dump"):
+        dumped = value.model_dump(mode="json")
+        if isinstance(dumped, dict):
+            return _stringify_output(dumped)
+    return str(value)
+
+
+def _derive_input_text(fn_kwargs: dict[str, Any]) -> str:
+    for key in ("input_text", "prompt", "content", "text", "message"):
+        value = fn_kwargs.get(key)
+        if isinstance(value, str) and value.strip():
+            return value
+    messages = fn_kwargs.get("messages")
+    if isinstance(messages, list) and messages:
+        parts: list[str] = []
+        for message in messages:
+            if isinstance(message, dict):
+                role = message.get("role", "user")
+                content = message.get("content", "")
+            else:
+                role = getattr(message, "role", "user")
+                content = getattr(message, "content", "")
+            parts.append(f"{role}: {content}")
+        if parts:
+            return "\n".join(parts)
+    return json.dumps(_json_safe(fn_kwargs), ensure_ascii=False, default=str)
+
+
+async def _call_target(fn: Callable[..., Any], fn_kwargs: dict[str, Any]) -> Any:
+    result = fn(**fn_kwargs)
+    if inspect.isawaitable(result):
+        return await result
+    return result
+
+
+class VerdantPipeline:
+    def __init__(
+        self,
+        settings: Settings | None = None,
+        *,
+        claude_service: ClaudeService | None = None,
+        gemini_service: GeminiService | None = None,
+        cache_service: CacheService | None = None,
+        db_service: DBService | None = None,
+    ) -> None:
+        self.settings = settings or get_settings()
+        self.claude_service = claude_service or ClaudeService(self.settings)
+        self.gemini_service = gemini_service or GeminiService(self.settings)
+        self.cache_service = cache_service or CacheService(self.settings)
+        self.db_service = db_service or DBService(self.settings)
+
+    async def _generate_default_output(
+        self,
+        input_text: str,
+        intent: IntentStageOutput,
+        baseline: BaselineStageOutput,
+        metadata: dict[str, Any],
+    ) -> str:
+        prompt = (
+            "Respond helpfully to the user's request and return JSON only.\n\n"
+            f"Context type: {intent.context_type.value}\n"
+            f"Intent summary: {intent.user_intent_summary}\n"
+            f"Baseline summary: {baseline.baseline_summary}\n"
+            f"Input text:\n{input_text}\n\n"
+            f"Metadata:\n{json.dumps(_json_safe(metadata), ensure_ascii=False, default=str)}\n"
+        )
+
+        try:
+            return await self.claude_service.generate_text("generate", prompt)
+        except Exception as exc:
+            logger.warning("Default output generation failed, using input echo fallback: %s", exc)
+            return input_text
+
+    async def run(
+        self,
+        fn: Callable[..., Any] | None = None,
+        *,
+        context_type: str | ContextType | None = None,
+        input_text: str | None = None,
+        fn_kwargs: dict[str, Any] | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> WrapResult:
+        started_at = time.perf_counter()
+        metadata = metadata or {}
+        fn_kwargs = dict(fn_kwargs or {})
+        resolved_input_text = input_text or _derive_input_text(fn_kwargs)
+
+        intent = await extract_intent(
+            resolved_input_text,
+            context_type=context_type,
+            settings=self.settings,
+            claude_service=self.claude_service,
+            gemini_service=self.gemini_service,
+        )
+
+        baseline_context = ContextType.normalize(context_type) if context_type else intent.context_type
+        baseline = await load_baseline(
+            baseline_context,
+            settings=self.settings,
+            db_service=self.db_service,
+            cache_service=self.cache_service,
+        )
+
+        pipeline_error: str | None = None
+
+        if fn is None:
+            try:
+                raw_output: Any = await self._generate_default_output(resolved_input_text, intent, baseline, metadata)
+                clean_output: Any = raw_output
+            except Exception as exc:  # pragma: no cover - catch-all guard
+                logger.exception("Default generation failed unexpectedly: %s", exc)
+                raw_output = {"error": str(exc)}
+                clean_output = ""
+                pipeline_error = str(exc)
+        else:
+            try:
+                raw_output = await _call_target(fn, fn_kwargs)
+                clean_output = _json_safe(raw_output)
+            except Exception as exc:
+                logger.warning("Wrapped function raised; continuing with fallback output: %s", exc)
+                raw_output = {"error": str(exc)}
+                clean_output = ""
+                pipeline_error = str(exc)
+
+        output_text = _stringify_output(clean_output)
+        bias = await match_bias_patterns(
+            resolved_input_text,
+            output_text,
+            intent=intent,
+            baseline=baseline,
+        )
+        explanation = await generate_explanation(
+            resolved_input_text,
+            output_text,
+            intent=intent,
+            baseline=baseline,
+            bias=bias,
+            settings=self.settings,
+            claude_service=self.claude_service,
+            gemini_service=self.gemini_service,
+        )
+        trust = await synthesize_trust_score(
+            intent=intent,
+            baseline=baseline,
+            bias=bias,
+            explanation=explanation,
+            settings=self.settings,
+            db_service=self.db_service,
+        )
+
+        if pipeline_error:
+            explanation = explanation.model_copy(
+                update={
+                    "plain_language_explanation": (
+                        f"{explanation.plain_language_explanation} "
+                        f"The wrapped AI call failed: {pipeline_error}."
+                    ).strip(),
+                    "caveats": explanation.caveats + ["No valid upstream output was produced."],
+                }
+            )
+            trust = trust.model_copy(
+                update={
+                    "trust_score": min(trust.trust_score, 15),
+                    "risk_level": RiskLevel.critical,
+                    "alerts": list(dict.fromkeys(trust.alerts + ["Wrapped function call failed"])),
+                    "reasons": trust.reasons + [f"Upstream call failed: {pipeline_error}."],
+                    "score_breakdown": {**trust.score_breakdown, "upstream_call_failed": 0.0},
+                }
+            )
+
+        stages = PipelineStageOutputs(
+            intent=intent,
+            baseline=baseline,
+            bias=bias,
+            explanation=explanation,
+            trust=trust,
+        )
+
+        audit = AuditPayload(
+            context_type=ContextType.normalize(intent.context_type),
+            input_text=resolved_input_text,
+            output_text=output_text,
+            raw_output=_json_safe(raw_output),
+            clean_output=_json_safe(clean_output),
+            stages=stages,
+            trust_score=trust.trust_score,
+            flags=list(bias.flags),
+            explanation=explanation.plain_language_explanation,
+            metadata=_json_safe(metadata),
+            model_name=self.settings.claude_model,
+            duration_ms=int((time.perf_counter() - started_at) * 1000),
+            error=raw_output.get("error") if isinstance(raw_output, dict) else None,
+        )
+
+        return WrapResult(
+            output=clean_output,
+            audit=audit,
+            trust_score=trust.trust_score,
+            flags=list(bias.flags),
+            explanation=explanation.plain_language_explanation,
+        )

verdant/services/__init__.py

@@ -0,0 +1 @@
+# Service package marker.