feat(citations): add per-claim citations to AI briefs

LLM prompts updated to output {text, citation, quote} objects for every
key_point and risk. govinfo_url stored on BillBrief (migration 0006) so
the frontend can link directly to the source document without an extra
query. AIBriefCard renders § citation chips that expand inline to show
the verbatim quote and a View source → GovInfo link. Old plain-string
briefs continue to render unchanged.

Authored-By: Jack Levy

backend/alembic/versions/0006_add_brief_govinfo_url.py

@@ -0,0 +1,21 @@
+"""add govinfo_url to bill_briefs
+
+Revision ID: 0006
+Revises: 0005
+Create Date: 2026-02-28
+"""
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0006"
+down_revision = "0005"
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    op.add_column("bill_briefs", sa.Column("govinfo_url", sa.String(), nullable=True))
+
+
+def downgrade():
+    op.drop_column("bill_briefs", "govinfo_url")

backend/app/models/brief.py

@@ -14,12 +14,13 @@ class BillBrief(Base):
     document_id = Column(Integer, ForeignKey("bill_documents.id", ondelete="SET NULL"), nullable=True)
     brief_type = Column(String(20), nullable=False, server_default="full")  # full | amendment
     summary = Column(Text)
-    key_points = Column(JSONB)      # list[str]
-    risks = Column(JSONB)           # list[str]
+    key_points = Column(JSONB)      # list[{text, citation, quote}]
+    risks = Column(JSONB)           # list[{text, citation, quote}]
     deadlines = Column(JSONB)       # list[{date: str, description: str}]
     topic_tags = Column(JSONB)      # list[str]
     llm_provider = Column(String(50))
     llm_model = Column(String(100))
+    govinfo_url = Column(String, nullable=True)
     created_at = Column(DateTime(timezone=True), server_default=func.now())
 
     bill = relationship("Bill", back_populates="briefs")

backend/app/schemas/schemas.py

@@ -36,12 +36,13 @@ class BriefSchema(BaseModel):
     id: int
     brief_type: str = "full"
     summary: Optional[str] = None
-    key_points: Optional[list[str]] = None
-    risks: Optional[list[str]] = None
+    key_points: Optional[list[Any]] = None
+    risks: Optional[list[Any]] = None
     deadlines: Optional[list[dict[str, Any]]] = None
     topic_tags: Optional[list[str]] = None
     llm_provider: Optional[str] = None
     llm_model: Optional[str] = None
+    govinfo_url: Optional[str] = None
     created_at: Optional[datetime] = None
 
     model_config = {"from_attributes": True}

backend/app/services/llm_service.py

@@ -21,17 +21,24 @@ without political bias.
 Always respond with valid JSON matching exactly this schema:
 {
   "summary": "2-4 paragraph plain-language summary of what this bill does",
-  "key_points": ["specific concrete fact 1", "specific concrete fact 2"],
-  "risks": ["legitimate concern or challenge 1", "legitimate concern 2"],
+  "key_points": [
+    {"text": "specific concrete fact", "citation": "Section X(y)", "quote": "verbatim excerpt from bill ≤80 words"}
+  ],
+  "risks": [
+    {"text": "legitimate concern or challenge", "citation": "Section X(y)", "quote": "verbatim excerpt from bill ≤80 words"}
+  ],
   "deadlines": [{"date": "YYYY-MM-DD or null", "description": "what happens on this date"}],
   "topic_tags": ["healthcare", "taxation"]
 }
 
 Rules:
 - summary: Explain WHAT the bill does, not whether it is good or bad. Be factual and complete.
-- key_points: 5-10 specific, concrete things the bill changes, authorizes, or appropriates.
+- key_points: 5-10 specific, concrete things the bill changes, authorizes, or appropriates. \
+Each item MUST include "text" (your claim), "citation" (the section number, e.g. "Section 301(a)(2)"), \
+and "quote" (a verbatim excerpt of ≤80 words from that section that supports your claim).
 - risks: Legitimate concerns from any perspective — costs, implementation challenges, \
