Documentation Index

Fetch the complete documentation index at: https://grantmaster.dev/llms.txt

Use this file to discover all available pages before exploring further.

​

AI Engine and Prompt Management

​

AI Stack Architecture

• Primary Model: gemini-2.5-flash — used for all generation tasks: journal drafting, compliance auditing, grant proposal writing, report generation, and RAG query answering.
• Embeddings: text-embedding-004 (Google) — powers semantic similarity search in the RAG pipeline.
• Execution Mode: USE_CLOUD_FUNCTIONS = true in both geminiService.ts and ragService.ts. Production calls are routed through Firebase Callable Functions (Genkit-instrumented) rather than direct client-side SDK calls. Client-side fallback paths remain in code but are not active in production.

​

Source File Map

​

Gemini Core Infrastructure

​

Specialized Gemini Feature Modules

​

RAG Pipeline (Modular)

​

Context Assembly and Safety

​

Other AI Services

​

Hooks

​

Agent Services

​

Retrieval-Augmented Generation (RAG)

1. Ingestion (ragDocumentProcessing.ts): Uploaded files are chunked by chunkText() using sentence-boundary-aware splitting with a 200-token overlap window. Each chunk is categorised as budget, compliance, reporting, or general by keyword detection in detectCategory().
2. Embeddings (ragDocumentProcessing.ts): generateEmbedding() calls the text-embedding-004 model via @google/genai. Embeddings are stored on DocumentChunk records in the document-chunks Firestore collection, scoped by organizationId and projectId for tenant isolation.
3. Retrieval (ragRetrieval.ts, ranking.ts, retrievalQueryBuilder.ts): retrieveRelevantChunks() builds a Firestore query via buildDocumentChunkQuery(), fetches tenant-scoped chunks, computes cosine and Jaccard similarity, applies freshness filtering via isChunkFresh(), deduplicates via dedupeScoredChunks(), and returns the top-N results (default 5). Production document processing is triggered by a Firebase Storage upload event via the processDocument Cloud Function.
4. Context Assembly (contextAssembler.ts): assembleContextFromChunks() and buildRAGPrompt() construct the final prompt. The system switches structure based on queryType. getSystemInstruction() provides the GrantControl AI persona. After generation, extractCitations() parses [Source N] references.
5. Safety (responseSafety.ts): Before returning any RAG response, applySafetyGuard() checks for prompt injection patterns, secret exfiltration attempts, and PII in the output.
6. Query Orchestration (ragPipeline.ts): queryRAG() is the internal orchestrator combining retrieval, context assembly, LLM call, and safety checks into one pipeline.
7. Cloud Function Routing (ragCloud.ts): queryRAGAuto() is the public entry point. In production it delegates to queryRAGCloudFunction(), which calls the queryRAG Callable Function (server-side key, auth checks, audit logging).
8. Caching (ragCache.ts): Query results are cached for 1 hour (configurable per category via ragShared.ts) in the query-cache Firestore collection keyed by a hash of queryText + projectId. Cache hits are recorded in the AI query audit log.
9. Audit Logging (ragLogging.ts): Every query (cache hit or miss) is written to the ai-query-logs collection via logQuery(), including cache status and safety check metadata.
10. Document Management (ragDocumentManagement.ts): uploadAndProcessDocument() handles the full upload-to-processing lifecycle. subscribeToDocumentStatus() enables real-time status updates in the UI.

​

Supported Query Types

​

Metadata Extraction

• extractDeadlines() — pulls reporting deadlines from document text and returns DeadlineInfo[]
• extractActivityRules() — pulls allowed/prohibited activity rules and returns ActivityRule[]

​

Prompt Versioning and Management

• System Personas: Each AI task (RAG assistant, compliance auditor, journal generator, etc.) has a dedicated system instruction string. The RAG persona is built by getSystemInstruction() in contextAssembler.ts.
• Default Templates: Seed prompts are defined in defaultPrompts.ts and loaded by promptLibraryService.ts.
• Dynamic Injection: Context is injected at call time (project data, document chunks, user role). The RAG system builds prompts via buildRAGPrompt() in contextAssembler.ts which switches structure based on queryType.
• Structured Output: geminiSchemas.ts defines Gemini response schemas (Schema, Type from @google/genai) to enforce typed JSON output for all structured generation tasks. geminiJsonParser.ts safely parses the responses.

​

