feat: update citation format to include workgroup names

- Modified citation format across multiple components to replace 'speaker' with 'workgroup_name' for consistency.
- Updated the constitution document to reflect the new citation format requirements.
- Enhanced citation extraction and scoring logic to accommodate the new workgroup-based citations.
- Adjusted related services and models to ensure proper handling of workgroup information in citations.

Author: stephen-rowan

.specify/memory/constitution.md

@@ -38,7 +38,7 @@ The system must ground all outputs strictly in archived meeting data.
 
 Every generated statement shall be supported by verifiable citation.
 
-- Required format: [meeting_id | date | speaker]
+- Required format: [meeting_id | date | workgroup_name]
 - Each answer includes retrieved text + provenance metadata
 - Citations are non-optional, non-negotiable
 
@@ -93,7 +93,7 @@ All actions must be visible and reviewable.
 - System MUST extract structured entities from meeting records (meetings, workgroups, people, documents, agenda items, decision items, action items)
 - Entity storage MUST be local-first: JSON files in `entities/` directory structure (no external database dependencies)
 - Entity relationships MUST maintain referential integrity (foreign key validation, cascade delete behaviors)
-- Entity extraction MUST preserve traceability to source meeting records (meeting_id, date, speaker relationships)
+- Entity extraction MUST preserve traceability to source meeting records (meeting_id, date, workgroup relationships)
 - System MUST support dual querying: structured entity queries (quantitative counts, relationship navigation) AND vector similarity search (qualitative RAG queries)
 - Entity extraction MUST be deterministic: same meeting record produces identical entity structure and relationships
 - Entity storage operations MUST be atomic (temporary file + rename pattern for writes, backup/restore for deletes)

src/models/evaluation_case.py

@@ -13,7 +13,7 @@ class EvaluationCase(BaseModel):
         case_id: Unique evaluation case identifier
         prompt: Test query prompt
         ground_truth: Expected answer content
-        expected_citations: Expected citations in format [meeting_id | date | speaker]
+        expected_citations: Expected citations in format [meeting_id | date | workgroup_name]
         evaluation_metrics: Scoring results
         run_timestamp: Evaluation run timestamp
         model_version: LLM version used for evaluation
@@ -25,7 +25,7 @@ class EvaluationCase(BaseModel):
     ground_truth: str = Field(..., description="Expected answer content")
     expected_citations: List[Dict[str, Any]] = Field(
         ...,
-        description="Expected citations in format [meeting_id | date | speaker]"
+        description="Expected citations in format [meeting_id | date | workgroup_name]"
     )
     evaluation_metrics: Optional[Dict[str, Any]] = Field(
         None,
@@ -55,7 +55,7 @@ class Config:
                     {
                         "meeting_id": "meeting_001",
                         "date": "2024-03-15",
-                        "speaker": "Alice",
+                        "workgroup_name": "Budget Committee",
                         "excerpt": "budget allocation"
                     }
                 ],

src/models/rag_query.py

@@ -15,11 +15,11 @@ class RetrievedChunk(BaseModel):
 
 
 class Citation(BaseModel):
-    """Citation in format [meeting_id | date | speaker]."""
+    """Citation in format [meeting_id | date | workgroup_name]."""
 
     meeting_id: str = Field(..., description="Meeting identifier")
     date: str = Field(..., description="Meeting date")
-    speaker: Optional[str] = Field(None, description="Speaker name")
+    workgroup_name: Optional[str] = Field(None, description="Workgroup name")
     excerpt: str = Field(..., description="Cited text excerpt")
 
 
@@ -33,7 +33,7 @@ class RAGQuery(BaseModel):
         timestamp: Query execution timestamp
         retrieved_chunks: Retrieved document chunks with metadata
         output: Generated answer text
-        citations: Verifiable citations in format [meeting_id | date | speaker]
+        citations: Verifiable citations in format [meeting_id | date | workgroup_name]
         model_version: Version of LLM used for generation
         embedding_version: Version of embedding model used
         user_id: SSO user identifier (optional)
@@ -82,7 +82,7 @@ class Config:
                     {
                         "meeting_id": "meeting_001",
                         "date": "2024-03-15",
-                        "speaker": "Alice",
+                        "workgroup_name": "Budget Committee",
                         "excerpt": "The budget committee decided..."
                     }
                 ],

src/services/audit_writer.py

@@ -54,7 +54,7 @@ def write_query_audit_log(self, rag_query: RAGQuery) -> Path:
                 {
                     "meeting_id": citation.meeting_id,
                     "date": citation.date,
-                    "speaker": citation.speaker,
+                    "workgroup_name": citation.workgroup_name,
                     "excerpt": citation.excerpt
                 }
                 for citation in rag_query.citations

src/services/chunking.py

