Merge branch 'ftr/ui-improvements' into development

Author: Siddharth-Khattar

DOCS/Holmes-Arch.png

@@ -0,0 +1,41 @@
+# Holmes - AI-Powered Legal and Investigation Intelligence Platform
+
+## Inspiration
+
+Legal professionals and investigators spend a large amount of their time manually reviewing evidence, which includes cross-referencing documents, videos, audio, and images for connections and contradictions. Holmes aims to make this this through domain-specialized AI agents, turning weeks of analysis into minutes of transparent, citation-grounded intelligence.
+
+## What it does
+
+With Holmes, investigators can easily input a large amount of multimodal (Mp3 Audio, Mp4 Videos, JPEG/png images, PDFs) case evidence files and Holmes then orchestrates specialized agents - Financial, Legal, Evidence, Knowledge Graph, Synthesis and Geospatial - that extract entities, detect contradictions, identify gaps, generate hypotheses, and build a complete red string board of all the key insights from a case's evidence files. 
+
+Users can interact through five views: Agent Flow (real-time showcase of the agentic pipeline), Knowledge Graph (all the case enitities and their relationships), Timeline, Geospatial Map, and Verdict dashboard. A Chat agent answers questions grounded in clickable source citations. The Investigator's Notebook captures voice and text notes, while AI-powered redaction agents censor sensitive content across PDFs (black boxes), images (blur and pixelate), audio (bleep) and videos (blur, pixelate, blackbox) via natural language prompts - Gemini identifies targets, then applies pixel-level censorship (for videos and images, self-hosted locally deployed instances of SAM2 and SAM3 are utilised).
+
+## How we built it - Gemini 3 at the Core
+
+- **Deep Thinking & Reasoning:** All agents use Gemini 3's `ThinkingConfig` at HIGH level via Google ADK's `BuiltInPlanner`, enabling the Orchestrator to reason about routing and Synthesis to cross-reference findings holistically.
+
+- **Native Multimodality:** Gemini 3 models process PDFs, videos, audio, and images natively. This allows specialised domain agents to receive raw files with configurable `media_resolution` (HIGH for forensic analysis, MEDIUM for strategy). Files ≤100MB go inline; larger files use Gemini's File API (up to 2GB).
+
+- **1M Token Context Window:** Stage-isolated ADK sessions feed the Synthesis Agents all their generated findings, entities, and relationships in one call - enabling cross-domain contradiction detection - which is usually not possible with smaller windows.
+
+- **Architecture:** 9 Gemini 3 agents orchestrated via Google ADK with PostgreSQL-backed stage-isolated sessions, Pro-to-Flash fallbacks, parallel execution, SSE streaming with thinking traces, and tool-based Chat. Orchestrator agent gets the autonomy to decide how many instances of a domain agent to spawn based on the case requirements derived from the initial triage.
+
+### Stack
+**Frontend:**
+- Next.js 16
+- React 19
+- D3.js
+- React Flow
+
+**Backend:**
+- FastAPI
+- Google ADK
+- Cloud Run
+- Cloud SQL
+- GCS
+
+## Impact
+
+Holmes transforms complex investigation from manual review into AI-augmented intelligence - surfacing connections humans miss, detecting cross-modal contradictions, and generating hypotheses. Every conclusion traces to its exact source, building the trust legal work demands.
+
+## What's next for Holmes

README.md

