feat: AI-generated descriptions for contracts

acartag7 · web-flow · commit ae146f6a6da6 · 2026-03-13T00:55:59.000+01:00
diff --git a/dashboard/src/lib/api/contracts.ts b/dashboard/src/lib/api/contracts.ts
@@ -116,3 +116,15 @@ export function getContractUsage(
     `/contracts/${encodeURIComponent(contractId)}/usage`,
   )
 }
+
+export function generateDescription(body: {
+  name: string
+  type: string
+  definition_yaml: string
+  tags?: string[]
+}): Promise<{ description: string }> {
+  return request<{ description: string }>("/contracts/generate-description", {
+    method: "POST",
+    body: JSON.stringify(body),
+  })
+}
diff --git a/dashboard/src/lib/api/index.ts b/dashboard/src/lib/api/index.ts
@@ -6,7 +6,7 @@ export { listBundles, listBundleVersions, uploadBundle, deployBundle, getBundleY
 export { getAgentStatus, getAgentCoverage, getFleetCoverage, getAgentHistory } from "./agents"
 export { getStatsOverview, getContractStats } from "./stats"
 export { listChannels, createChannel, updateChannel, deleteChannel, testChannel, rotateSigningKey, purgeEvents, getAiConfig, updateAiConfig, deleteAiConfig, testAiConnection, getAiUsage } from "./settings"
-export { listContracts, getContract, getContractVersion, createContract, updateContract, deleteContract, importContracts, getContractUsage } from "./contracts"
+export { listContracts, getContract, getContractVersion, createContract, updateContract, deleteContract, importContracts, getContractUsage, generateDescription } from "./contracts"
 export { listCompositions, getComposition, createComposition, updateComposition, deleteComposition, previewComposition, deployComposition } from "./compositions"
 
 export type { HealthResponse, HealthDetailsResponse, ServiceHealth, UserInfo, SetupResponse, ApiKeyInfo, CreateKeyResponse } from "./auth"
diff --git a/dashboard/src/pages/contracts/contract-editor-dialog.tsx b/dashboard/src/pages/contracts/contract-editor-dialog.tsx
@@ -14,7 +14,11 @@ import {
 import { Alert, AlertDescription } from "@/components/ui/alert"
 import { YamlEditor } from "@/components/yaml-editor"
 import { useYamlValidation } from "@/hooks/use-yaml-validation"
-import { createContract, updateContract, type LibraryContract } from "@/lib/api/contracts"
+import { createContract, updateContract, generateDescription, type LibraryContract } from "@/lib/api/contracts"
+import { getAiConfig } from "@/lib/api/settings"
+import {
+  Tooltip, TooltipContent, TooltipTrigger,
+} from "@/components/ui/tooltip"
 import { AiChatPanel } from "./ai-chat-panel"
 
 const CONTRACT_TYPES = ["pre", "post", "session", "sandbox"] as const
@@ -58,8 +62,17 @@ export function ContractEditorDialog({
   const [definition, setDefinition] = useState("")
   const [saving, setSaving] = useState(false)
   const [error, setError] = useState<string | null>(null)
+  const [aiConfigured, setAiConfigured] = useState(false)
+  const [generatingDesc, setGeneratingDesc] = useState(false)
   const { validation, validate, reset } = useYamlValidation()
 
+  // Check AI config on mount
+  useEffect(() => {
+    getAiConfig()
+      .then((cfg) => setAiConfigured(cfg.configured))
+      .catch(() => setAiConfigured(false))
+  }, [])
+
   // Reset form when dialog opens or contract changes
   useEffect(() => {
     if (!open) return
@@ -129,6 +142,28 @@ export function ContractEditorDialog({
     }
   }
 
+  const handleGenerateDescription = async () => {
+    if (!definition.trim() || !name.trim()) {
+      toast.error("Name and definition are required to generate a description")
+      return
+    }
+    setGeneratingDesc(true)
+    try {
+      const tagList = tags.split(",").map((t) => t.trim()).filter(Boolean)
+      const result = await generateDescription({
+        name,
+        type,
+        definition_yaml: definition,
+        tags: tagList.length > 0 ? tagList : undefined,
+      })
+      setDescription(result.description)
+    } catch {
+      toast.error("Failed to generate description")
+    } finally {
+      setGeneratingDesc(false)
+    }
+  }
+
   const idValid = !contractId || ID_REGEX.test(contractId)
 
   const handleSave = async () => {
@@ -233,7 +268,27 @@ export function ContractEditorDialog({
 
               <div className="grid grid-cols-2 gap-3">
                 <div className="space-y-1.5">
-                  <Label htmlFor="contract-desc">Description</Label>
+                  <div className="flex items-center gap-1.5">
+                    <Label htmlFor="contract-desc">Description</Label>
+                    {aiConfigured && (
+                      <Tooltip>
+                        <TooltipTrigger asChild>
+                          <Button
+                            variant="ghost" size="icon"
+                            className="size-5"
+                            disabled={generatingDesc || !definition.trim() || !name.trim()}
+                            onClick={handleGenerateDescription}
+                          >
+                            {generatingDesc
+                              ? <Loader2 className="size-3 animate-spin" />
+                              : <Sparkles className="size-3" />
+                            }
+                          </Button>
+                        </TooltipTrigger>
+                        <TooltipContent>Generate with AI</TooltipContent>
+                      </Tooltip>
+                    )}
+                  </div>
                   <Input id="contract-desc" value={description} onChange={(e) => setDescription(e.target.value)} placeholder="Optional" />
                 </div>
                 <div className="space-y-1.5">
diff --git a/src/edictum_server/routes/ai.py b/src/edictum_server/routes/ai.py
@@ -17,6 +17,8 @@
 from edictum_server.schemas.ai import (
     AiConfigResponse,
     AssistRequest,
+    GenerateDescriptionRequest,
+    GenerateDescriptionResponse,
     TestConnectionResponse,
     UpsertAiConfigRequest,
 )
@@ -162,6 +164,103 @@ async def test_connection(
             await provider.close()
 
 
+@router.post(
+    "/api/v1/contracts/generate-description",
+    response_model=GenerateDescriptionResponse,
+)
+async def generate_description(
+    body: GenerateDescriptionRequest,
+    auth: AuthContext = Depends(require_dashboard_auth),
+    db: AsyncSession = Depends(get_db),
+    settings: Settings = Depends(get_settings),
+) -> GenerateDescriptionResponse:
+    """Generate a one-line description for a contract from its YAML definition."""
+    config = await get_ai_config(db, auth.tenant_id)
+    if not config:
+        raise HTTPException(status_code=503, detail="AI assistant not configured")
+
+    api_key: str | None = None
+    provider = None
+    try:
+        secret = settings.get_signing_secret()
+        if config.api_key_encrypted:
+            api_key = decrypt_api_key(config.api_key_encrypted, secret)
+
+        from edictum_server.ai import create_provider
+
+        provider = create_provider(
+            provider=config.provider,
+            api_key=api_key,
+            model=config.model,
+            base_url=config.base_url,
+        )
+
+        tags_str = ", ".join(body.tags) if body.tags else "none"
+        prompt = (
+            "Generate a concise one-sentence description for this edictum contract. "
+            "The description should explain what the contract does in plain English "
+            "(what it checks and what action it takes). Do not include the contract "
+            "name or ID. Output ONLY the description text, nothing else.\n\n"
+            f"Name: {body.name}\n"
+            f"Type: {body.type}\n"
+            f"Tags: {tags_str}\n"
+            f"Definition:\n```yaml\n{body.definition_yaml}\n```"
+        )
+
+        start = time.monotonic()
+        chunks: list[str] = []
+        async for chunk in provider.stream_response(
+            messages=[{"role": "user", "content": prompt}],
+            system_prompt=(
+                "You are a technical writer for edictum, an AI agent governance system. "
+                "You write clear, concise descriptions for governance contracts. "
+                "Respond with ONLY the description — no quotes, no prefix, no explanation."
+            ),
+            max_tokens=150,
+        ):
+            chunks.append(chunk)
+            if time.monotonic() - start > 15:
+                break  # 15s safety timeout
+
+        description = "".join(chunks).strip().strip('"').strip("'")
+
+        # Log usage
+        elapsed = int((time.monotonic() - start) * 1000)
+        usage = provider.last_usage
+        if usage:
+            from edictum_server.ai.pricing import estimate_cost, fetch_model_pricing
+
+            pricing = await fetch_model_pricing(provider.model, config.provider)
+            cost = estimate_cost(usage.input_tokens, usage.output_tokens, pricing)
+            await log_usage(
+                tenant_id=auth.tenant_id,
+                provider_name=config.provider,
+                model=provider.model,
+                input_tokens=usage.input_tokens,
+                output_tokens=usage.output_tokens,
+                total_tokens=usage.input_tokens + usage.output_tokens,
+                duration_ms=elapsed,
+                cost=cost,
+            )
+
+        return GenerateDescriptionResponse(description=description)
+    except HTTPException:
+        raise
+    except Exception as exc:
+        logger.warning(
+            "AI description generation failed for tenant %s: %s",
+            auth.tenant_id,
+            exc,
+        )
+        err_msg = str(exc)
+        if api_key and api_key in err_msg:
+            err_msg = err_msg.replace(api_key, "***")
+        raise HTTPException(status_code=503, detail=err_msg) from exc
+    finally:
+        if provider:
+            await provider.close()
+
+
 @router.post("/api/v1/contracts/assist")
 async def assist(
     body: AssistRequest,
diff --git a/src/edictum_server/schemas/ai.py b/src/edictum_server/schemas/ai.py
@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+from typing import Annotated
+
 from pydantic import BaseModel, Field
 
 
@@ -47,6 +49,21 @@ class AssistRequest(BaseModel):
     current_yaml: str | None = Field(None, max_length=50_000)
 
 
+class GenerateDescriptionRequest(BaseModel):
+    """Request to generate a description from contract metadata."""
+
+    name: str = Field(..., max_length=255)
+    type: str = Field(..., max_length=32)
+    definition_yaml: str = Field(..., max_length=50_000)
+    tags: list[Annotated[str, Field(max_length=64)]] = Field(default_factory=list, max_length=20)
+
+
+class GenerateDescriptionResponse(BaseModel):
+    """AI-generated description for a contract."""
+
+    description: str
+
+
 class DailyUsage(BaseModel):
     """Aggregated AI usage for a single day."""
 