@@ -80,7 +80,9 @@ def chunk_transcript(
         "date": meeting_record.date,
         "participants": meeting_record.participants,
         "decisions": meeting_record.decisions,
-        "tags": meeting_record.tags
+        "tags": meeting_record.tags,
+        "workgroup": getattr(meeting_record, "workgroup", None),
+        "workgroup_id": getattr(meeting_record, "workgroup_id", None)
     }
 
     # Chunk transcript with overlap

src/services/citation_extractor.py

@@ -1,18 +1,55 @@
 """Citation extraction service."""
 
-from typing import List, Dict, Any
+from typing import List, Dict, Any, Optional
 from datetime import datetime
+from uuid import UUID
 
 from ..models.rag_query import Citation
 from ..lib.citation import format_citation
 from ..lib.logging import get_logger
+from ..lib.config import ENTITIES_MEETINGS_DIR, ENTITIES_WORKGROUPS_DIR
+from ..services.entity_storage import load_entity
+from ..models.meeting import Meeting
+from ..models.workgroup import Workgroup
 
 logger = get_logger(__name__)
 
 
+def _get_workgroup_name_from_meeting(meeting_id: str) -> Optional[str]:
+    """
+    Get workgroup name from meeting ID.
+    
+    Args:
+        meeting_id: Meeting identifier (UUID string)
+        
+    Returns:
+        Workgroup name if found, None otherwise
+    """
+    if not meeting_id or meeting_id in ("entity-storage", "quantitative-analysis", "no-evidence"):
+        return None
+    
+    try:
+        meeting_uuid = UUID(meeting_id)
+        meeting = load_entity(meeting_uuid, ENTITIES_MEETINGS_DIR, Meeting)
+        if meeting and meeting.workgroup_id:
+            workgroup = load_entity(meeting.workgroup_id, ENTITIES_WORKGROUPS_DIR, Workgroup)
+            if workgroup:
+                logger.debug("workgroup_name_found", meeting_id=meeting_id, workgroup_name=workgroup.name)
+                return workgroup.name
+            else:
+                logger.debug("workgroup_not_found", meeting_id=meeting_id, workgroup_id=str(meeting.workgroup_id))
+        else:
+            logger.debug("meeting_or_workgroup_id_missing", meeting_id=meeting_id, has_meeting=meeting is not None)
+    except ValueError as e:
+        logger.debug("invalid_meeting_id_format", meeting_id=meeting_id, error=str(e))
+    except (AttributeError, Exception) as e:
+        logger.debug("workgroup_name_lookup_failed", meeting_id=meeting_id, error=str(e))
+    return None
+
+
 def extract_citations(retrieved_chunks: List[Dict[str, Any]]) -> List[Citation]:
     """
-    Extract citations from retrieved chunks in format [meeting_id | date | speaker].
+    Extract citations from retrieved chunks in format [meeting_id | date | workgroup_name].
     
     Args:
         retrieved_chunks: List of retrieved chunk dictionaries with metadata
@@ -26,10 +63,13 @@ def extract_citations(retrieved_chunks: List[Dict[str, Any]]) -> List[Citation]:
         metadata = chunk.get("metadata", {})
         meeting_id = metadata.get("meeting_id", chunk.get("meeting_id", ""))
         date = metadata.get("date", "")
-        participants = metadata.get("participants", [])
 
-        # Extract speaker (use first participant or leave empty)
-        speaker = participants[0] if participants else None
+        # Try to get workgroup name from metadata first (from FAISS index)
+        workgroup_name = metadata.get("workgroup")
+        
+        # If not in metadata, try to look up from entity storage
+        if not workgroup_name and meeting_id:
+            workgroup_name = _get_workgroup_name_from_meeting(meeting_id)
 
         # Extract excerpt (chunk text)
         excerpt = chunk.get("text", "")
@@ -42,7 +82,7 @@ def extract_citations(retrieved_chunks: List[Dict[str, Any]]) -> List[Citation]:
         citation = Citation(
             meeting_id=meeting_id,
             date=date,
-            speaker=speaker,
+            workgroup_name=workgroup_name,
             excerpt=excerpt[:200] + "..." if len(excerpt) > 200 else excerpt  # Truncate long excerpts
         )
 
@@ -66,7 +106,7 @@ def create_no_evidence_citation(index_name: str) -> Citation:
     return Citation(
         meeting_id="no-evidence",
         date=datetime.utcnow().strftime("%Y-%m-%d"),
-        speaker="System",
+        workgroup_name=None,
         excerpt=f"No evidence found in retrieved chunks. RAG query searched index '{index_name}' but found no relevant results above the similarity threshold."
     )
 
@@ -79,7 +119,7 @@ def format_citations_as_text(citations: List[Citation]) -> str:
         citations: List of Citation objects
         
     Returns:
-        Formatted citation text
+        Formatted citation text (only citation format, no excerpt)
     """
     if not citations:
         return ""