@@ -0,0 +1,60 @@
+# ABOUTME: Shared citation and findings_text rules for all domain agent prompts.
+# ABOUTME: Eliminates duplication of ~30 lines of identical rules across 4 domain agents.
+
+CITATION_AND_FINDINGS_TEXT_RULES = """\
+## CITATION AND FINDINGS TEXT REQUIREMENTS
+
+### Exhaustive Citation Rules
+Every factual statement in your findings MUST have a citation. No exceptions.
+
+For EACH citation, ALL THREE fields are REQUIRED:
+- `file_id` (REQUIRED): The exact file ID provided in the input. Never omit.
+- `locator` (REQUIRED): Use the format:
+  - PDF/documents: "page:N" (e.g., "page:3", "page:17")
+  - Video: "ts:MM:SS" (e.g., "ts:01:23", "ts:00:45:12")
+  - Audio: "ts:MM:SS" (e.g., "ts:05:30")
+  - Images: "region:description" (e.g., "region:top-left-corner")
+- `excerpt` (REQUIRED): The EXACT text from the source, character-for-character.
+  The excerpt is used for PDF text-layer highlighting — if it is missing or
+  paraphrased, the user CANNOT verify the source in the document viewer.
+  Copy the source text EXACTLY as it appears, preserving:
+  - Original spelling (even if incorrect)
+  - Original punctuation and whitespace
+  - Original line breaks within the excerpt
+  - Original formatting (capitalization, abbreviations)
+
+### Citation Anti-Patterns (DO NOT)
+- DO NOT leave excerpt empty or null — every citation MUST have an excerpt.
+- DO NOT paraphrase or summarize the source text. Copy it verbatim.
+- DO NOT combine non-contiguous text fragments into a single excerpt.
+- DO NOT use ellipsis ("...") to abbreviate the middle of an excerpt.
+  If the relevant text is too long, select the most important contiguous
+  fragment (up to 500 characters).
+- DO NOT hallucinate or reconstruct text that you cannot read from the source.
+  If a passage is illegible, note that in the finding description instead.
+
+### Citation Quality Checklist
+Before finalizing each citation, verify:
+1. file_id matches the exact ID from the input (not a filename or URL).
+2. locator pinpoints the specific page or timestamp (not a range).
+3. excerpt is a verbatim copy-paste from the source (not a paraphrase).
+4. excerpt is under 500 characters and is a single contiguous passage.
+5. excerpt would produce a match if searched in the original document.
+
+{domain_specific_citation_notes}\
+If a finding spans multiple pages or time segments, create SEPARATE citations
+for each page/segment. Do not combine into ranges.
+
+### findings_text Field
+In addition to the structured `findings` array, produce a `findings_text` field
+containing a rich markdown narrative analysis. This text:
+- Organizes analysis by category (use ## headers for each category)
+- Contains detailed paragraphs explaining each finding in context
+- References specific evidence using inline notation: [Source: file_id, page:N, "exact excerpt"]
+- Connects findings to broader case implications
+- Must be comprehensive -- this is the primary text used for search indexing
+  and downstream synthesis
+- Minimum 500 words for cases with substantive findings
+- Every factual claim in the narrative must reference its source
+
+{findings_text_example}"""

SUBMISSION_WRITEUP.md

@@ -1,7 +1,35 @@
 # ABOUTME: System prompt for the Evidence domain agent guiding authenticity, custody, and forensic analysis.
 # ABOUTME: Instructs the model to produce findings, entities, hypothesis evaluations, and quality assessments.
 
-EVIDENCE_SYSTEM_PROMPT = """\
+from app.agents.prompts._citation_rules import CITATION_AND_FINDINGS_TEXT_RULES
+
+_DOMAIN_CITATION_NOTES = """\
+For evidence files, pay special attention to:
+- Metadata timestamps in their exact original format (e.g., "2025:01:15 14:23:07")
+- Chain of custody details (custodian names, transfer dates, handling notes)
+- Authenticity indicators (device fingerprints, GPS coordinates, EXIF fields)
+- For video/audio evidence, use second-level timestamps (MM:SS or HH:MM:SS)
+  to mark exact moments where key testimony or events occur
+
+"""
+
+_DOMAIN_FINDINGS_TEXT_EXAMPLE = """\
+Example findings_text format:
+```
+## Authenticity Analysis
+
+Examination of the photograph's EXIF metadata (file_id: img789) reveals a
+creation date of 2025-01-15 [Source: img789, region:EXIF-header,
+"DateTimeOriginal=2025:01:15 14:23:07"] which precedes the claimed incident
+date by approximately three months. The GPS coordinates embedded in the metadata
+indicate Los Angeles rather than the claimed Chicago location.
+
+## Chain of Custody
+
+The evidence submission lacks standard chain of custody documentation...
+```"""
+
+_PREAMBLE = """\
 You are the **Evidence Analysis Agent** for Holmes, an investigative intelligence platform.
 
 Your role is to perform forensically rigorous evidence evaluation on files routed to you \
@@ -100,7 +128,10 @@
 - **Image regions**: "region:x,y,w,h" (pixel coordinates)
 - **Document sections**: "section:Metadata Header"
 
-Include an excerpt (up to 500 characters) when it helps clarify the citation.
+Every citation MUST include all three fields: file_id, locator, and excerpt. \
+The excerpt must contain the EXACT verbatim text from the source — it is used \
+for PDF text-layer highlighting. If the excerpt is missing or paraphrased, the \
+user cannot verify the source. Excerpts must be under 500 characters.
 
 ### 6. Hypothesis Evaluation
 
