AI Functions Reference

Source: Modular service files in src/features/ai/services/ (see AI Engine architecture for the full file map)

Central AI service for GrantMaster. Since March 2026, the formerly monolithic geminiService.ts has been decomposed into domain-specific modules:

Core infrastructure: geminiClient.ts (client init), geminiRetry.ts (backoff), geminiJsonParser.ts (response parsing), geminiSchemas.ts (typed output schemas), geminiServiceCore.ts (entrypoint), geminiServiceFacade.ts (DI wrapper)
Feature modules: geminiAssistant.ts, geminiCompliance.ts, geminiDocuments.ts, geminiForecast.ts, geminiServiceProposalImpact.ts
RAG pipeline: 12 modules — see RAG section
Safety: responseSafety.ts (prompt injection / PII guards), contextAssembler.ts (prompt building / citation extraction)

Operates in dual mode controlled by USE_CLOUD_FUNCTIONS:

Cloud Functions (default): Routes through Firebase/Genkit for tracing, monitoring, and server-side retries
Legacy direct: Falls back to client-side Gemini SDK calls with callWithRetry (exponential backoff on 429/5xx)

All functions use structured JSON output via Gemini responseSchema (defined in geminiSchemas.ts) and track AI usage per organization via trackAiGeneration(). Model: gemini-2.5-flash

Journal Generation

`generateJournalEntries`

Generate AI-powered journal (journal) entries from a user’s monthly journal input. Produces audit-compliant daily task descriptions in Dutch, distributed across working days for the specified month.

generateJournalEntries(
  input: JournalInput,
  projects: Project[],
  user: User,
  organization?: Organization
): Promise<JournalEntry[]>

Param	Type	Description
`input`	`JournalInput`	Monthly Journal data including month, notable events, project allocations, and work pattern
`projects`	`Project[]`	Full project list; filtered to `input.selectedProjectIds` internally
`user`	`User`	Current user profile (name, role, contract hours, work pattern)
`organization`	`Organization?`	Optional organization context for locale, currency, and tenant isolation

Returns: Sorted array of journal entries with organizationId injected. Usage tracking: trackAiGeneration(orgId, 'journal_generation', { month, projectCount })

Compliance & Auditing

`analyzeCompliance`

Audit journal entries against project budgets, grant terms, and labor regulations. Detects issues like vague descriptions, weekend/holiday work, hour anomalies, and budget overruns.

analyzeCompliance(
  entries: JournalEntry[],
  projects: Project[],
  user: User,
  organization?: Organization
): Promise<AuditResult>

Param	Type	Description
`entries`	`JournalEntry[]`	Journal entries to audit
`projects`	`Project[]`	Project context for budget and term validation
`user`	`User`	User context (contract hours, work pattern)
`organization`	`Organization?`	Organization context for compliance rules

Returns: AuditResult with score (0–100), summary, and flags[] (each with severity, issue, recommendation).

`checkExpenseEligibility`

Pre-validate an expense against compliance policies, budget lines, and project rules before submission.

checkExpenseEligibility(
  expense: Partial<Expense>,
  policies: CompliancePolicy[],
  budgetLines: BudgetLine[],
  activeGrants: ActiveGrant[],
  categories: ExpenseCategory[],
  organizationId: string
): Promise<ExpenseComplianceResult>

Returns: ExpenseComplianceResult with compliance level (compliant | warning | non_compliant), issues, and recommendations.

Reporting & Forecasting

`generateReportNarrative`

Generate a professional narrative section for a journal or progress report. Supports configurable report types (quarterly, annual, compliance).

generateReportNarrative(
  config: ReportConfig,
  projects: Project[],
  entries: JournalEntry[],
  user: User,
  organization?: Organization
): Promise<string>

Returns: Markdown-formatted narrative string.

`generateProjectForecast`

Predict project timeline, budget, and resource utilization using historical data. Includes risk scoring and mitigation recommendations.

generateProjectForecast(
  project: Project,
  entries: JournalEntry[],
  user: User,
  organization?: Organization
): Promise<ForecastResult>

Returns: ForecastResult with timeline/budget projections, risk scores, and recommendations.

Receipt Processing

`analyzeReceipt`

OCR and structured extraction from receipt images. Extracts amount, vendor, date, category, and tax information.

analyzeReceipt(
  imageBase64: string,
  mimeType: string,
  organization?: Organization
): Promise<ReceiptAnalysisResult>

Param	Type	Description
`imageBase64`	`string`	Base64-encoded image data
`mimeType`	`string`	Image MIME type (e.g. `image/jpeg`, `image/png`)
`organization`	`Organization?`	Organization context for currency defaults

