{ "openapi": "3.1.0", "info": { "title": "Semvec REST API — Persistent Semantic State", "description": "Framework-agnostic semantic memory service. Feed text into Semvec sessions and retrieve context-aware memories. Auth via Ed25519-signed license JWTs (SEMVEC_LICENSE_KEY).", "version": "1.0.0" }, "paths": { "/metrics": { "get": { "summary": "Metrics", "operationId": "metrics_metrics_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/v1/health": { "get": { "summary": "Health", "operationId": "health_v1_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/v1/readyz": { "get": { "summary": "Readyz", "description": "Readiness probe: 200 when every dependency is reachable, else 503.\n\nReturns ``{\"ready\": bool, \"checks\": {redis, database, embedder}}``. Sets\nHTTP 503 (Service Unavailable) when any check fails so the orchestrator\npulls the pod out of rotation until it recovers.", "operationId": "readyz_v1_readyz_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Response Readyz V1 Readyz Get" } } } } } } }, "/v1/run": { "post": { "summary": "Run", "description": "Async-native version of /v1/run.\n\nTwo heavy operations get awaited so the event loop stays free for\nother requests:\n\n * The embedder call goes through ``embed_async``, which wraps the\n BatchedEmbedder's per-call Future via ``asyncio.wrap_future``.\n While this request waits for its batch to fill on the worker\n thread, the loop services other VUs — that's where the\n concurrency win comes from.\n * ``pss.memory.get_relevant_memories`` runs in a thread via\n ``asyncio.to_thread``. The Rust call releases the GIL during\n the heavy cosine scan, so other handlers progress in parallel.\n\nCheap operations (session lookup, numpy math in compute_*, dict\nwrites in buffer_message) stay inline — wrapping them in to_thread\nwould add more context-switch cost than it saves.", "operationId": "run_v1_run_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/store": { "post": { "summary": "Store", "operationId": "store_v1_store_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/dedup-check": { "post": { "summary": "Dedup Check", "description": "Run the dedup-signal computation against ``req.text`` without\nstoring it. Read-only: no state mutation, no rate-limit\nbookkeeping. Returns the same ``{is_update, max_sim, matched_id}``\ntriple that ``/v1/run`` attaches to its response as\n``dedup_signal``.", "operationId": "dedup_check_v1_dedup_check_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DedupCheckRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DedupSignal" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/session/create": { "post": { "summary": "Create Session", "operationId": "create_session_v1_session_create_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSessionResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/session/{session_id}": { "delete": { "summary": "Delete Session", "operationId": "delete_session_v1_session__session_id__delete", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionIdOnly" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/state/metrics": { "get": { "summary": "Session Metrics", "operationId": "session_metrics_v1_state_metrics_get", "parameters": [ { "name": "session_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/metrics/{session_id}": { "get": { "summary": "Session Metrics", "operationId": "session_metrics_v1_metrics__session_id__get", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Session Id" } }, { "name": "session_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricsResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/state/context": { "get": { "summary": "Session Context", "operationId": "session_context_v1_state_context_get", "parameters": [ { "name": "session_id", "in": "query", "required": true, "schema": { "type": "string", "title": "Session Id" } }, { "name": "top_k", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50, "minimum": 1, "default": 5, "title": "Top K" } }, { "name": "full_first", "in": "query", "required": false, "schema": { "type": "boolean", "description": "When true, the first memory is returned ungutted (truncated=False) so the caller can read the top hit in full without a follow-up /memories/{hash} expand.", "default": false, "title": "Full First" }, "description": "When true, the first memory is returned ungutted (truncated=False) so the caller can read the top hit in full without a follow-up /memories/{hash} expand." }, { "name": "max_text_chars", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100000, "minimum": 1, "description": "Truncation cap applied to each memory's ``text`` field. Default 500. Smaller values shrink the response payload; pass a very large number (e.g. 10000) to effectively disable truncation. ``full_first=true`` still returns the top hit verbatim regardless of this cap.", "default": 500, "title": "Max Text Chars" }, "description": "Truncation cap applied to each memory's ``text`` field. Default 500. Smaller values shrink the response payload; pass a very large number (e.g. 10000) to effectively disable truncation. ``full_first=true`` still returns the top hit verbatim regardless of this cap." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContextResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/session/{session_id}/memories/{memory_hash}": { "get": { "summary": "Expand Memory", "description": "Return the full text + metadata of a single memory.\n\nPaired with ``/v1/state/context``: the context endpoint returns\neach item's ``memory_hash``; the client drills into individual\nmemories here when it needs the full text beyond the 500-char\ndefault truncation.", "operationId": "expand_memory_v1_session__session_id__memories__memory_hash__get", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } }, { "name": "memory_hash", "in": "path", "required": true, "schema": { "type": "string", "title": "Memory Hash" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryExpandResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/session/{session_id}/trigger": { "delete": { "summary": "Clear Triggers", "operationId": "clear_triggers_v1_session__session_id__trigger_delete", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "summary": "Add Trigger", "operationId": "add_trigger_v1_session__session_id__trigger_post", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/session/{session_id}/anchor": { "post": { "summary": "Add Anchor", "operationId": "add_anchor_v1_session__session_id__anchor_post", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnchorRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnchorResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/session/{session_id}/anchor_score": { "get": { "summary": "Anchor Score", "operationId": "anchor_score_v1_session__session_id__anchor_score_get", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnchorScoreResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/session/{session_id}/isolation": { "put": { "summary": "Set Isolation", "operationId": "set_isolation_v1_session__session_id__isolation_put", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IsolationRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IsolationResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/session/{session_id}/isolation/release": { "post": { "summary": "Release Isolation", "operationId": "release_isolation_v1_session__session_id__isolation_release_post", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IsolationReleaseResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/session/{session_id}/memory": { "post": { "summary": "Inject Memory", "operationId": "inject_memory_v1_session__session_id__memory_post", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryInjectRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemoryInjectResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/session/{session_id}/export": { "get": { "summary": "Export Session State", "operationId": "export_session_state_v1_session__session_id__export_get", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/session/{session_id}/import": { "post": { "summary": "Import Session State", "operationId": "import_session_state_v1_session__session_id__import_post", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/session/{session_id}/verify": { "post": { "summary": "Verify Session Consistency", "operationId": "verify_session_consistency_v1_session__session_id__verify_post", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/session/{session_id}/entities": { "get": { "summary": "Query Entities", "operationId": "query_entities_v1_session__session_id__entities_get", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "default": "", "title": "Q" } }, { "name": "max_results", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 20, "title": "Max Results" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityListResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "summary": "Store Entity", "operationId": "store_entity_v1_session__session_id__entities_post", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityCreate" } } } }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/session/{session_id}/entities/{key}": { "delete": { "summary": "Remove Entity", "operationId": "remove_entity_v1_session__session_id__entities__key__delete", "parameters": [ { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string", "title": "Key" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityDeletedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/cluster/": { "get": { "summary": "List Clusters", "operationId": "list_clusters_v1_cluster__get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/ClusterListItem" }, "type": "array", "title": "Response List Clusters V1 Cluster Get" } } } } } }, "post": { "summary": "Create Cluster", "operationId": "create_cluster_v1_cluster__post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterCreate" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterInfo" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/cluster/{cluster_id}": { "delete": { "summary": "Delete Cluster", "operationId": "delete_cluster_v1_cluster__cluster_id__delete", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cluster Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "summary": "Get Cluster", "operationId": "get_cluster_v1_cluster__cluster_id__get", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cluster Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterState" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/cluster/{cluster_id}/members": { "post": { "summary": "Add Member", "operationId": "add_member_v1_cluster__cluster_id__members_post", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cluster Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/cluster/{cluster_id}/members/{session_id}": { "delete": { "summary": "Remove Member", "operationId": "remove_member_v1_cluster__cluster_id__members__session_id__delete", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cluster Id" } }, { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Session Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberRemovedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/cluster/{cluster_id}/store": { "post": { "summary": "Store In Cluster", "operationId": "store_in_cluster_v1_cluster__cluster_id__store_post", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cluster Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "title": "Body" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/cluster/{cluster_id}/run": { "post": { "summary": "Run Cluster", "description": "Query the cluster's backing Semvec session.\n\n``cluster_id`` IS the session_id — we pin it here so callers can\ndrive cluster conversations with a single identifier.\n\nAsync because it delegates to the now-async /v1/run handler.", "operationId": "run_cluster_v1_cluster__cluster_id__run_post", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cluster Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/cluster/{cluster_id}/feedback": { "post": { "summary": "Apply Coupling Feedback", "operationId": "apply_coupling_feedback_v1_cluster__cluster_id__feedback_post", "parameters": [ { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cluster Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClusterFeedbackResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/region/": { "get": { "summary": "List Regions", "operationId": "list_regions_v1_region__get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/RegionListItem" }, "type": "array", "title": "Response List Regions V1 Region Get" } } } } } }, "post": { "summary": "Create Region", "operationId": "create_region_v1_region__post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegionCreate" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegionInfo" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/region/{region_id}": { "delete": { "summary": "Delete Region", "operationId": "delete_region_v1_region__region_id__delete", "parameters": [ { "name": "region_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Region Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "summary": "Get Region", "operationId": "get_region_v1_region__region_id__get", "parameters": [ { "name": "region_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Region Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegionState" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/region/{region_id}/clusters": { "post": { "summary": "Add Cluster", "operationId": "add_cluster_v1_region__region_id__clusters_post", "parameters": [ { "name": "region_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Region Id" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegionClusterRequest" } } } }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/region/{region_id}/clusters/{cluster_id}": { "delete": { "summary": "Remove Cluster", "operationId": "remove_cluster_v1_region__region_id__clusters__cluster_id__delete", "parameters": [ { "name": "region_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Region Id" } }, { "name": "cluster_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Cluster Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/region/{region_id}/events": { "get": { "summary": "Region Events", "operationId": "region_events_v1_region__region_id__events_get", "parameters": [ { "name": "region_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Region Id" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 20, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DriftEventItem" }, "title": "Response Region Events V1 Region Region Id Events Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/observer/": { "post": { "summary": "Create Observer", "operationId": "create_observer_v1_observer__post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObserverCreate" } } }, "required": true }, "responses": { "201": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObserverInfo" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/observer/summary": { "get": { "summary": "Observer Summary", "operationId": "observer_summary_v1_observer_summary_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/v1/observer/sample": { "post": { "summary": "Observer Sample", "operationId": "observer_sample_v1_observer_sample_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/v1/observer/anomalies": { "delete": { "summary": "Observer Clear Anomalies", "operationId": "observer_clear_anomalies_v1_observer_anomalies_delete", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } }, "get": { "summary": "Observer Anomalies", "operationId": "observer_anomalies_v1_observer_anomalies_get", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 1000, "minimum": 1, "default": 20, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/observer/regions": { "post": { "summary": "Observer Register Region", "operationId": "observer_register_region_v1_observer_regions_post", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object", "title": "Body" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/observer/regions/{region_id}": { "delete": { "summary": "Observer Unregister Region", "operationId": "observer_unregister_region_v1_observer_regions__region_id__delete", "parameters": [ { "name": "region_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Region Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/network/transfer": { "post": { "summary": "Transfer Delta", "operationId": "transfer_delta_v1_network_transfer_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeltaTransferRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeltaTransferResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/network/users/switch": { "post": { "summary": "Switch User", "operationId": "switch_user_v1_network_users_switch_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSwitchRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSwitchResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/network/users/active": { "get": { "summary": "Get Active User", "operationId": "get_active_user_v1_network_users_active_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActiveUserResponse" } } } } } } }, "/v1/network/users/{user_id}/serialize": { "post": { "summary": "Serialize User", "operationId": "serialize_user_v1_network_users__user_id__serialize_post", "parameters": [ { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "title": "User Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSerializeResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/network/consensus": { "post": { "summary": "Propose Consensus", "operationId": "propose_consensus_v1_network_consensus_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsensusProposalRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsensusProposalResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/v1/network/consensus/trust": { "get": { "summary": "Get Trust Scores", "operationId": "get_trust_scores_v1_network_consensus_trust_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustScoresResponse" } } } } } } }, "/openai/v1/chat/completions": { "post": { "summary": "Chat Completions", "description": "OpenAI-compatible chat-completions proxy (Steps 15 + 16).\n\n``stream: false`` (default) → a buffered :class:`JSONResponse`;\n``stream: true`` → a :class:`StreamingResponse` of verbatim upstream SSE.\nSee the module docstring / design doc for the full per-request flow. All\nproxy-side failures return an OpenAI-shaped error envelope.", "operationId": "chat_completions_openai_v1_chat_completions_post", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/openai/v1/models": { "get": { "summary": "List Models", "description": "OpenAI-compatible ``GET /models`` — advertise the mapping's model.\n\nAuth mirrors chat/completions (the proxy key resolves to a tenant mapping;\na bad/missing key yields the same 401 envelope). The returned list carries a\nsingle entry for the mapping's ``default_model`` when set — the model this\nproxy key is wired to talk to. An ``x-request-id`` is echoed/minted as on the\nchat surface.", "operationId": "list_models_openai_v1_models_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/openai/v1/{path}": { "delete": { "summary": "Passthrough", "description": "Transparent catch-all — relay any other ``/openai/v1/*`` call to the\nconfigured upstream verbatim (embeddings, files, moderations, …).\n\nRegistered last, so the specific ``/chat/completions`` + ``/models`` routes\ntake precedence. Only active in transparent mode; legacy proxy-key mode has\nno generic passthrough and returns 404.", "operationId": "passthrough_openai_v1__path__delete", "parameters": [ { "name": "path", "in": "path", "required": true, "schema": { "type": "string", "title": "Path" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "get": { "summary": "Passthrough", "description": "Transparent catch-all — relay any other ``/openai/v1/*`` call to the\nconfigured upstream verbatim (embeddings, files, moderations, …).\n\nRegistered last, so the specific ``/chat/completions`` + ``/models`` routes\ntake precedence. Only active in transparent mode; legacy proxy-key mode has\nno generic passthrough and returns 404.", "operationId": "passthrough_openai_v1__path__get", "parameters": [ { "name": "path", "in": "path", "required": true, "schema": { "type": "string", "title": "Path" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "patch": { "summary": "Passthrough", "description": "Transparent catch-all — relay any other ``/openai/v1/*`` call to the\nconfigured upstream verbatim (embeddings, files, moderations, …).\n\nRegistered last, so the specific ``/chat/completions`` + ``/models`` routes\ntake precedence. Only active in transparent mode; legacy proxy-key mode has\nno generic passthrough and returns 404.", "operationId": "passthrough_openai_v1__path__patch", "parameters": [ { "name": "path", "in": "path", "required": true, "schema": { "type": "string", "title": "Path" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "summary": "Passthrough", "description": "Transparent catch-all — relay any other ``/openai/v1/*`` call to the\nconfigured upstream verbatim (embeddings, files, moderations, …).\n\nRegistered last, so the specific ``/chat/completions`` + ``/models`` routes\ntake precedence. Only active in transparent mode; legacy proxy-key mode has\nno generic passthrough and returns 404.", "operationId": "passthrough_openai_v1__path__post", "parameters": [ { "name": "path", "in": "path", "required": true, "schema": { "type": "string", "title": "Path" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "put": { "summary": "Passthrough", "description": "Transparent catch-all — relay any other ``/openai/v1/*`` call to the\nconfigured upstream verbatim (embeddings, files, moderations, …).\n\nRegistered last, so the specific ``/chat/completions`` + ``/models`` routes\ntake precedence. Only active in transparent mode; legacy proxy-key mode has\nno generic passthrough and returns 404.", "operationId": "passthrough_openai_v1__path__put", "parameters": [ { "name": "path", "in": "path", "required": true, "schema": { "type": "string", "title": "Path" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "ActiveUserResponse": { "properties": { "active_user": { "type": "string", "title": "Active User" } }, "type": "object", "required": [ "active_user" ], "title": "ActiveUserResponse" }, "AnchorRequest": { "properties": { "embedding": { "items": { "type": "number" }, "type": "array", "title": "Embedding" } }, "type": "object", "required": [ "embedding" ], "title": "AnchorRequest" }, "AnchorResponse": { "properties": { "session_id": { "type": "string", "title": "Session Id" }, "anchor_count": { "type": "integer", "title": "Anchor Count" } }, "type": "object", "required": [ "session_id", "anchor_count" ], "title": "AnchorResponse" }, "AnchorScoreResponse": { "properties": { "session_id": { "type": "string", "title": "Session Id" }, "anchor_score": { "type": "number", "title": "Anchor Score" }, "anchor_count": { "type": "integer", "title": "Anchor Count" }, "drift_threshold": { "type": "number", "title": "Drift Threshold" }, "realignment_remaining": { "type": "integer", "title": "Realignment Remaining" } }, "type": "object", "required": [ "session_id", "anchor_score", "anchor_count", "drift_threshold", "realignment_remaining" ], "title": "AnchorScoreResponse" }, "ClusterCreate": { "properties": { "name": { "type": "string", "minLength": 1, "title": "Name" }, "aggregation_mode": { "type": "string", "enum": [ "weighted_average", "attention" ], "title": "Aggregation Mode", "default": "weighted_average" }, "coupling_factor": { "type": "number", "maximum": 1.0, "minimum": 0.0, "title": "Coupling Factor", "default": 0.0 }, "drift_exempt": { "type": "boolean", "title": "Drift Exempt", "description": "Pin the cluster's shared session: regional realignment never erodes its dedup index, and the cluster may not join a region. Persisted via SEMVEC_STATE_PERSIST so the pin survives a restart.", "default": false } }, "type": "object", "required": [ "name" ], "title": "ClusterCreate" }, "ClusterFeedbackResponse": { "properties": { "cluster_id": { "type": "string", "title": "Cluster Id" }, "sessions_updated": { "type": "integer", "title": "Sessions Updated" } }, "type": "object", "required": [ "cluster_id", "sessions_updated" ], "title": "ClusterFeedbackResponse" }, "ClusterInfo": { "properties": { "cluster_id": { "type": "string", "title": "Cluster Id" }, "name": { "type": "string", "title": "Name" }, "aggregation_mode": { "type": "string", "title": "Aggregation Mode" }, "coupling_factor": { "type": "number", "title": "Coupling Factor" } }, "type": "object", "required": [ "cluster_id", "name", "aggregation_mode", "coupling_factor" ], "title": "ClusterInfo" }, "ClusterListItem": { "properties": { "cluster_id": { "type": "string", "title": "Cluster Id" }, "name": { "type": "string", "title": "Name" }, "member_count": { "type": "integer", "title": "Member Count" } }, "type": "object", "required": [ "cluster_id", "name", "member_count" ], "title": "ClusterListItem" }, "ClusterState": { "properties": { "cluster_id": { "type": "string", "title": "Cluster Id" }, "name": { "type": "string", "title": "Name" }, "aggregation_mode": { "type": "string", "title": "Aggregation Mode" }, "coupling_factor": { "type": "number", "title": "Coupling Factor" }, "member_count": { "type": "integer", "title": "Member Count" }, "phase": { "type": "string", "title": "Phase" }, "interaction_count": { "type": "integer", "title": "Interaction Count" }, "total_memories": { "type": "integer", "title": "Total Memories" }, "aggregate_vector": { "items": { "type": "number" }, "type": "array", "title": "Aggregate Vector" } }, "type": "object", "required": [ "cluster_id", "name", "aggregation_mode", "coupling_factor", "member_count", "phase", "interaction_count", "total_memories", "aggregate_vector" ], "title": "ClusterState" }, "ConsensusProposalRequest": { "properties": { "proposer_session_id": { "type": "string", "title": "Proposer Session Id" }, "target_embedding": { "items": { "type": "number" }, "type": "array", "title": "Target Embedding" } }, "type": "object", "required": [ "proposer_session_id", "target_embedding" ], "title": "ConsensusProposalRequest" }, "ConsensusProposalResponse": { "properties": { "accepted": { "type": "boolean", "title": "Accepted" }, "trust_scores": { "additionalProperties": { "type": "number" }, "type": "object", "title": "Trust Scores" } }, "type": "object", "required": [ "accepted", "trust_scores" ], "title": "ConsensusProposalResponse" }, "ContextItem": { "properties": { "text": { "type": "string", "title": "Text" }, "relevance": { "type": "number", "title": "Relevance" }, "memory_hash": { "type": "string", "title": "Memory Hash", "default": "" }, "truncated": { "type": "boolean", "title": "Truncated", "default": true } }, "type": "object", "required": [ "text", "relevance" ], "title": "ContextItem" }, "ContextResponse": { "properties": { "session_id": { "type": "string", "title": "Session Id" }, "context": { "items": { "$ref": "#/components/schemas/ContextItem" }, "type": "array", "title": "Context" } }, "type": "object", "required": [ "session_id", "context" ], "title": "ContextResponse" }, "CreateSessionRequest": { "properties": { "session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Session Id" }, "dimension": { "type": "integer", "maximum": 16384.0, "minimum": 1.0, "title": "Dimension", "default": 384 }, "model_name": { "type": "string", "title": "Model Name", "default": "all-MiniLM-L6-v2" }, "use_cortex": { "type": "boolean", "title": "Use Cortex", "description": "Enable cross-session Cortex aggregation (SemvecCortexObserver). The legacy field name ``use_meta_pss`` is still accepted as a deprecated alias and maps to this flag.", "default": false }, "enable_topic_switch": { "type": "boolean", "title": "Enable Topic Switch", "default": true }, "template_embedding": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Template Embedding" }, "policy_vectors": { "anyOf": [ { "items": { "additionalProperties": true, "type": "object" }, "type": "array" }, { "type": "null" } ], "title": "Policy Vectors" } }, "type": "object", "title": "CreateSessionRequest" }, "CreateSessionResponse": { "properties": { "session_id": { "type": "string", "title": "Session Id" }, "created": { "type": "boolean", "title": "Created", "default": true } }, "type": "object", "required": [ "session_id" ], "title": "CreateSessionResponse" }, "DedupCheckRequest": { "properties": { "session_id": { "type": "string", "maxLength": 128, "minLength": 1, "pattern": "^[A-Za-z0-9_-]+$", "title": "Session Id", "description": "Existing session id." }, "text": { "type": "string", "minLength": 1, "title": "Text", "description": "Candidate text that would otherwise be passed to /v1/run." }, "dedup_threshold": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": -1.0 }, { "type": "null" } ], "title": "Dedup Threshold", "description": "Per-call cosine threshold override for is_update (cosine range [-1, 1]). Defaults to SemvecConfig.dedup_update_threshold (typically 0.85)." } }, "type": "object", "required": [ "session_id", "text" ], "title": "DedupCheckRequest", "description": "POST /v1/dedup-check — preview the dedup signal without storing." }, "DedupSignal": { "properties": { "is_update": { "type": "boolean", "title": "Is Update", "description": "True when max_sim exceeds the configured dedup threshold." }, "max_sim": { "type": "number", "maximum": 1.0, "minimum": -1.0, "title": "Max Sim", "description": "Cosine similarity to the closest prior memory." }, "matched_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Matched Id", "description": "UUIDv7 of the prior memory that produced max_sim, or null on cold start." } }, "type": "object", "required": [ "is_update", "max_sim" ], "title": "DedupSignal", "description": "Informational hint emitted by ``SemvecState.update()``.\n\nStorage is append-only regardless of this signal — the caller decides\nwhether to suppress a re-store, merge the incoming context into RAG,\nor just log the event. ``matched_id`` is the UUIDv7 of the prior\nmemory that produced ``max_sim``, or ``None`` on cold start." }, "DeletedResponse": { "properties": { "deleted": { "type": "boolean", "title": "Deleted" } }, "type": "object", "required": [ "deleted" ], "title": "DeletedResponse" }, "DeltaTransferRequest": { "properties": { "source_session_id": { "type": "string", "title": "Source Session Id" }, "target_session_id": { "type": "string", "title": "Target Session Id" }, "max_weight": { "type": "number", "title": "Max Weight", "default": 0.15 } }, "type": "object", "required": [ "source_session_id", "target_session_id" ], "title": "DeltaTransferRequest" }, "DeltaTransferResponse": { "properties": { "source_session_id": { "type": "string", "title": "Source Session Id" }, "target_session_id": { "type": "string", "title": "Target Session Id" }, "delta_norm": { "type": "number", "title": "Delta Norm" } }, "type": "object", "required": [ "source_session_id", "target_session_id", "delta_norm" ], "title": "DeltaTransferResponse" }, "DriftEventItem": { "properties": { "cluster_id": { "type": "string", "title": "Cluster Id" }, "region_id": { "type": "string", "title": "Region Id" }, "drift_score": { "type": "number", "title": "Drift Score" }, "drift_phase": { "type": "string", "title": "Drift Phase" }, "timestamp": { "type": "number", "title": "Timestamp" } }, "type": "object", "required": [ "cluster_id", "region_id", "drift_score", "drift_phase", "timestamp" ], "title": "DriftEventItem" }, "EntityCreate": { "properties": { "key": { "type": "string", "title": "Key" }, "kind": { "type": "string", "enum": [ "variable", "function", "class", "path", "error", "signature", "constant", "type" ], "title": "Kind" }, "value": { "type": "string", "title": "Value" }, "context": { "type": "string", "title": "Context", "default": "" }, "importance": { "type": "number", "title": "Importance", "default": 1.0 } }, "type": "object", "required": [ "key", "kind", "value" ], "title": "EntityCreate" }, "EntityDeletedResponse": { "properties": { "session_id": { "type": "string", "title": "Session Id" }, "key": { "type": "string", "title": "Key" }, "removed": { "type": "boolean", "title": "Removed" } }, "type": "object", "required": [ "session_id", "key", "removed" ], "title": "EntityDeletedResponse" }, "EntityListItem": { "properties": { "key": { "type": "string", "title": "Key" }, "kind": { "type": "string", "title": "Kind" }, "value": { "type": "string", "title": "Value" }, "context": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Context" }, "importance": { "type": "number", "title": "Importance" }, "access_count": { "type": "integer", "title": "Access Count", "default": 0 } }, "type": "object", "required": [ "key", "kind", "value", "importance" ], "title": "EntityListItem" }, "EntityListResponse": { "properties": { "session_id": { "type": "string", "title": "Session Id" }, "entities": { "items": { "$ref": "#/components/schemas/EntityListItem" }, "type": "array", "title": "Entities" }, "total": { "type": "integer", "title": "Total" } }, "type": "object", "required": [ "session_id", "entities", "total" ], "title": "EntityListResponse" }, "EntityResponse": { "properties": { "session_id": { "type": "string", "title": "Session Id" }, "key": { "type": "string", "title": "Key" }, "size": { "type": "integer", "title": "Size" } }, "type": "object", "required": [ "session_id", "key", "size" ], "title": "EntityResponse" }, "ExportResponse": { "properties": { "session_id": { "type": "string", "title": "Session Id" }, "state_dict": { "additionalProperties": true, "type": "object", "title": "State Dict" }, "checksum": { "type": "string", "title": "Checksum" } }, "type": "object", "required": [ "session_id", "state_dict", "checksum" ], "title": "ExportResponse" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "HealthResponse": { "properties": { "status": { "type": "string", "title": "Status", "default": "ok" }, "active_sessions": { "type": "integer", "title": "Active Sessions", "default": 0 }, "version": { "type": "string", "title": "Version", "default": "1.0.0" } }, "type": "object", "title": "HealthResponse" }, "ImportRequest": { "properties": { "state_dict": { "additionalProperties": true, "type": "object", "title": "State Dict" } }, "type": "object", "required": [ "state_dict" ], "title": "ImportRequest" }, "ImportResponse": { "properties": { "session_id": { "type": "string", "title": "Session Id" }, "imported": { "type": "boolean", "title": "Imported" } }, "type": "object", "required": [ "session_id", "imported" ], "title": "ImportResponse" }, "IsolationReleaseResponse": { "properties": { "session_id": { "type": "string", "title": "Session Id" }, "released_count": { "type": "integer", "title": "Released Count" } }, "type": "object", "required": [ "session_id", "released_count" ], "title": "IsolationReleaseResponse" }, "IsolationRequest": { "properties": { "level": { "type": "string", "enum": [ "OPEN", "FILTER", "QUARANTINE", "LOCKDOWN" ], "title": "Level" }, "exclusion_embeddings": { "anyOf": [ { "items": { "items": { "type": "number" }, "type": "array" }, "type": "array" }, { "type": "null" } ], "title": "Exclusion Embeddings" }, "allowlist_embeddings": { "anyOf": [ { "items": { "items": { "type": "number" }, "type": "array" }, "type": "array" }, { "type": "null" } ], "title": "Allowlist Embeddings" }, "similarity_threshold": { "type": "number", "title": "Similarity Threshold", "default": 0.7 } }, "type": "object", "required": [ "level" ], "title": "IsolationRequest" }, "IsolationResponse": { "properties": { "session_id": { "type": "string", "title": "Session Id" }, "level": { "type": "string", "title": "Level" } }, "type": "object", "required": [ "session_id", "level" ], "title": "IsolationResponse" }, "MemberRemovedResponse": { "properties": { "cluster_id": { "type": "string", "title": "Cluster Id" }, "session_id": { "type": "string", "title": "Session Id" }, "removed": { "type": "boolean", "title": "Removed" } }, "type": "object", "required": [ "cluster_id", "session_id", "removed" ], "title": "MemberRemovedResponse" }, "MemberRequest": { "properties": { "session_id": { "type": "string", "title": "Session Id" } }, "type": "object", "required": [ "session_id" ], "title": "MemberRequest" }, "MemberResponse": { "properties": { "cluster_id": { "type": "string", "title": "Cluster Id" }, "session_id": { "type": "string", "title": "Session Id" }, "added": { "type": "boolean", "title": "Added" } }, "type": "object", "required": [ "cluster_id", "session_id", "added" ], "title": "MemberResponse" }, "MemoryExpandResponse": { "properties": { "session_id": { "type": "string", "title": "Session Id" }, "memory_hash": { "type": "string", "title": "Memory Hash" }, "text": { "type": "string", "title": "Text" }, "truncated": { "type": "boolean", "title": "Truncated", "default": false }, "importance": { "type": "number", "title": "Importance" }, "access_count": { "type": "integer", "title": "Access Count" }, "timestamp": { "type": "number", "title": "Timestamp" } }, "type": "object", "required": [ "session_id", "memory_hash", "text", "importance", "access_count", "timestamp" ], "title": "MemoryExpandResponse" }, "MemoryInjectRequest": { "properties": { "embedding": { "items": { "type": "number" }, "type": "array", "title": "Embedding" }, "text": { "type": "string", "title": "Text" }, "tier": { "type": "string", "enum": [ "short_term", "medium_term", "long_term" ], "title": "Tier", "default": "short_term" }, "importance": { "type": "number", "title": "Importance", "default": 0.5 }, "access_count": { "type": "integer", "title": "Access Count", "default": 0 } }, "type": "object", "required": [ "embedding", "text" ], "title": "MemoryInjectRequest" }, "MemoryInjectResponse": { "properties": { "session_id": { "type": "string", "title": "Session Id" }, "tier": { "type": "string", "title": "Tier" }, "total_memories": { "type": "integer", "title": "Total Memories" } }, "type": "object", "required": [ "session_id", "tier", "total_memories" ], "title": "MemoryInjectResponse" }, "MetricsResponse": { "properties": { "session_id": { "type": "string", "title": "Session Id" }, "phase": { "type": "string", "title": "Phase" }, "interaction_count": { "type": "integer", "title": "Interaction Count" }, "total_memories": { "type": "integer", "title": "Total Memories" }, "beta_history": { "items": { "type": "number" }, "type": "array", "title": "Beta History" }, "similarity_history": { "items": { "type": "number" }, "type": "array", "title": "Similarity History" }, "fsm_history": { "items": { "type": "number" }, "type": "array", "title": "Fsm History" }, "norm_history": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Norm History" }, "phase_history": { "items": { "type": "string" }, "type": "array", "title": "Phase History" } }, "type": "object", "required": [ "session_id", "phase", "interaction_count", "total_memories", "beta_history", "similarity_history", "fsm_history", "phase_history" ], "title": "MetricsResponse" }, "ObserverCreate": { "properties": { "sample_interval_seconds": { "type": "number", "title": "Sample Interval Seconds", "default": 30.0 }, "region_ids": { "items": { "type": "string" }, "type": "array", "title": "Region Ids" } }, "type": "object", "title": "ObserverCreate" }, "ObserverInfo": { "properties": { "observer_id": { "type": "string", "title": "Observer Id" }, "registered_regions": { "type": "integer", "title": "Registered Regions" }, "meta_session_id": { "type": "string", "title": "Meta Session Id" } }, "type": "object", "required": [ "observer_id", "registered_regions", "meta_session_id" ], "title": "ObserverInfo" }, "RegionClusterRequest": { "properties": { "cluster_id": { "type": "string", "title": "Cluster Id" } }, "type": "object", "required": [ "cluster_id" ], "title": "RegionClusterRequest" }, "RegionCreate": { "properties": { "name": { "type": "string", "minLength": 1, "title": "Name" }, "consensus_threshold": { "type": "number", "title": "Consensus Threshold", "default": 0.5 }, "vote_window_seconds": { "type": "number", "title": "Vote Window Seconds", "default": 60.0 } }, "type": "object", "required": [ "name" ], "title": "RegionCreate" }, "RegionInfo": { "properties": { "region_id": { "type": "string", "title": "Region Id" }, "name": { "type": "string", "title": "Name" }, "meta_session_id": { "type": "string", "title": "Meta Session Id" } }, "type": "object", "required": [ "region_id", "name", "meta_session_id" ], "title": "RegionInfo" }, "RegionListItem": { "properties": { "region_id": { "type": "string", "title": "Region Id" }, "name": { "type": "string", "title": "Name" }, "cluster_count": { "type": "integer", "title": "Cluster Count" } }, "type": "object", "required": [ "region_id", "name", "cluster_count" ], "title": "RegionListItem" }, "RegionState": { "properties": { "region_id": { "type": "string", "title": "Region Id" }, "name": { "type": "string", "title": "Name" }, "meta_session_id": { "type": "string", "title": "Meta Session Id" }, "cluster_count": { "type": "integer", "title": "Cluster Count" }, "consensus_threshold": { "type": "number", "title": "Consensus Threshold" }, "recent_drift_events": { "items": { "additionalProperties": true, "type": "object" }, "type": "array", "title": "Recent Drift Events" }, "last_realignment": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Last Realignment" } }, "type": "object", "required": [ "region_id", "name", "meta_session_id", "cluster_count", "consensus_threshold", "recent_drift_events", "last_realignment" ], "title": "RegionState" }, "RunRequest": { "properties": { "message": { "type": "string", "minLength": 1, "title": "Message", "description": "User message" }, "session_id": { "anyOf": [ { "type": "string", "maxLength": 128, "pattern": "^[A-Za-z0-9_-]+$" }, { "type": "null" } ], "title": "Session Id", "description": "Reuse an existing session. Omit to create a fresh one." }, "response": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Response", "description": "Previous LLM answer — stored inline as the previous turn's Q&A." }, "short_circuit_threshold": { "type": "number", "maximum": 1.0, "minimum": -1.0, "title": "Short Circuit Threshold", "description": "Similarity threshold for the short-circuit flag.", "default": 0.85 }, "reset_context": { "type": "boolean", "title": "Reset Context", "description": "Wipe all memories and restart the session from scratch.", "default": false }, "user_id": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "User Id", "description": "The data subject this turn belongs to — the person whose memory it becomes, and the key `/v1/compliance/users/{user_id}/...` reads and erases on. Required for the turn to be written to the Compliance Pack's audit trail; omit it and the turn is not audited. This is NOT the licence subject: that is the tenant, enforced separately, and substituting it here would make one person's erasure request delete every user of that tenant." } }, "type": "object", "required": [ "message" ], "title": "RunRequest" }, "RunResponse": { "properties": { "session_id": { "type": "string", "title": "Session Id" }, "context": { "type": "string", "title": "Context", "description": "Compressed context block — inject as system prompt." }, "top_similarity": { "type": "number", "title": "Top Similarity", "default": 0.0 }, "short_circuit": { "type": "boolean", "title": "Short Circuit", "default": false }, "drift_score": { "type": "number", "title": "Drift Score", "default": 0.0 }, "drift_detected": { "type": "boolean", "title": "Drift Detected", "default": false }, "drift_phase": { "type": "string", "enum": [ "stable", "shifting", "drifted" ], "title": "Drift Phase", "default": "stable" }, "dedup_signal": { "anyOf": [ { "$ref": "#/components/schemas/DedupSignal" }, { "type": "null" } ], "description": "Informational dedup hint from the underlying update()." }, "retrieval_error": { "type": "boolean", "title": "Retrieval Error", "description": "True when per-turn memory retrieval faulted and this turn fell back to an empty context. Diagnostic only — the turn still succeeded; the context block just carries no retrieved memories.", "default": false } }, "type": "object", "required": [ "session_id", "context" ], "title": "RunResponse" }, "SessionIdOnly": { "properties": { "session_id": { "type": "string", "title": "Session Id" } }, "type": "object", "required": [ "session_id" ], "title": "SessionIdOnly" }, "StoreRequest": { "properties": { "session_id": { "type": "string", "title": "Session Id" }, "response": { "type": "string", "minLength": 1, "title": "Response" }, "user_id": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "title": "User Id", "description": "The data subject this stored turn belongs to. Same meaning and same rule as on `/v1/run`: it is what the Compliance Pack reads and erases on, it is not the licence subject, and omitting it means the turn is not audited." }, "dedup_threshold": { "anyOf": [ { "type": "number", "maximum": 1.0, "minimum": -1.0 }, { "type": "null" } ], "title": "Dedup Threshold", "description": "Per-call cosine threshold override for the informational dedup_signal.is_update decision, in [-1, 1] (cosine range). Defaults to SemvecConfig.dedup_update_threshold (typically 0.85). Storage is append-only regardless — this only flips the returned signal." } }, "type": "object", "required": [ "session_id", "response" ], "title": "StoreRequest" }, "StoreResponse": { "properties": { "session_id": { "type": "string", "title": "Session Id" } }, "type": "object", "required": [ "session_id" ], "title": "StoreResponse" }, "TriggerRequest": { "properties": { "keyword": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Keyword" }, "embedding": { "anyOf": [ { "items": { "type": "number" }, "type": "array" }, { "type": "null" } ], "title": "Embedding" }, "threshold": { "type": "number", "title": "Threshold", "default": 0.8 } }, "type": "object", "title": "TriggerRequest" }, "TriggerResponse": { "properties": { "session_id": { "type": "string", "title": "Session Id" }, "trigger_count": { "type": "integer", "title": "Trigger Count" } }, "type": "object", "required": [ "session_id", "trigger_count" ], "title": "TriggerResponse" }, "TrustScoresResponse": { "properties": { "trust_scores": { "additionalProperties": { "type": "number" }, "type": "object", "title": "Trust Scores" } }, "type": "object", "required": [ "trust_scores" ], "title": "TrustScoresResponse" }, "UserSerializeResponse": { "properties": { "user_id": { "type": "string", "title": "User Id" }, "state": { "additionalProperties": true, "type": "object", "title": "State" } }, "type": "object", "required": [ "user_id", "state" ], "title": "UserSerializeResponse" }, "UserSwitchRequest": { "properties": { "user_id": { "type": "string", "title": "User Id" } }, "type": "object", "required": [ "user_id" ], "title": "UserSwitchRequest" }, "UserSwitchResponse": { "properties": { "active_user": { "type": "string", "title": "Active User" }, "previous_user": { "type": "string", "title": "Previous User" } }, "type": "object", "required": [ "active_user", "previous_user" ], "title": "UserSwitchResponse" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "VerifyRequest": { "properties": { "test_embeddings": { "items": { "items": { "type": "number" }, "type": "array" }, "type": "array", "title": "Test Embeddings" } }, "type": "object", "required": [ "test_embeddings" ], "title": "VerifyRequest" }, "VerifyResponse": { "properties": { "session_id": { "type": "string", "title": "Session Id" }, "consistent": { "type": "boolean", "title": "Consistent" } }, "type": "object", "required": [ "session_id", "consistent" ], "title": "VerifyResponse" } } } }