Architecture Decision Records: Gemini URL Context Integration
Document ID: ADR-2026-0204-005
Date: February 4, 2026
ADR-2026-007: Adoption of Gemini URL Context for Web Intelligence
Status
PROPOSED — Pending architecture review
Context
Coditect's autonomous agents currently lack the ability to independently research and ground decisions in live web content. Agents rely on human-provided context or pre-loaded documents. This limits autonomy in scenarios requiring documentation research, compliance verification, and competitive analysis.
Google's Gemini API URL Context tool (GA since August 2025) provides a built-in capability for LLMs to fetch, parse, and reason over web content at inference time, including multimodal support for PDFs and images.
Decision
Adopt Gemini API URL Context as the primary web content access mechanism for Coditect agents, integrated through a Web Intelligence Layer that provides caching, audit trails, and compliance controls.
Alternatives Considered
| Alternative | Pros | Cons | Decision |
|---|---|---|---|
| Gemini URL Context | Built-in, no infra, multimodal PDF support, Google cache | Public URLs only, Gemini dependency | Selected |
| Jina Reader API | Good text extraction, auth support | No visual PDF parsing, extra cost, additional dependency | Rejected as primary; retain as fallback |
| FireCrawl | Auth support, JavaScript rendering | No multimodal, extra cost, hosted dependency | Rejected |
| Crawl4AI (self-hosted) | Full control, auth support | Infrastructure overhead, no PDF understanding, maintenance burden | Rejected |
| Custom scraping | Maximum flexibility | Massive development effort, ongoing maintenance, anti-bot challenges | Rejected |
Consequences
Positive:
- Zero infrastructure overhead for web content access
- Native multimodal PDF understanding (superior to text extraction)
- Token-only pricing (no per-request fees)
- URL retrieval metadata for compliance audit trails
- Combines with Google Search for discover-then-analyze workflows
Negative:
- Google API dependency (mitigated by adapter pattern + fallback)
- Limited to public URLs (mitigated by file upload for private docs)
- Rate limits may constrain high-volume research (mitigated by caching + model routing)
- No control over cache freshness timing
Compliance Impact
- FDA 21 CFR Part 11: URL retrieval metadata provides evidence of source verification
- HIPAA: Must ensure no PHI is transmitted in URLs; URL allowlisting enforces this
- SOC2: Audit trail records all web content access by agents
ADR-2026-008: REST API over SDK for Gemini Integration
Status
PROPOSED
Context
Gemini provides both Python/JavaScript SDKs and a REST API for integration. The Coditect platform needs to choose an integration approach for the URL Context adapter.
Decision
Use the Gemini REST API directly (via httpx/aiohttp) rather than the Google GenAI Python SDK.
Rationale
This decision aligns with the source material's strong recommendation and Coditect's architectural principles:
| Factor | REST API | SDK |
|---|---|---|
| Dependency stability | HTTP protocol is stable | SDK versions change frequently (google-genai 1.55+) |
| Update burden | No code changes for API updates | SDK changes require codebase updates |
| Control | Full control over request/response | Abstracted; harder to debug edge cases |
| Error handling | Direct HTTP status codes | SDK-wrapped exceptions may obscure root cause |
| Retry logic | Custom implementation | SDK retry may conflict with Coditect's circuit breaker |
| Payload inspection | Full visibility for audit trails | SDK may transform payloads |
| Testing | Easy to mock HTTP calls | SDK mocking is more complex |
Consequences
Positive:
- Reduced dependency churn
- Full control over request/response lifecycle
- Easier audit trail capture (raw request/response logging)
- Simpler testing via HTTP mocking
Negative:
- Must implement request construction manually
- Must track API schema changes ourselves
- No automatic client-side validation
Implementation Note
Wrap REST calls in a thin adapter class (GeminiURLContextAdapter) that encapsulates all Gemini-specific logic. If SDK becomes compelling in future, only the adapter needs replacement.
ADR-2026-009: Compliance Document Caching Architecture
Status
PROPOSED
Context
Compliance agents will frequently access the same regulatory documents (FDA guidance, HIPAA bulletins, NIST frameworks). Without caching, each research task would make redundant API calls, consuming tokens and increasing latency.
However, compliance documents occasionally update. Caching stale regulatory content could lead to incorrect compliance decisions.
Decision
Implement a FoundationDB-backed content cache with category-based TTL and content versioning.
TTL Strategy
| Content Category | TTL | Rationale |
|---|---|---|
| Regulatory (FDA, HIPAA, NIST) | 24 hours | Regulatory docs change infrequently but must be current |
| API Documentation | 6 hours | Docs update more frequently |
| News/Blog content | 1 hour | Rapidly changing content |
| Static reference material | 7 days | Standards, specifications rarely change |
| Volatile content | 30 minutes | Frequently updated dashboards, feeds |
Content Versioning
Each cached entry stores a SHA-256 hash of the content. When TTL expires and content is re-fetched, compare hashes:
- Same hash: Extend TTL without re-processing
- Different hash: Store new version, flag change for compliance review, maintain previous version for audit
Consequences
Positive:
- 50%+ reduction in API calls (steady state)
- Consistent response times for frequently accessed documents
- Content versioning enables compliance change detection
- FoundationDB provides ACID guarantees for cache integrity
Negative:
- Cache invalidation complexity
- Storage growth over time (mitigated by TTL-based cleanup)
- Potential for serving slightly stale content within TTL window
ADR-2026-010: URL Allowlisting for Compliance Workflows
Status
PROPOSED
Context
In compliance-critical workflows, agents must only ground decisions in authoritative sources. Unrestricted URL access could lead to agents using unofficial, incorrect, or manipulated content for compliance decisions.
Decision
Implement mandatory URL domain allowlisting for compliance-mode URL Context requests.
Allowlist Structure
compliance_url_allowlist:
fda_21cfr11:
- fda.gov
- ecfr.gov
- federalregister.gov
hipaa:
- hhs.gov
- healthit.gov
soc2:
- aicpa-cima.com
- isaca.org
general_standards:
- nist.gov
- iso.org
# Non-compliance mode: no restriction (all public URLs allowed)
Enforcement
- Compliance mode: Only allowlisted domains permitted; requests to other domains are rejected with clear error
- Non-compliance mode: All public URLs permitted (standard agent research)
- Allowlist maintained in FoundationDB configuration; changes require audit record
Consequences
Positive:
- Prevents compliance decisions grounded in unreliable sources
- Auditable source restriction for regulatory inspection
- Configurable per compliance framework
Negative:
- Requires maintenance as authoritative sources change
- May miss relevant content from non-allowlisted sources
- Adds validation overhead to request pipeline
ADR-2026-011: Multi-Model Routing for URL Context Tasks
Status
PROPOSED
Context
URL Context tasks vary significantly in complexity and criticality. Simple documentation lookups don't require the same model quality as regulatory document interpretation. Coditect's token economics framework requires intelligent model selection.
Decision
Implement task-type-based model routing for URL Context requests, defaulting to Flash for cost efficiency and escalating to Pro for compliance and complex analysis.
Routing Matrix
| Task Type | Default Model | Override Trigger | Estimated Cost/Request |
|---|---|---|---|
| General research | Gemini 2.5 Flash | — | ~$0.01-$0.05 |
| API documentation | Gemini 2.5 Flash | Complex API → Pro | ~$0.01-$0.03 |
| News/blog analysis | Gemini 2.5 Flash | — | ~$0.005-$0.02 |
| PDF document analysis | Gemini 2.5 Pro | Simple PDF → Flash | ~$0.05-$0.20 |
| Compliance research | Gemini 2.5 Pro | Always Pro | ~$0.05-$0.20 |
| Architecture analysis | Gemini 2.5 Pro | Simple → Flash | ~$0.03-$0.15 |
| Code reference lookup | Gemini 2.5 Flash | Security analysis → Pro | ~$0.01-$0.05 |
Estimated Impact
40-60% token cost reduction compared to uniform Pro usage, based on typical task distribution where ~70% of URL Context requests are research/documentation tasks.
Consequences
Positive:
- Significant cost reduction through intelligent routing
- Appropriate quality level for each task type
- Aligns with Coditect's existing model routing infrastructure
Negative:
- Routing logic adds complexity
- Misrouting could degrade quality for important tasks (mitigated by conservative defaults)
- Model capabilities may shift with updates (requires periodic calibration)
ADR-2026-012: Fallback Strategy for URL Context Failures
Status
PROPOSED
Context
URL Context requests can fail for multiple reasons: rate limits, network issues, URL inaccessibility, or content format issues. Coditect agents must maintain autonomy even when the primary web intelligence path fails.
Decision
Implement a tiered fallback strategy with circuit breaker protection.
Fallback Tiers
Tier 1: Gemini URL Context (primary)
↓ (on failure)
Tier 2: Gemini Google Search grounding (discover + summarize)
↓ (on failure)
Tier 3: FoundationDB cached content (may be stale)
↓ (on failure)
Tier 4: Agent reports inability with context (human checkpoint)
Circuit Breaker Configuration
- Open threshold: 5 consecutive failures within 2 minutes
- Recovery timeout: 120 seconds
- Half-open test: 2 requests before closing
Consequences
Positive:
- Agent autonomy maintained across failure scenarios
- Graceful degradation rather than hard failure
- Circuit breaker prevents cascade failures
Negative:
- Fallback paths may provide lower quality results
- Stale cache usage in compliance mode requires explicit flagging
- Complex error handling logic
All ADRs maintained in FoundationDB configuration store
Review cycle: Quarterly or on significant technology changes
Approval required: Coditect Architecture Review Board