unsprawl.solver¶

Regulatory Compliance Agent using Gemini Context Caching.

This module implements the SolverAgent that ingests master plan documents, caches them for fast repeated queries, and checks proposals for compliance.

Example

>>> from unsprawl.solver import SolverAgent
>>>
>>> agent = SolverAgent()
>>> cache_name = await agent.ingest_master_plan("city_zoning_plan.pdf")
>>> result = await agent.query_compliance(
...     "Proposal: Build a 50-story residential tower in zone R-2"
... )
>>> print(result)

Attributes¶

logger

Classes¶

SolverAgent

Regulatory compliance agent using Context Caching.

Module Contents¶

logger¶

class SolverAgent(model='gemini-2.5-flash', cache_model='gemini-1.5-pro-002', api_key=None, default_ttl='3600s')[source]¶

Regulatory compliance agent using Context Caching.

Ingests master plan PDFs and caches them for efficient repeated queries. The cache persists for the specified TTL, enabling fast compliance checks without re-uploading documents.

Parameters:

model (str) – The Gemini model to use for compliance queries.
cache_model (str) – The model to use for caching (must support context caching).
api_key (str | None) – Google API key. If None, reads from GOOGLE_API_KEY environment variable.
default_ttl (str) – Default cache TTL (e.g., “3600s” for 1 hour, “86400s” for 1 day).

Notes

Uses client.files.upload for PDF ingestion
Uses client.caches.create for context caching
Queries use cached_content parameter for efficiency

model = 'gemini-2.5-flash'¶

cache_model = 'gemini-1.5-pro-002'¶

default_ttl = '3600s'¶

client¶

_cache_name: str | None = None¶

_cached_files: list[google.genai.types.File] = []¶

property cache_name: str | None¶

Get the current cache name, if any.

async upload_file(file_path)[source]¶

Upload a file to Gemini for use in caching.

Parameters:: file_path (str | Path) – Path to the file to upload.
Returns:: The uploaded file reference.
Return type:: types.File

async ingest_master_plan(pdf_path, ttl=None, display_name=None)[source]¶

Ingest a master plan PDF and create a cached context.

Parameters:

pdf_path (str | Path) – Path to the PDF document.
ttl (str | None) – Cache time-to-live. If None, uses default_ttl.
display_name (str | None) – Display name for the cache. If None, uses filename.

Returns:

The cache name for subsequent queries.

Return type:

str

async query_compliance(proposal, cache_name=None)[source]¶

Query compliance of a proposal against the cached master plan.

Parameters:

proposal (str) – The proposal to check for compliance.
cache_name (str | None) – Cache name to query. If None, uses the last created cache.

Returns:

Compliance analysis result.

Return type:

str

Raises:

ValueError – If no cache is available.

async get_cache_info(cache_name=None)[source]¶

Get information about a cache.

Parameters:: cache_name (str | None) – Cache name to query. If None, uses the last created cache.
Returns:: Cache metadata including expiration time.
Return type:: dict[str, Any]

async delete_cache(cache_name=None)[source]¶

Delete a cache to free resources.

Parameters:: cache_name (str | None) – Cache name to delete. If None, uses the last created cache.

async list_caches()[source]¶

List all available caches.

Returns:: List of cache metadata.
Return type:: list[dict[str, Any]]