-constitutional questions, unintended consequences. Include at least 2 even for benign bills.
+constitutional questions, unintended consequences. Include at least 2 even for benign bills. \
+Each item MUST include "text", "citation", and "quote" just like key_points.
 - deadlines: Only include if explicitly stated in the text. Use null for date if a deadline \
 is mentioned without a specific date. Empty list if none.
 - topic_tags: 3-8 lowercase tags. Prefer these standard tags: healthcare, taxation, defense, \
@@ -49,8 +56,8 @@ TOKENS_PER_CHAR = 0.25  # rough approximation: 4 chars ≈ 1 token
 @dataclass
 class ReverseBrief:
     summary: str
-    key_points: list[str]
-    risks: list[str]
+    key_points: list[dict]
+    risks: list[dict]
     deadlines: list[dict]
     topic_tags: list[str]
     llm_provider: str
@@ -82,16 +89,23 @@ and you must summarize what changed between the previous and new version.
 Always respond with valid JSON matching exactly this schema:
 {
   "summary": "2-3 paragraph plain-language description of what changed in this version",
-  "key_points": ["specific change 1", "specific change 2"],
-  "risks": ["new concern introduced by this change 1", "concern 2"],
+  "key_points": [
+    {"text": "specific change", "citation": "Section X(y)", "quote": "verbatim excerpt from new version ≤80 words"}
+  ],
+  "risks": [
+    {"text": "new concern introduced by this change", "citation": "Section X(y)", "quote": "verbatim excerpt from new version ≤80 words"}
+  ],
   "deadlines": [{"date": "YYYY-MM-DD or null", "description": "new deadline added"}],
   "topic_tags": ["healthcare", "taxation"]
 }
 
 Rules:
 - summary: Focus ONLY on what is different from the previous version. Be specific.
-- key_points: List concrete additions, removals, or modifications in this version.
-- risks: Only include risks that are new or changed relative to the previous version.
+- key_points: List concrete additions, removals, or modifications in this version. \
+Each item MUST include "text" (your claim), "citation" (the section number, e.g. "Section 301(a)(2)"), \
+and "quote" (a verbatim excerpt of ≤80 words from the NEW version that supports your claim).
+- risks: Only include risks that are new or changed relative to the previous version. \
+Each item MUST include "text", "citation", and "quote" just like key_points.
 - deadlines: Only new or changed deadlines. Empty list if none.
 - topic_tags: Same standard tags as before — include any new topics this version adds.
 

backend/app/workers/llm_processor.py

@@ -86,6 +86,7 @@ def process_document_with_llm(self, document_id: int):
             topic_tags=brief.topic_tags,
             llm_provider=brief.llm_provider,
             llm_model=brief.llm_model,
+            govinfo_url=doc.govinfo_url,
         )
         db.add(db_brief)
         db.commit()

frontend/components/bills/AIBriefCard.tsx

@@ -1,14 +1,74 @@
 "use client";
 
-import { AlertTriangle, CheckCircle, Clock, Cpu, Tag } from "lucide-react";
-import { BriefSchema } from "@/lib/types";
+import { useState } from "react";
+import { AlertTriangle, CheckCircle, Clock, Cpu, ExternalLink, Tag } from "lucide-react";
+import { BriefSchema, CitedPoint } from "@/lib/types";
 import { formatDate } from "@/lib/utils";
 
 interface AIBriefCardProps {
   brief?: BriefSchema | null;
 }
 