@@ -89,9 +129,9 @@ def format_citations_as_text(citations: List[Citation]) -> str:
         citation_str = format_citation(
             citation.meeting_id,
             citation.date,
-            citation.speaker
+            citation.workgroup_name
         )
-        citation_lines.append(f"- {citation_str}: {citation.excerpt}")
+        citation_lines.append(f"- {citation_str}")
 
     return "\n".join(citation_lines)
 

src/services/citation_scorer.py

@@ -33,7 +33,7 @@ def score_citation_accuracy(
             if validate_citation_format(format_citation(
                 citation.meeting_id,
                 citation.date,
-                citation.speaker
+                citation.workgroup_name
             ))
         )
         return valid_count / len(actual_citations) if actual_citations else 0.0
@@ -44,13 +44,13 @@ def score_citation_accuracy(
     for expected in expected_citations:
         expected_meeting_id = expected.get("meeting_id", "")
         expected_date = expected.get("date", "")
-        expected_speaker = expected.get("speaker")
+        expected_workgroup_name = expected.get("workgroup_name")
 
         # Find matching actual citation
         for actual in actual_citations:
             if (actual.meeting_id == expected_meeting_id and
                 actual.date == expected_date and
-                (not expected_speaker or actual.speaker == expected_speaker)):
+                (not expected_workgroup_name or actual.workgroup_name == expected_workgroup_name)):
                 matched_count += 1
                 break
 

src/services/entity_query.py

@@ -250,8 +250,9 @@ def get_documents_by_meeting_with_validation(self, meeting_id: UUID) -> List[Doc
         Raises:
             ValueError: If entity loading fails
         """
-        import requests
         from urllib.parse import urlparse
+        from urllib.request import urlopen, Request
+        from urllib.error import URLError, HTTPError
 
         logger.info("query_documents_by_meeting_with_validation_start", meeting_id=str(meeting_id))
 
@@ -270,17 +271,19 @@ def get_documents_by_meeting_with_validation(self, meeting_id: UUID) -> List[Doc
                         validated_documents.append(document)
                         continue
 
-                    # Attempt HEAD request to validate accessibility
+                    # Attempt HEAD request to validate accessibility using standard library
                     try:
-                        response = requests.head(str(document.link), timeout=5, allow_redirects=True)
-                        is_accessible = response.status_code < 400
-                        if not is_accessible:
-                            logger.warning("query_documents_link_inaccessible", document_id=str(document.id), link=str(document.link), status_code=response.status_code)
-                        # Still include document even if link is inaccessible (FR-012)
-                        validated_documents.append(document)
-                    except (requests.RequestException, Exception) as e:
+                        req = Request(str(document.link), method='HEAD')
+                        with urlopen(req, timeout=5) as response:
+                            is_accessible = response.status < 400
+                            if not is_accessible:
+                                logger.warning("query_documents_link_inaccessible", document_id=str(document.id), link=str(document.link), status_code=response.status)
+                            # Still include document even if link is inaccessible (FR-012)
+                            validated_documents.append(document)
+                    except (URLError, HTTPError, Exception) as e:
                         # Link validation failed but don't block retrieval
-                        logger.warning("query_documents_link_validation_failed", document_id=str(document.id), link=str(document.link), error=str(e))
+                        status_code = getattr(e, 'code', None) if isinstance(e, HTTPError) else None
+                        logger.warning("query_documents_link_validation_failed", document_id=str(document.id), link=str(document.link), error=str(e), status_code=status_code)
                         validated_documents.append(document)
 
                 except Exception as e:

src/services/query_service.py

@@ -278,7 +278,7 @@ def execute_query(
                 citations.append(Citation(
                     meeting_id="entity-storage",
                     date=datetime.utcnow().strftime("%Y-%m-%d"),
-                    speaker="System",
+                    workgroup_name=None,
                     excerpt=f"Counted {count} meetings by scanning JSON files in {source}. Method: {method}."
                 ))
 
@@ -293,7 +293,7 @@ def execute_query(
                 citations.append(Citation(
                     meeting_id="quantitative-analysis",
                     date=datetime.utcnow().strftime("%Y-%m-%d"),
-                    speaker="System",
+                    workgroup_name=None,
                     excerpt=f"Quantitative analysis performed. Method: {method}. Source: {source}."
                 ))
 
@@ -304,7 +304,7 @@ def execute_query(
                             citations.append(Citation(
                                 meeting_id=cit.get("type", "quantitative"),
                                 date=datetime.utcnow().strftime("%Y-%m-%d"),
-                                speaker="System",
+                                workgroup_name=None,
                                 excerpt=cit.get("description", f"Method: {cit.get('method', method)}")
                             ))
             else: