API reference¶

Generated docstrings for the small set of classes that carry the demo’s behavior. The rest of the codebase — CLI commands, settings dataclasses, plugin wiring, IoC providers — is intentionally out of scope; their shapes are stable and reading the source is faster than reading generated docs.

ADK runner¶

The per-request chat runner that ties the Litestar chat controller to Flash-Lite intent routing, grounded row-rendered routes, Google ADK 2.0 fallbacks, and closure-bound tools.

class app.domain.chat.services.adk.ADKRunner[source]¶

Bases: object

Per-request ADK 2.0 workflow with closure-bound tools.

__init__(session_service, classifier, persona_manager)[source]¶

Parameters:¶

session_service : SQLSpecSessionService¶

classifier : FlashLiteIntentClassifier¶

persona_manager : PersonaManager¶

Return type:¶

None

static ensure_configured()[source]¶

Raise AIServiceUnconfigured if Vertex AI credentials are missing.

Return type:¶

None

async get_history(user_id, session_id)[source]¶

Return displayable chat history for the current ADK session.

Return type:¶

list[ChatMessage]

Parameters:¶

user_id : str¶

session_id : str¶

async get_history_or_empty(user_id, session_id)[source]¶

Return displayable chat history, or an empty list if loading fails.

Return type:¶

list[ChatMessage]

Parameters:¶

user_id : str¶

session_id : str¶

async clear_session(user_id, session_id)[source]¶

Delete the current ADK session and its event history.

Return type:¶

None

Parameters:¶

user_id : str¶

session_id : str¶

async stream_request(query, user_id, session_id, persona, tools_service, location_context=None)[source]¶

Stream a chat turn as ADK produces partial events.

Yields:¶

Delta events followed by one final event with the complete reply payload.

Raises:¶

• AIServiceUnconfigured – If configured credentials are missing or invalid.

• ClientError – If the Gemini client fails for a non-credential reason.

• ValueError – If ADK raises a non-credential validation error.

Parameters:¶

query : str¶

user_id : str¶

session_id : str | None¶

persona : str¶

tools_service : AgentToolsService¶

location_context : dict[str, Any] | None¶

Return type:¶

AsyncIterator[dict[str, Any]]

Services¶

OracleAsyncService subclasses that own the named-SQL queries and result mapping for products, the embedding/response caches, structured Vertex AI selection calls, and the per-message metrics surfaced on /explore.

class app.domain.products.services.services.ProductService[source]¶

Bases: OracleAsyncService

Handles database operations for products using SQLSpec patterns.

async list_with_count(*filters)[source]¶

Return type:¶

OffsetPagination[Product]

Parameters:¶

filters : BeforeAfterFilter | OnBeforeAfterFilter | InCollectionFilter[Any] | LimitOffsetFilter | OrderByFilter | SearchFilter | NotInCollectionFilter[Any] | NotInSearchFilter | AnyCollectionFilter[Any] | NotAnyCollectionFilter[Any] | NullFilter | NotNullFilter | BooleanFilter | ChoicesFilter[Any]¶

async list_apex_products(*, q=None, category=None, limit=50, offset=0)[source]¶

Return type:¶

tuple[list[ApexProduct], int]

Parameters:¶

q : str | None¶

category : str | None¶

limit : int¶

offset : int¶

async get_vector_readiness()[source]¶

Return type:¶

ApexVectorReadiness

async get_by_id(product_id)[source]¶

Return type:¶

Product | None

Parameters:¶

product_id : int¶

async get_by_name(name)[source]¶

Return type:¶

Product | None

Parameters:¶

name : str¶

async get_products_for_embedding(force=False)[source]¶

Return (products_to_embed, total_count). force=True returns every product.

Return type:¶

tuple[list[dict[str, Any]], int]

Parameters:¶

force : bool¶

async update_embedding(product_id, embedding)[source]¶

Return type:¶

bool

Parameters:¶

product_id : int¶

embedding : list[float]¶

async search_by_vector(query_embedding, similarity_threshold=0.7, limit=5, *, store_id=None)[source]¶

Return type:¶

list[ProductMatch]

Parameters:¶

query_embedding : list[float]¶

similarity_threshold : float¶

limit : int¶

store_id : int | None¶

class app.domain.system.services.services.CacheService[source]¶

Bases: OracleAsyncService

Handles database operations for response and embedding cache.

async get_cached_response(cache_key)[source]¶

Return type:¶

ResponseCache | None

Parameters:¶

cache_key : str¶

async delete_expired_responses()[source]¶

Delete expired response-cache rows.

Return type:¶

int

Returns:¶

Number of expired response-cache rows deleted.

async set_cached_response(cache_key, response_data, ttl_minutes=60)[source]¶

Return type:¶

ResponseCache | None

Parameters:¶

cache_key : str¶

response_data : dict[str, Any]¶

ttl_minutes : int¶

async get_embedding(text, model)[source]¶

Return type:¶

list[float] | None

Parameters:¶

text : str¶

model : str¶

async save_embedding(text, embedding, model)[source]¶

Return type:¶

None

Parameters:¶

text : str¶

embedding : list[float]¶

model : str¶

async get_cache_stats()[source]¶

Return type:¶

CacheStats

async invalidate_cache(cache_type=None)[source]¶

Clear cache tables.

Return type:¶

int

Returns:¶

Number of rows deleted across the targeted cache tables.

Parameters:¶

cache_type : str | None¶

class app.domain.system.services.services.MetricsService[source]¶

Bases: OracleAsyncService

Handles performance metrics and search logging.

async record_search(metrics)[source]¶

Return type:¶

None

Parameters:¶

metrics : SearchMetricsCreate¶

async get_performance_stats(hours=24)[source]¶

Return type:¶

PerformanceStats

Parameters:¶

hours : int¶

async get_time_series(hours=1)[source]¶

Aggregate per-minute latency buckets for the requested window.

Return type:¶

MetricsTimeSeries

Returns:¶

A MetricsTimeSeries with parallel labels and series arrays.

Parameters:¶

hours : int¶

async get_chart_data(hours=1)[source]¶

Return all Explore dashboard chart projections for a shared time window.

Return type:¶

MetricsCharts

Parameters:¶

hours : int¶

Schemas¶

msgspec.Struct types used for request/response bodies, named-SQL row mapping, and tool payloads.

Chat domain schemas package.

class app.domain.chat.schemas.ChatMessage[source]¶

Bases: CamelizedBaseStruct

Individual chat message.

message : str¶

source : str¶

Product domain schemas package.

class app.domain.products.schemas.ApexInventoryList[source]¶

Bases: CamelizedBaseStruct

Inventory or availability row collection.

items : list[ProductAvailability]¶

total : int¶

class app.domain.products.schemas.ApexInventorySummaryList[source]¶

Bases: CamelizedBaseStruct

Inventory summary collection.

items : list[ApexInventorySummaryRow]¶

total : int¶

class app.domain.products.schemas.ApexInventorySummaryRow[source]¶

Bases: CamelizedBaseStruct

Inventory aggregate counts for a single store.

store_id : int¶

store_name : str¶

product_count : int¶

in_stock_count : int¶

low_stock_count : int¶

out_of_stock_count : int¶

total_quantity : int¶

class app.domain.products.schemas.ApexOpenAPIStatus[source]¶

Bases: CamelizedBaseStruct

Catalog metadata for APEX display.

title : str¶

api_version : str¶

base_path : str¶

tags : list[str]¶

operation_ids : list[str]¶

class app.domain.products.schemas.ApexProduct[source]¶

Bases: CamelizedBaseStruct

Product catalog row safe for APEX REST Source Catalogs.

id : int¶

name : str¶

description : str¶

price : float¶

category : str | None¶

sku : str | None¶

in_stock : bool¶

created_at : datetime | None¶

updated_at : datetime | None¶

class app.domain.products.schemas.ApexProductList[source]¶

Bases: CamelizedBaseStruct

Paginated product rows for APEX catalog consumption.

items : list[ApexProduct]¶

total : int¶

limit : int¶

offset : int¶

class app.domain.products.schemas.ApexRecommendation[source]¶

Bases: CamelizedBaseStruct

Grounded recommendation row returned to APEX.

product_id : int¶

name : str¶

description : str¶

price : float¶

category : str | None¶

sku : str | None¶

similarity_score : float | None¶

store_id : int | None¶

store_name : str | None¶

quantity_available : int | None¶

stock_status : Literal['IN_STOCK', 'LOW_STOCK', 'OUT_OF_STOCK'] | None¶

pickup_available : bool | None¶

class app.domain.products.schemas.ApexRecommendationRequest[source]¶

Bases: CamelizedBaseStruct

Recommendation request body accepted by APEX REST clients.

query : Annotated[str, msgspec.Meta(min_length=1, max_length=500)]¶

store_id : int | None¶

limit : Annotated[int, msgspec.Meta(ge=1, le=100)]¶

class app.domain.products.schemas.ApexRecommendationResponse[source]¶

Bases: CamelizedBaseStruct

Recommendation response with vector timings when available.

query : str¶

mode : Literal['vector', 'fallback']¶

items : list[ApexRecommendation]¶

total : int¶

cache_hit : bool | None¶

embedding_time_ms : float | None¶

oracle_time_ms : float | None¶

fallback_reason : str | None¶

class app.domain.products.schemas.ApexStoreList[source]¶

Bases: CamelizedBaseStruct

Seeded store rows safe for APEX display.

items : list[Store]¶

total : int¶

class app.domain.products.schemas.ApexVectorReadiness[source]¶

Bases: CamelizedBaseStruct

Oracle vector data readiness counts.

product_count : int¶

embedded_product_count : int¶

class app.domain.products.schemas.ApexVectorStatus[source]¶

Bases: CamelizedBaseStruct

Embedding provider and Oracle vector readiness status.

embedding_model : str¶

embedding_dimensions : int¶

provider_configured : bool¶

oracle_vector_ready : bool¶

product_count : int¶

embedded_product_count : int¶

class app.domain.products.schemas.ExplainPlan[source]¶

Bases: CamelizedBaseStruct

Oracle EXPLAIN PLAN output for the vector-search SQL (Panel 2).

plan_lines : list[str]¶

plan_summary : str¶

plan_rows : list[ExplainPlanRow]¶

class app.domain.products.schemas.ExplainPlanRow[source]¶

Bases: CamelizedBaseStruct

A structured operation row parsed from Oracle DBMS_XPLAN text.

id : str¶

operation : str¶

name : str¶

rows : str¶

bytes : str¶

cost : str¶

time : str¶

raw_line : str¶

is_vector : bool¶

class app.domain.products.schemas.Product[source]¶

Bases: CamelizedBaseStruct

Product entity from database.

id : int¶

name : str¶

price : float¶

description : str¶

category : str | None¶

sku : str | None¶

in_stock : bool¶

metadata : dict[str, Any] | None¶

embedding : list[float] | None¶

created_at : datetime | None¶

updated_at : datetime | None¶

class app.domain.products.schemas.ProductAvailability[source]¶

Bases: StoreProductInventory

Product availability row with store and product display fields.

store_name : str¶

store_address : str¶

store_city : str | None¶

store_state : str | None¶

store_zip : str | None¶

latitude : float | None¶

longitude : float | None¶

timezone : str | None¶

google_place_id : str | None¶

product_name : str¶

product_description : str¶

product_category : str | None¶

product_sku : str | None¶

product_price : float | None¶

distance_miles : float | None¶

class app.domain.products.schemas.ProductMatch[source]¶

Bases: CamelizedBaseStruct

A product row returned by vector similarity search.

Slim projection of product (no embedding, no metadata) plus the similarity_score derived in SQL via 1 - VECTOR_DISTANCE(…).

id : int¶

name : str¶

description : str¶

price : float¶

similarity_score : float¶

store_id : int | None¶

store_name : str | None¶

quantity_available : int | None¶

stock_status : Literal['IN_STOCK', 'LOW_STOCK', 'OUT_OF_STOCK'] | None¶

pickup_available : bool | None¶

class app.domain.products.schemas.Store[source]¶

Bases: CamelizedBaseStruct

Store location entity from database.

id : int¶

name : str¶

address : str¶

created_at : datetime¶

updated_at : datetime¶

city : str | None¶

state : str | None¶

zip : str | None¶

phone : str | None¶

latitude : float | None¶

longitude : float | None¶

timezone : str | None¶

google_place_id : str | None¶

hours : dict[str, Any] | None¶

metadata : dict[str, Any] | None¶

class app.domain.products.schemas.StoreDistance[source]¶

Bases: Store

Store row plus local coordinate ranking score.

distance_miles : float¶

distance_score : float | None¶

class app.domain.products.schemas.StoreHours[source]¶

Bases: CamelizedBaseStruct

Store hours response contract.

store_id : int¶

store_name : str¶

timezone : str | None¶

hours : dict[str, Any]¶

class app.domain.products.schemas.StoreProductInventory[source]¶

Bases: CamelizedBaseStruct

Store-product inventory row.

id : int¶

store_id : int¶

product_id : int¶

quantity_available : int¶

stock_status : Literal['IN_STOCK', 'LOW_STOCK', 'OUT_OF_STOCK']¶

pickup_available : bool¶

updated_at : datetime | None¶

class app.domain.products.schemas.VectorDemo[source]¶

Bases: CamelizedBaseStruct