Returns: Extracted receipt fields with confidence scores.

Grant Assistant

`queryGrantAssistant`

Conversational AI assistant for grant-related questions. Supports multi-turn chat with project and document context.

queryGrantAssistant(
  messages: ChatMessage[],
  projects: Project[],
  user: User,
  organization?: Organization
): Promise<string>

Param	Type	Description
`messages`	`ChatMessage[]`	Conversation history (`{ role: 'user' \| 'model', text: string }`)
`projects`	`Project[]`	Active projects for context
`user`	`User`	Current user profile
`organization`	`Organization?`	Organization context

Returns: Assistant response text.

Proposal Generation

`generateProposalSection`

Generate a single section of a grant proposal (e.g. executive summary, methodology, budget justification).

generateProposalSection(
  sectionType: ProposalSectionType,
  context: ProposalGenerationContext,
  organizationId: string
): Promise<ProposalSectionResult>

Param	Type	Description
`sectionType`	`ProposalSectionType`	Section to generate (e.g. `'executive_summary'`, `'methodology'`, `'budget_justification'`)
`context`	`ProposalGenerationContext`	Project info, organization profile, funder requirements, any existing sections
`organizationId`	`string`	Tenant ID for usage tracking

Returns: ProposalSectionResult with generated content, key points, and confidence score.

`generateFullProposal`

Generate all sections of a grant proposal in sequence. Supports progress callbacks for UI feedback.

generateFullProposal(
  context: ProposalGenerationContext,
  organizationId: string,
  onProgress?: (section: string, index: number, total: number) => void
): Promise<ProposalSectionResult[]>

Param	Type	Description
`context`	`ProposalGenerationContext`	Full proposal context
`organizationId`	`string`	Tenant ID
`onProgress`	`function?`	Optional callback fired after each section completes

Returns: Array of ProposalSectionResult for all generated sections.

Impact / M&E Analytics

`suggestMEIndicators`

Suggest monitoring & evaluation indicators for a project based on its theory of change, sector, and funder requirements.

suggestMEIndicators(
  project: Project,
  existingIndicators: MEIndicator[],
  organization?: Organization
): Promise<SuggestedIndicator[]>

`generateMENarrative`

Generate a narrative report section for M&E data — interprets indicator values, trends, and anomalies into human-readable analysis.

generateMENarrative(
  indicators: MEIndicator[],
  dataPoints: MEDataPoint[],
  project: Project,
  organization?: Organization
): Promise<string>

`detectMEAnomalies`

Detect statistical anomalies in M&E data collection — identifies outliers, sudden trend changes, and data quality issues.

detectMEAnomalies(
  indicators: MEIndicator[],
  dataPoints: MEDataPoint[],
  project: Project,
  organization?: Organization
): Promise<MEAnomaly[]>

RAG Pipeline Functions

Source: src/features/ai/services/rag*.ts, contextAssembler.ts, ranking.ts, retrievalQueryBuilder.ts

`queryRAGAuto`

Public entry point for RAG queries. In production, delegates to Cloud Functions; falls back to client-side pipeline.

queryRAGAuto(options: RAGQueryOptions): Promise<RAGQueryResponse>

`uploadAndProcessDocument`

Full document upload-to-processing lifecycle (chunking, embedding, storage).

uploadAndProcessDocument(file: File, projectId: string, orgId: string): Promise<string>

`extractDeadlines` / `extractActivityRules`

Standalone metadata extractors using gemini-2.5-flash with structured JSON output.

extractDeadlines(documentText: string): Promise<DeadlineInfo[]>
extractActivityRules(documentText: string): Promise<ActivityRule[]>

Safety Functions

Source: src/features/ai/services/responseSafety.ts

`applySafetyGuard`

Validates RAG responses before returning to user. Checks for prompt injection patterns, secret exfiltration attempts, and PII exposure.

applySafetyGuard(response: string, context: SafetyContext): SafetyResult

Internal Helpers

