AI Tools Integration
Relevant source files
The following files were used as context for generating this wiki page:
The AI Tools Integration in Poneglyph provides a comprehensive humanitarian intelligence analysis system. It leverages large language models (LLMs) specialized as "Poneglyph Research Assistants" to synthesize insights from internal humanitarian datasets and external web sources. The system is designed to support NGO workers and researchers in making data-driven decisions during crises.
Sources: apps/server/src/agents/prompts/system.ts:1-7
Core Agent Architecture
The system utilizes an orchestrator model that manages three primary capabilities: internal database semantic search, real-time grounded web search, and multi-step deep research. Each capability is encapsulated as a specialized tool that the LLM can invoke based on the user's query requirements.
Sources: apps/server/src/agents/prompts/system.ts:9-24
Tools and Capabilities
The following table outlines the primary AI tools available within the Poneglyph ecosystem:
| Tool Name | Technology | Primary Purpose | Source |
|---|---|---|---|
searchDatabase | pgvector / PostgreSQL | Semantic search of field reports, datasets, and NGO documents. | search-db.ts:25-30 |
webSearch | Gemini Google Search | Real-time grounding for current events and policy updates. | web-search.ts:70-75 |
deepResearch | Tavily AI | Multi-step investigation for complex synthesis and fact-checking. | system.ts:20-24 |
Internal Data Retrieval (searchDatabase)
The searchDatabaseTool implements semantic search using pgvector for cosine similarity. This allows the agent to find relevant humanitarian reports even when keywords do not match exactly.
The tool performs a join between datasets and sources tables, filtering by embedding similarity. It also enriches results with metadata such as file types, publishers, and publication dates.
Sources: apps/server/src/agents/tools/search-db.ts:25-125
Data Enrichment Logic
For every relevant dataset found, the system:
- Calculates Relevance: Uses
1 - (d.embedding <=> embeddingStr::vector)to determine a similarity score. - Manages Access: Generates temporary, presigned S3 URLs for secure file access.
- Applies Metadata: Maps tags to datasets in O(1) time using a pre-fetched Map.
Sources: apps/server/src/agents/tools/search-db.ts:47-51, apps/server/src/agents/tools/search-db.ts:98-120
External Intelligence (webSearch & deepResearch)
The webSearchTool utilizes Gemini's native Google Search grounding. This tool is isolated to avoid conflicts between provider-defined tools and custom tools.
For more intensive tasks, the deepResearch specialist conducts multi-step research. It follows a structured workflow:
- Searching via multiple angles and queries.
- Extracting content from URLs.
- Cross-referencing findings.
- Determining confidence levels (High/Medium/Low).
Sources: apps/server/src/agents/prompts/deep-research.ts:5-12
Research Interface and Agent Panel
On the frontend, users interact with these tools through a dedicated research agent panel. This component handles message threads, file uploads, and real-time status updates.
Frontend Components
| Component | Functionality | Source |
|---|---|---|
AgentPanel | Main chat interface for tool interaction and file processing. | agent-panel.tsx:21 |
ResearchStatusLog | Displays agent progress (e.g., "Explored 12 files"). | research/page.tsx:26 |
ResearchInput | Captures user queries and file attachments. | research/page.tsx:106 |
The AgentPanel component supports drag-and-drop file uploads for CSV, JSON, and XLSX formats, allowing users to provide local context to the AI research tools.
Sources: apps/web/src/components/research/agent-panel.tsx:85-115
Response Guidelines and Tone
The AI tools are programmed to maintain a professional, analytical tone suitable for life-or-death resource allocation decisions. The system prompt mandates:
- Source Citations: Every claim must include inline markdown links.
- Structured Sections: Separation between "Internal Datasets" and "Web Sources".
- Data Precision: Explicit mention of uncertainty if a claim is not fully supported.