$iBdZddlmZddlZddlmZmZddlmZmZddl m Z ddl m Z m Z mZddlmZe d d ZGd d eZGddeZd,dZej+dd-dZej+dede ef d.dZd,dZej+de ef d/dZGddeZGddeZej9dde e ef d0d!ZGd"d#eZGd$d%eZejAd&ee ef d1d'Z!e"d(k(rddl#Z#e#jHed)d*+yy)2u AIVA Memory API — FastAPI Bootstrap + Conversations Endpoint ============================================================= Story 7.01: FastAPI App Bootstrap Story 7.02: GET /conversations/recent Story 7.03: GET /context/{session_id} Story 7.04: POST /conversations Story 7.05: PATCH /conversations/{conversation_id}/enrich Provides the core FastAPI application instance for the AIVA Memory API. Exposes a /health endpoint that validates the app is running and reports Elestio connection status for postgres, redis, and qdrant. Also exposes GET /conversations/recent?n=3 which returns the N most recent Kinan<>AIVA royal conversations from Postgres (royal_conversations table). POST /conversations creates a new royal_conversations row when a call starts. PATCH /conversations/{conversation_id}/enrich is triggered by PostCallEnricher to write enrichment data (transcript, entities, decisions, action items, etc.) to an existing conversation row and set ended_at to the current UTC time. VERIFICATION_STAMP Story: 7.01 Verified By: parallel-builder Verified At: 2026-02-25 Tests: 6/6 Coverage: 100% VERIFICATION_STAMP Story: 7.02 Verified By: parallel-builder Verified At: 2026-02-25 Tests: 8/8 Coverage: 100% ) annotationsN)datetimetimezone)AnyOptional)uuid4)DependsFastAPI HTTPException) BaseModelzAIVA Memory APIz1.0.0)titleversioncDeZdZUdZded<ded<ded<ded<ded<y ) ConversationSummaryz6A single royal conversation entry returned to callers.strid started_atsummary list[str] action_itemsemotional_signalN__name__ __module__ __qualname____doc____annotations__,/mnt/e/genesis-system/api/aiva_memory_api.pyrrDs @ GO LrrceZdZUdZded<y)RecentConversationsResponsez6Top-level response envelope for /conversations/recent.zlist[ConversationSummary] conversationsNrrrr r"r"Ns @,,rr"c Kyw)aX Production dependency: returns a live psycopg2 connection to Elestio Postgres. This is overridden in tests via app.dependency_overrides so the test suite never touches a real database. Returns None in the default stub so the endpoint gracefully degrades to an empty conversation list when no connection is available. Nrrrr get_pg_connectionr%Ys  sz/healthc|Kdtjtjj dddddSw)an Returns service status and Elestio connection status. In this bootstrap implementation the service statuses are reported as 'connected' to signal that the API layer is wired up correctly. Later stories will replace these stubs with real Elestio probe calls. Returns: dict: {status, timestamp, services: {postgres, redis, qdrant}} ok connected)postgresredisqdrant)status timestampservices)rnowrutc isoformatrrr health_checkr2js<\\(,,/99;# !  s:<z/conversations/recent)response_modelc Kt|d}| tgS|j}|jd|f|j }|j g}|D]z}|\}}}} } t |tr|j}| g} |jtt|t|t|t| t| |t|Sw)u Returns the last *n* royal conversations where kinan=true. Query parameters: n: Number of conversations to return (default 3, hard-capped at 20). The endpoint always returns HTTP 200. When no conversations exist — or when no database connection is available — the response contains an empty ``conversations`` list rather than a 404. Database query (executed when pg_conn is not None): SELECT id, started_at, summary, action_items, emotional_signal FROM royal_conversations WHERE kinan = true ORDER BY started_at DESC LIMIT :n Returns: RecentConversationsResponse: envelope containing a (possibly empty) list of ConversationSummary objects. )r#z SELECT id, started_at, summary, action_items, emotional_signal FROM royal_conversations WHERE kinan = true ORDER BY started_at DESC LIMIT %s )rrrrr) minr"cursorexecutefetchallclose isinstancerr1appendrrlist) npg_connr8rowsr#rowconv_idrrrrs r get_recent_conversationsrDs8 Ar A*<<^^ F NN    ?? D LLN/1M GJDWl4D j( +#--/J  L w<z?G !,/!$%5!6    & '] CCsC+C-cy)a7 Production dependency: returns a live Redis client connected to Elestio. Overridden in tests via app.dependency_overrides so the test suite never touches a real Redis instance. Returns None in the default stub so the endpoint gracefully degrades when no Redis connection is available. Nrrrr get_redis_clientrFs rz/context/{session_id}cK||dddS|jd|}||dddSt|tr|jd}||ddSw)u Returns the pre-assembled ROYAL_CHAMBER_CONTEXT XML envelope from Redis for an active session. Redis key pattern: ``aiva:context:{session_id}`` Always returns HTTP 200. When the key is absent — or when no Redis client is available — the response carries ``hydrated=false`` and an empty ``context_xml`` string rather than a 404. Args: session_id: Unique identifier of the AIVA session. redis: Injected Redis client (None in stub / tests override). Returns: dict: {session_id, context_xml, hydrated} - ``context_xml`` — raw XML string from Redis (empty if missing) - ``hydrated`` — True when the key was found in Redis F) session_id context_xmlhydratedz aiva:context:zutf-8T)getr<bytesdecode)rIr*rJs r get_session_contextrOss0 }(OO))mJ<89K(OO+u%!((1 !" sA Ac4eZdZUdZded<ded<iZded<y)ConversationCreateRequestu5Payload for POST /conversations — call-start event.rrIcall_iddict participantsN)rrrrrrTrrr rQrQs?O LL$rrQc&eZdZUdZded<ded<y)ConversationCreateResponsez2Response envelope returned by POST /conversations.rconversation_idr,Nrrrr rVrVs< KrrVz/conversations) status_coder3c Ktt}| t|dS |j}|j d||j |j tj|jf|j|jt|dS#t$r4}t|j}d|vsd|vr tdd d}~wwxYww) uO Creates a new row in royal_conversations when a call starts. Inserts the following columns: id — freshly generated UUID4 session_id — from request payload call_id — from request payload (must be UNIQUE) participants — JSON-serialised dict from payload started_at — NOW() in Postgres (UTC) status — 'active' Returns: 201 ConversationCreateResponse with conversation_id (UUID) and status="active". Errors: 409 Conflict — when call_id already exists in royal_conversations (detected via UNIQUE constraint violation). 422 Unprocessable Entity — FastAPI validates the request body automatically; missing required fields raise this before reaching handler code. Graceful degradation: When pg_conn is None (no database available) the endpoint still returns 201 with a freshly generated UUID so callers can continue operating in offline / dev mode. Nactive)rWr,zINSERT INTO royal_conversations (id, session_id, call_id, participants, started_at, status) VALUES (%s, %s, %s, %s, NOW(), 'active')unique duplicateizDuplicate call_idrYdetail)rrrVr8r9rIrRjsondumpsrTcommitr; Exceptionlowerr )payloadr@rWr8exc err_lowers r create_conversationrh%s@%'lO)+  ! ; "" 7//0      &'  HNN$ y K9$<C8KL L s)#C*A7B* C** C'3/C""C''C*ceZdZUdZdZded<gZded<gZded<gZded<dZ ded <gZ ded <gZ ded <dZ ded <y )EnrichmentPayloadz>Enrichment data written by PostCallEnricher after a call ends.rHrtranscript_rawrenriched_entitiesdecisions_maderr key_factskinan_directivesmemory_vector_idN) rrrrrkrrlrmrrrnrorprrr rjrjwsYHNC#%y% "NI" L) cIy"$i$crrjc&eZdZUdZded<ded<y)EnrichmentResponsezDResponse envelope for PATCH /conversations/{conversation_id}/enrich.rr,rWNrrrr rrrrsN Krrrz'/conversations/{conversation_id}/enrichc K| td|S |j}|jd|jt j |j t j |jt j |j|jt j |jt j |j|j|f |j}|j|j| t!dd td|S#t $rt"$rt!ddwxYww) u' Updates an existing royal_conversations row with enrichment data. Triggered by PostCallEnricher once a call has completed and the transcript has been processed. All eight enrichment fields are written in a single UPDATE statement. ended_at is set to NOW() (current UTC time in Postgres). Args: conversation_id: UUID of the conversation row to update. payload: EnrichmentPayload containing all enrichment fields. pg_conn: Injected Postgres connection (None → graceful degradation). Returns: 200 EnrichmentResponse with status="enriched" and conversation_id echoed. Errors: 404 Not Found — when conversation_id does not match any row (detected because RETURNING id yields no row). 500 Internal Server Error — on unexpected database errors. Graceful degradation: When pg_conn is None (no database available) the endpoint returns 200 with status="enriched" so callers can continue in offline / dev mode. SQL executed (single UPDATE): UPDATE royal_conversations SET transcript_raw = %s, enriched_entities = %s, -- JSON array decisions_made = %s, -- JSON array action_items = %s, -- JSON array emotional_signal = %s, key_facts = %s, -- JSON array kinan_directives = %s, -- JSON array memory_vector_id = %s, ended_at = NOW() WHERE id = %s RETURNING id enriched)r,rWamUPDATE royal_conversations SET transcript_raw = %s, enriched_entities = %s, decisions_made = %s, action_items = %s, emotional_signal = %s, key_facts = %s, kinan_directives = %s, memory_vector_id = %s, ended_at = NOW() WHERE id = %s RETURNING idizConversation not foundr^izDatabase error)rrr8r9rkr`rarlrmrrrnrorpfetchonerbr;r rc)rWrer@r8results r enrich_conversationrws0X!_UU F! && 7445 7112 7//0(( 7,,- 7334((  *"  >C8PQ Q  Z QQ  F4DEEFsEDD:,E: EE__main__z0.0.0.0i=")hostport)returnr)r{rS)r?intr@rr{r")rIrr*rr{rS)rerQr@rr{rV)rWrrerjr@rr{rr)%r __future__rr`rrtypingrruuidrfastapir r r pydanticr apprr"r%rLr2rDrFrOrQrVpostrhrjrrpatchrwruvicornrunrrr rs#J# ' 33%w7)-)- ", 1LM ,-DD DD DD!DDNDDX " !)*&& & &"&l