Full POST /api/vector-demo payload for SPA / JSON consumers.

results : list[VectorDemoMatch]¶

search_time_ms : float¶

embedding_time_ms : float¶

oracle_time_ms : float¶

cache_hit : bool¶

performance_level : str¶

debug_timings : dict[str, float]¶

class app.domain.products.schemas.VectorDemoMatch[source]¶

Bases: CamelizedBaseStruct

A vector-search hit shaped for the explore-page Panel 1 partial.

name : str¶

description : str¶

price : float¶

similarity : float¶

class app.domain.products.schemas.VectorQuery[source]¶

Bases: CamelizedBaseStruct

A user-supplied vector-search query string.

query : str¶

System domain schemas package.

class app.domain.system.schemas.CacheStats[source]¶

Bases: CamelizedBaseStruct

Embedding-cache hit/usage rollup with derived hit rate.

total_hits : int¶

total_entries : int¶

cache_hit_rate : float¶

class app.domain.system.schemas.CacheStatsRow[source]¶

Bases: CamelizedBaseStruct

Single-row projection from get-cache-stats.

total_hits : int¶

total_entries : int¶

class app.domain.system.schemas.EmbeddingCache[source]¶

Bases: CamelizedBaseStruct

Embedding cache entry.

id : int¶

text_hash : str¶

embedding : list[float]¶

model : str¶

created_at : datetime¶

last_accessed : datetime¶

hit_count : int¶

class app.domain.system.schemas.MetricCard[source]¶

Bases: CamelizedBaseStruct

Single card on the metrics summary panel.

label : str¶

value : str | float¶

trend : str¶

trend_value : str | float | None¶

class app.domain.system.schemas.MetricsBreakdown[source]¶

Bases: CamelizedBaseStruct

Labels and values for the system breakdown chart.

labels : list[str]¶

values : list[float]¶

class app.domain.system.schemas.MetricsBreakdownRow[source]¶

Bases: CamelizedBaseStruct

Aggregate component timing row projected from search_metric.

embedding_ms : float¶

oracle_ms : float¶

ai_ms : float¶

intent_ms : float¶

other_ms : float¶

class app.domain.system.schemas.MetricsCharts[source]¶

Bases: CamelizedBaseStruct

Complete Explore dashboard chart payload.

time_series : MetricsTimeSeries¶

scatter : list[MetricsScatterPoint]¶

breakdown : MetricsBreakdown¶

class app.domain.system.schemas.MetricsScatterPoint[source]¶

Bases: CamelizedBaseStruct

Single vector-search point for similarity-vs-latency charts.

similarity_score : float¶

total_ms : float¶

oracle_ms : float¶

embedding_ms : float¶

class app.domain.system.schemas.MetricsSummary[source]¶

Bases: CamelizedBaseStruct

Card list rendered client-side in the Explore dashboard.

cards : list[MetricCard]¶

class app.domain.system.schemas.MetricsTimeSeries[source]¶

Bases: CamelizedBaseStruct

Latency series payload consumed by ApexCharts.

labels : list[str]¶

series : MetricsTimeSeriesPoints¶

class app.domain.system.schemas.MetricsTimeSeriesPoints[source]¶

Bases: CamelizedBaseStruct

Per-stage latency series for the latency chart.

total_ms : list[float]¶

oracle_ms : list[float]¶

embedding_ms : list[float]¶

class app.domain.system.schemas.MetricsTimeSeriesRow[source]¶

Bases: CamelizedBaseStruct

Single per-minute bucket projected from metrics-time-series.

bucket : str¶

total_ms : float¶

oracle_ms : float¶

embedding_ms : float¶

class app.domain.system.schemas.PerformanceStats[source]¶

Bases: CamelizedBaseStruct

Aggregate latency and volume across a window of search_metric rows.

total_searches : int¶

avg_search_time_ms : float¶

avg_oracle_time_ms : float¶

avg_similarity_score : float¶

class app.domain.system.schemas.ResponseCache[source]¶

Bases: CamelizedBaseStruct

Response cache entry.

id : int¶

cache_key : str¶

response_data : dict[str, Any]¶

created_at : datetime¶

expires_at : datetime | None¶

class app.domain.system.schemas.SearchMetricsCreate[source]¶

Bases: CamelizedBaseStruct

Row inserted into search_metric.

query_id : str¶

user_id : str | None¶

search_time_ms : float¶

embedding_time_ms : float¶

oracle_time_ms : float¶

ai_time_ms : float¶

intent_time_ms : float¶

similarity_score : float | None¶

result_count : int¶