verdant 0.1.0__tar.gz

verdant-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mavericks (Raheem, Emafido, Ismail)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

verdant-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: verdant
+Version: 0.1.0
+Summary: VERDANT SDK for inspectable AI governance
+Author: Raheem, Emafido, Ismail
+License: MIT
+Project-URL: Homepage, https://github.com/lgndcraft2/Verdant
+Project-URL: Repository, https://github.com/lgndcraft2/Verdant
+Project-URL: Documentation, https://github.com/lgndcraft2/Verdant/tree/main/docs
+Project-URL: Issues, https://github.com/lgndcraft2/Verdant/issues
+Keywords: ai-governance,ai-safety,audit,bias-detection,ndpr,trust-score
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anthropic<1,>=0.34
+Requires-Dist: google-generativeai<1,>=0.7
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: redis<6,>=5
+Requires-Dist: supabase<3,>=2
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-mock>=3.14; extra == "dev"
+Dynamic: license-file
+
+# VERDANT SDK
+
+VERDANT is a lightweight SDK for making AI outputs inspectable. It wraps an AI call and returns the clean model output together with a structured audit payload, bias flags, a plain-language explanation, and a 0-100 trust score.
+
+The SDK is built for Nigerian and African teams shipping AI into higher-stakes contexts such as hiring, lending, content moderation, and healthcare.
+
+## Install
+
+```bash
+pip install verdant
+```
+
+## Usage
+
+```python
+from verdant import VerdantClient
+
+client = VerdantClient(api_key="vd_live_...")
+
+result = await client.wrap(
+    fn=openai.chat.completions.create,
+    model="gpt-4o",
+    messages=[{"role": "user", "content": user_input}],
+)
+
+print(result.output)
+print(result.trust_score)
+print(result.flags)
+print(result.explanation)
+```
+
+## Project
+
+Source code, documentation, and issue tracking live at:
+
+https://github.com/lgndcraft2/Verdant

verdant-0.1.0/README.md

@@ -0,0 +1,36 @@
+# VERDANT SDK
+
+VERDANT is a lightweight SDK for making AI outputs inspectable. It wraps an AI call and returns the clean model output together with a structured audit payload, bias flags, a plain-language explanation, and a 0-100 trust score.
+
+The SDK is built for Nigerian and African teams shipping AI into higher-stakes contexts such as hiring, lending, content moderation, and healthcare.
+
+## Install
+
+```bash
+pip install verdant
+```
+
+## Usage
+
+```python
+from verdant import VerdantClient
+
+client = VerdantClient(api_key="vd_live_...")
+
+result = await client.wrap(
+    fn=openai.chat.completions.create,
+    model="gpt-4o",
+    messages=[{"role": "user", "content": user_input}],
+)
+
+print(result.output)
+print(result.trust_score)
+print(result.flags)
+print(result.explanation)
+```
+
+## Project
+
+Source code, documentation, and issue tracking live at:
+
+https://github.com/lgndcraft2/Verdant

verdant-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "verdant"
+version = "0.1.0"
+description = "VERDANT SDK for inspectable AI governance"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [
+  { name = "Raheem" },
+  { name = "Emafido" },
+  { name = "Ismail" },
+]
+keywords = [
+  "ai-governance",
+  "ai-safety",
+  "audit",
+  "bias-detection",
+  "ndpr",
+  "trust-score",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+dependencies = [
+  "anthropic>=0.34,<1",
+  "google-generativeai>=0.7,<1",
+  "httpx>=0.27,<1",
+  "pydantic>=2.7,<3",
+  "redis>=5,<6",
+  "supabase>=2,<3",
+]
+
+[tool.setuptools]
+package-dir = {"" = "."}
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["verdant*"]
+
+[tool.setuptools.package-data]
+"verdant.services" = ["prompts/*.txt"]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+  "pytest-mock>=3.14",
+]
+
+[project.urls]
+Homepage = "https://github.com/lgndcraft2/Verdant"
+Repository = "https://github.com/lgndcraft2/Verdant"
+Documentation = "https://github.com/lgndcraft2/Verdant/tree/main/docs"
+Issues = "https://github.com/lgndcraft2/Verdant/issues"

verdant-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

verdant-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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)