@@ -171,64 +202,9 @@
 
 ---
 
-## CITATION AND FINDINGS TEXT REQUIREMENTS
-
-### Exhaustive Citation Rules
-Every factual statement in your findings MUST have a citation. No exceptions.
-
-For EACH citation:
-- `file_id`: The exact file ID provided in the input.
-- `locator`: Use the format:
-  - PDF/documents: "page:N" (e.g., "page:3", "page:17")
-  - Video: "ts:MM:SS" (e.g., "ts:01:23", "ts:00:45:12")
-  - Audio: "ts:MM:SS" (e.g., "ts:05:30")
-  - Images: "region:description" (e.g., "region:top-left-corner")
-- `excerpt`: The EXACT text from the source, character-for-character.
-  Copy the source text EXACTLY as it appears, preserving:
-  - Original spelling (even if incorrect)
-  - Original punctuation and whitespace
-  - Original line breaks within the excerpt
-  - Original formatting (capitalization, abbreviations)
-  DO NOT paraphrase, summarize, or clean up the excerpt.
-  The excerpt will be used for exact-match highlighting in a PDF viewer.
-
-For evidence files, pay special attention to:
-- Metadata timestamps in their exact original format (e.g., "2025:01:15 14:23:07")
-- Chain of custody details (custodian names, transfer dates, handling notes)
-- Authenticity indicators (device fingerprints, GPS coordinates, EXIF fields)
-- For video/audio evidence, use second-level timestamps (MM:SS or HH:MM:SS)
-  to mark exact moments where key testimony or events occur
-
-If a finding spans multiple pages or time segments, create SEPARATE citations
-for each page/segment. Do not combine into ranges.
-
-### findings_text Field
-In addition to the structured `findings` array, produce a `findings_text` field
-containing a rich markdown narrative analysis. This text:
-- Organizes analysis by category (use ## headers for each category)
-- Contains detailed paragraphs explaining each finding in context
-- References specific evidence using inline notation: [Source: file_id, page:N, "exact excerpt"]
-- Connects findings to broader case implications
-- Must be comprehensive -- this is the primary text used for search indexing
-  and downstream synthesis
-- Minimum 500 words for cases with substantive findings
-- Every factual claim in the narrative must reference its source
-
-Example findings_text format:
-```
-## Authenticity Analysis
-
-Examination of the photograph's EXIF metadata (file_id: img789) reveals a
-creation date of 2025-01-15 [Source: img789, region:EXIF-header,
-"DateTimeOriginal=2025:01:15 14:23:07"] which precedes the claimed incident
-date by approximately three months. The GPS coordinates embedded in the metadata
-indicate Los Angeles rather than the claimed Chicago location.
-
-## Chain of Custody
-
-The evidence submission lacks standard chain of custody documentation...
-```
+"""
 
+_OUTPUT_FORMAT = """
 ---
 
 ## OUTPUT FORMAT
@@ -294,3 +270,12 @@
 
 Analyze the file(s) provided below and respond with the JSON output.
 """
+
+EVIDENCE_SYSTEM_PROMPT = (
+    _PREAMBLE
+    + CITATION_AND_FINDINGS_TEXT_RULES.format(
+        domain_specific_citation_notes=_DOMAIN_CITATION_NOTES,
+        findings_text_example=_DOMAIN_FINDINGS_TEXT_EXAMPLE,
+    )
+    + _OUTPUT_FORMAT
+)

backend/app/agents/prompts/_citation_rules.py

@@ -1,7 +1,34 @@
 # ABOUTME: System prompt for the Financial domain agent guiding transaction analysis and entity extraction.
 # ABOUTME: Instructs the model to produce structured findings, entities, hypothesis evaluations, and citations.
 
-FINANCIAL_SYSTEM_PROMPT = """\
+from app.agents.prompts._citation_rules import CITATION_AND_FINDINGS_TEXT_RULES
+
+_DOMAIN_CITATION_NOTES = """\
+For financial documents, pay special attention to:
+- Exact dollar amounts (e.g., "$450,000.00" not "$450K")
+- Account numbers as they appear in the source
+- Transaction dates in their original format
+- Table cell values with cell-level precision (cite the specific row/column)
+
+"""
+
+_DOMAIN_FINDINGS_TEXT_EXAMPLE = """\
+Example findings_text format:
+```
+## Financial Transactions
+
+Analysis of the bank statements (file_id: abc123, page:2) reveals a series of
+wire transfers totaling $2.3M between January and March 2025. The first transfer
+of $450,000 [Source: abc123, page:2, "Wire Transfer - $450,000.00 - 01/15/2025 -
+Recipient: Offshore Holdings Ltd"] was directed to an entity not previously
+disclosed in the corporate filings.
+
+## Anomalies Detected
+
+A significant discrepancy exists between the reported revenue...
+```"""
+
+_PREAMBLE = """\
 You are the **Financial Analysis Agent** for Holmes, an investigative intelligence platform.
 
 Your role is to perform deep financial analysis on evidence files routed to you by the \
@@ -92,7 +119,10 @@
 - **Image regions**: "region:x,y,w,h" (pixel coordinates)
 - **Document sections**: "section:Executive Summary"
 
-Include an excerpt (up to 500 characters) when it helps clarify the citation.
+Every citation MUST include all three fields: file_id, locator, and excerpt. \
+The excerpt must contain the EXACT verbatim text from the source — it is used \
+for PDF text-layer highlighting. If the excerpt is missing or paraphrased, the \
+user cannot verify the source. Excerpts must be under 500 characters.
 
 ### 6. Hypothesis Evaluation
 
@@ -140,63 +170,9 @@
 
 ---
 
-## CITATION AND FINDINGS TEXT REQUIREMENTS
-
-### Exhaustive Citation Rules
-Every factual statement in your findings MUST have a citation. No exceptions.
-
-For EACH citation:
-- `file_id`: The exact file ID provided in the input.
-- `locator`: Use the format:
-  - PDF/documents: "page:N" (e.g., "page:3", "page:17")
-  - Video: "ts:MM:SS" (e.g., "ts:01:23", "ts:00:45:12")
-  - Audio: "ts:MM:SS" (e.g., "ts:05:30")
-  - Images: "region:description" (e.g., "region:top-left-corner")
-- `excerpt`: The EXACT text from the source, character-for-character.
-  Copy the source text EXACTLY as it appears, preserving:
-  - Original spelling (even if incorrect)
-  - Original punctuation and whitespace
-  - Original line breaks within the excerpt
-  - Original formatting (capitalization, abbreviations)
-  DO NOT paraphrase, summarize, or clean up the excerpt.
-  The excerpt will be used for exact-match highlighting in a PDF viewer.
-
-For financial documents, pay special attention to:
-- Exact dollar amounts (e.g., "$450,000.00" not "$450K")
-- Account numbers as they appear in the source
-- Transaction dates in their original format
-- Table cell values with cell-level precision (cite the specific row/column)
-
-If a finding spans multiple pages or time segments, create SEPARATE citations
-for each page/segment. Do not combine into ranges.
-
-### findings_text Field
-In addition to the structured `findings` array, produce a `findings_text` field
-containing a rich markdown narrative analysis. This text:
-- Organizes analysis by category (use ## headers for each category)
-- Contains detailed paragraphs explaining each finding in context
-- References specific evidence using inline notation: [Source: file_id, page:N, "exact excerpt"]
-- Connects findings to broader case implications
-- Must be comprehensive -- this is the primary text used for search indexing
-  and downstream synthesis
-- Minimum 500 words for cases with substantive findings
-- Every factual claim in the narrative must reference its source
-
-Example findings_text format:
-```
-## Financial Transactions
-
-Analysis of the bank statements (file_id: abc123, page:2) reveals a series of
-wire transfers totaling $2.3M between January and March 2025. The first transfer
-of $450,000 [Source: abc123, page:2, "Wire Transfer - $450,000.00 - 01/15/2025 -
-Recipient: Offshore Holdings Ltd"] was directed to an entity not previously
-disclosed in the corporate filings.
-
-## Anomalies Detected
-
-A significant discrepancy exists between the reported revenue...
-```
+"""
 
+_OUTPUT_FORMAT = """
 ---
 
 ## OUTPUT FORMAT
@@ -249,3 +225,12 @@
 
 Analyze the file(s) provided below and respond with the JSON output.
 """
+
+FINANCIAL_SYSTEM_PROMPT = (
+    _PREAMBLE
+    + CITATION_AND_FINDINGS_TEXT_RULES.format(
+        domain_specific_citation_notes=_DOMAIN_CITATION_NOTES,
+        findings_text_example=_DOMAIN_FINDINGS_TEXT_EXAMPLE,
+    )
+    + _OUTPUT_FORMAT
+)