+function isCited(p: string | CitedPoint): p is CitedPoint {
+  return typeof p === "object" && p !== null && "text" in p;
+}
+
+interface CitedItemProps {
+  point: string | CitedPoint;
+  icon: React.ReactNode;
+  govinfo_url?: string;
+  openKey: string;
+  activeKey: string | null;
+  setActiveKey: (key: string | null) => void;
+}
+
+function CitedItem({ point, icon, govinfo_url, openKey, activeKey, setActiveKey }: CitedItemProps) {
+  const cited = isCited(point);
+  const isOpen = activeKey === openKey;
+
+  return (
+    <li className="text-sm">
+      <div className="flex items-start gap-2">
+        <span className="mt-0.5 shrink-0">{icon}</span>
+        <span className="flex-1">{cited ? point.text : point}</span>
+        {cited && (
+          <button
+            onClick={() => setActiveKey(isOpen ? null : openKey)}
+            title={isOpen ? "Hide source" : "View source"}
+            className={`shrink-0 text-xs px-1.5 py-0.5 rounded font-mono transition-colors ${
+              isOpen
+                ? "bg-primary text-primary-foreground"
+                : "bg-muted text-muted-foreground hover:bg-accent hover:text-foreground"
+            }`}
+          >
+            § {point.citation}
+          </button>
+        )}
+      </div>
+      {cited && isOpen && (
+        <div className="mt-2 ml-5 rounded-md border border-border bg-muted/40 p-3 space-y-2">
+          <blockquote className="text-xs text-muted-foreground italic leading-relaxed border-l-2 border-primary pl-3">
+            "{point.quote}"
+          </blockquote>
+          {govinfo_url && (
+            <a
+              href={govinfo_url}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="inline-flex items-center gap-1 text-xs text-primary hover:underline"
+            >
+              View source <ExternalLink className="w-3 h-3" />
+            </a>
+          )}
+        </div>
+      )}
+    </li>
+  );
+}
+
 export function AIBriefCard({ brief }: AIBriefCardProps) {
+  const [activeKey, setActiveKey] = useState<string | null>(null);
+
   if (!brief) {
     return (
       <div className="bg-card border border-border rounded-lg p-6">
@@ -45,12 +105,17 @@ export function AIBriefCard({ brief }: AIBriefCardProps) {
       {brief.key_points && brief.key_points.length > 0 && (
         <div>
           <h3 className="text-xs font-semibold uppercase tracking-wide text-muted-foreground mb-2">Key Points</h3>
-          <ul className="space-y-1.5">
+          <ul className="space-y-2">
             {brief.key_points.map((point, i) => (
-              <li key={i} className="flex items-start gap-2 text-sm">
-                <CheckCircle className="w-3.5 h-3.5 mt-0.5 text-green-500 shrink-0" />
-                <span>{point}</span>
-              </li>
+              <CitedItem
+                key={i}
+                point={point}
+                icon={<CheckCircle className="w-3.5 h-3.5 text-green-500" />}
+                govinfo_url={brief.govinfo_url}
+                openKey={`kp-${i}`}
+                activeKey={activeKey}
+                setActiveKey={setActiveKey}
+              />
             ))}
           </ul>
         </div>
@@ -59,12 +124,17 @@ export function AIBriefCard({ brief }: AIBriefCardProps) {
       {brief.risks && brief.risks.length > 0 && (
         <div>
           <h3 className="text-xs font-semibold uppercase tracking-wide text-muted-foreground mb-2">Risks & Concerns</h3>
-          <ul className="space-y-1.5">
+          <ul className="space-y-2">
             {brief.risks.map((risk, i) => (
-              <li key={i} className="flex items-start gap-2 text-sm">
-                <AlertTriangle className="w-3.5 h-3.5 mt-0.5 text-yellow-500 shrink-0" />
-                <span>{risk}</span>
-              </li>
+              <CitedItem
+                key={i}
+                point={risk}
+                icon={<AlertTriangle className="w-3.5 h-3.5 text-yellow-500" />}
+                govinfo_url={brief.govinfo_url}
+                openKey={`risk-${i}`}
+                activeKey={activeKey}
+                setActiveKey={setActiveKey}
+              />
             ))}
           </ul>
         </div>

frontend/lib/types.ts

@@ -10,15 +10,23 @@ export interface Member {
   photo_url?: string;
 }
 
+export interface CitedPoint {
+  text: string;
+  citation: string;
+  quote: string;
+}
+
 export interface BriefSchema {
   id: number;
+  brief_type?: string;
   summary?: string;
-  key_points?: string[];
-  risks?: string[];
+  key_points?: (string | CitedPoint)[];
+  risks?: (string | CitedPoint)[];
   deadlines?: { date: string | null; description: string }[];
   topic_tags?: string[];
   llm_provider?: string;
   llm_model?: string;
+  govinfo_url?: string;
   created_at?: string;
 }