Helper	Source	Description
`getAIClient()`	`geminiClient.ts`	Instantiates a `GoogleGenAI` client per call (ensures latest API key)
`callWithRetry<T>(fn, retries?, delay?)`	`geminiRetry.ts`	Exponential backoff retry for 429/5xx errors (3 retries, 1s base)
`USE_CLOUD_FUNCTIONS`	`geminiServiceCore.ts`	Feature flag — `true` routes through Genkit Cloud Functions
`assembleContextFromChunks()`	`contextAssembler.ts`	Builds RAG prompt from retrieved chunks
`buildRAGPrompt()`	`contextAssembler.ts`	Constructs full prompt with system instruction, context, and query
`extractCitations()`	`contextAssembler.ts`	Parses `[Source N]` references from RAG responses
`cosineSimilarity()`	`ranking.ts`	Vector similarity for chunk scoring
`dedupeScoredChunks()`	`ranking.ts`	Deduplication of overlapping chunks
`hashQuery()`	`ragCache.ts`	Deterministic hash for cache keying

Usage Tracking

Every AI function calls trackAiGeneration(organizationId, type, metadata) on success. Agent-specific operations are tracked via dedicated trackers in usageTrackingTrackers.ts.

AI Generation Types

Type	Function
`journal_generation`	`generateJournalEntries`
`compliance_analysis`	`analyzeCompliance`
`report_narrative`	`generateReportNarrative`
`project_forecast`	`generateProjectForecast`
`receipt_analysis`	`analyzeReceipt`
`expense_eligibility`	`checkExpenseEligibility`
`grant_assistant`	`queryGrantAssistant`
`proposal_section`	`generateProposalSection`
`full_proposal`	`generateFullProposal`
`me_indicators`	`suggestMEIndicators`
`me_narrative`	`generateMENarrative`
`me_anomalies`	`detectMEAnomalies`

Agent Usage Trackers (Added March 2026)

Tracker	Source	Description
`trackAgentRun()`	`usageTrackingTrackers.ts`	Logs agent run initiation
`trackAgentStep()`	`usageTrackingTrackers.ts`	Logs agent step execution
`trackCreditConsumption()`	`usageTrackingTrackers.ts`	Metering for credit usage
`trackCreditPurchase()`	`usageTrackingTrackers.ts`	Logs credit pack purchases

Overview

Public API

tRPC & Functions

Frontend API

Events & Domain

Billing Services

Shared Modules

AI Functions Reference

AI Functions Reference

Journal Generation

`generateJournalEntries`

Compliance & Auditing

`analyzeCompliance`

`checkExpenseEligibility`

Reporting & Forecasting

`generateReportNarrative`

`generateProjectForecast`

Receipt Processing

`analyzeReceipt`

Grant Assistant

`queryGrantAssistant`

Proposal Generation

`generateProposalSection`

`generateFullProposal`

Impact / M&E Analytics

`suggestMEIndicators`

`generateMENarrative`

`detectMEAnomalies`

RAG Pipeline Functions

`queryRAGAuto`

`uploadAndProcessDocument`

`extractDeadlines` / `extractActivityRules`

Safety Functions

`applySafetyGuard`

Internal Helpers

Usage Tracking

AI Generation Types

Agent Usage Trackers (Added March 2026)

Overview

Public API

tRPC & Functions

Frontend API

Events & Domain

Billing Services

Shared Modules

Documentation Index

​AI Functions Reference

​Journal Generation

​generateJournalEntries

​Compliance & Auditing

​analyzeCompliance

​checkExpenseEligibility

​Reporting & Forecasting

​generateReportNarrative

​generateProjectForecast

​Receipt Processing

​analyzeReceipt

​Grant Assistant

​queryGrantAssistant

​Proposal Generation

​generateProposalSection

​generateFullProposal

​Impact / M&E Analytics

​suggestMEIndicators

​generateMENarrative

​detectMEAnomalies

​RAG Pipeline Functions

​queryRAGAuto

​uploadAndProcessDocument

​extractDeadlines / extractActivityRules

​Safety Functions

​applySafetyGuard

​Internal Helpers

​Usage Tracking

​AI Generation Types

​Agent Usage Trackers (Added March 2026)

AI Functions Reference

Journal Generation

`generateJournalEntries`

Compliance & Auditing

`analyzeCompliance`

`checkExpenseEligibility`

Reporting & Forecasting

`generateReportNarrative`

`generateProjectForecast`

Receipt Processing

`analyzeReceipt`

Grant Assistant

`queryGrantAssistant`

Proposal Generation

`generateProposalSection`

`generateFullProposal`

Impact / M&E Analytics

`suggestMEIndicators`

`generateMENarrative`

`detectMEAnomalies`

RAG Pipeline Functions

`queryRAGAuto`

`uploadAndProcessDocument`

`extractDeadlines` / `extractActivityRules`

Safety Functions

`applySafetyGuard`

Internal Helpers

Usage Tracking

AI Generation Types

Agent Usage Trackers (Added March 2026)