Autonomous Agent Execution

​

Agent Definitions (agentDefinitions.ts)

​

Run Lifecycle (AgentExecutionService)

queued → running → completed
                 → failed
                 → cancelled
                 → awaiting_human → running (after resolution)

• startRun() — validates definition, checks RBAC, verifies quota via AgentQuotaService.validateRunStart() (concurrent limits, monthly/hourly rate limits), reserves credits via CreditService.reserveCredits(), creates the AgentRun document, emits AGENT_TASK_STARTED.
• executeStep() — validates step budget via AgentQuotaService.validateStepExecution(), invokes a tool from AgentToolRegistry, consumes credits via CreditService.consumeCredits(), appends an AgentStep to the run, emits AGENT_STEP_COMPLETED.
• pauseRun() — transitions to awaiting_human, creates an AgentEscalation record with resolution options, emits AGENT_ESCALATION_REQUIRED.
• resumeRun() — records resolution, transitions back to running, emits AGENT_ESCALATION_RESOLVED.
• completeRun() / failRun() / cancelRun() — release unused reserved credits via CreditService.releaseCredits(), emit the corresponding terminal event.

​

Agent Quota Service (AgentQuotaService)

• validateRunStart() — checks concurrent agent limit (per org, per tier), monthly run limit, and hourly rate limit before any agent run begins.
• validateStepExecution() — checks step budget and token budget per run before each step.
• getCreditUsageSummary() — returns dashboard/billing summary of credit consumption.
• Warning thresholds at 80% and 90% trigger QUOTA_WARNING events via EventBus for proactive alerting.

​

Agent Run Service (AgentRunService)

• listRuns(params) — queries agent_runs with filtering by status, agentType, and triggeredBy.
• parseAgentRun() — schema validation with Sentry error capture for malformed run documents.

​

Tool Registry (AgentToolRegistry)

1. Checks the agent’s inherited user permissions.
2. Calls the underlying service method.
3. Returns a structured AgentToolResult with creditsUsed and tokensUsed.

​

Credit Accounting

1. Credits are reserved upfront at startRun() based on definition.defaultCreditBudget.
2. Credits are consumed incrementally per step at executeStep().
3. Unused credits are released at run completion/failure/cancellation.

​

UI

• AgentDashboard — lists runs and current status.
• AgentRunDetail — step-by-step execution view.
• CreditUsageWidget — shows credits consumed per run.
• AgentAttributionBadge — inline badge for AI-generated content attribution.
• useAgentRuns hook — React Query integration with filtering and computed summary statistics (totalRuns, completedRuns, failedRuns, creditsConsumed, averageCreditCost, averageDurationMs).

​

Cost Control and Quotas

1. Credit budgets: Each agent run reserves a credit budget from definition.defaultCreditBudget. Steps consume credits atomically via Firestore transactions; unused credits are released on completion.
2. Agent quota service: AgentQuotaService.validateRunStart() enforces per-tenant concurrent agent limits, monthly run limits, and hourly rate limits — all tied to subscription tier via TIER_LIMITS.
3. Step and token budgets: AgentQuotaService.validateStepExecution() prevents runaway agent runs by checking per-run step and token budgets.
4. Usage tracking: All agent operations are metered via usageTrackingTrackers.ts — trackAgentRun(), trackAgentStep(), trackCreditConsumption(), trackCreditPurchase().
5. Usage alerts: usageAlerts.ts triggers notifications at 80%, 90%, 95%, and 100% thresholds for API calls, AI generations, storage, and other metered dimensions.
6. Query caching: RAG query results are cached with configurable TTLs per category (via ragShared.ts) in Firestore (query-cache) to avoid redundant Gemini calls.
7. Retry with backoff: geminiRetry.ts wraps all Gemini calls in callWithRetry() — retries up to 3 times with exponential backoff on HTTP 429 and 5xx responses.

​

Responsible AI & Privacy

• Safety Guards: responseSafety.ts runs applySafetyGuard() on all RAG responses to detect and block prompt injection, secret exfiltration, and PII exposure before returning results to the user.
• PII Stripping: Sensitive data is sanitized before being sent to the LLM provider.
• Zero-Retention: We opt-out of “Data Training” programs with AI providers to ensure customer data is never used to re-train base models.
• Audit Trail: Every AI query is logged to ai-query-logs via ragLogging.ts with full metadata (cache status, safety check results, token counts).