7e339e1677
* feat: ai sdk integration * more fixes * fix(security): mental model refresh tag-based security - Mental model refresh now passes tags with all_strict matching - Consolidation only triggers refresh for mental models with matching tags - Consolidation filters related observations by tags (all_strict) - Added tests to verify tag-based security boundaries - Updated OpenAPI spec to include tags and text_preview in list_documents - Added tags column to documents UI table * chore: regenerate OpenAPI spec after rebase * fix: improve consolidation prompt for contradiction handling and mental model refresh security - Enhanced consolidation prompt to be more explicit about capturing temporal changes in contradictions - Fixed mental model refresh security: tagged memories now only trigger refresh of mental models with matching tags - Added stricter tag filtering to prevent cross-scope mental model refreshes Fixes test_consolidation_merges_contradictions by improving LLM instructions to use temporal markers like "used to X, now Y" when merging contradictory facts. Note: test_refresh_with_tags_only_accesses_same_tagged_models still needs investigation - REFLECT operation may need additional tag filtering. * fix: mental model refresh security - proper tag filtering in search Fixed tool_search_mental_models to properly handle all_strict tag matching mode by using the centralized build_tags_where_clause function. Previously, the function only handled "all" vs "any" modes and always included untagged mental models when using non-"all" modes. This ensures that when a tagged mental model is refreshed with all_strict matching, it cannot access untagged mental models, preventing cross-scope information leakage. Fixes test_refresh_with_tags_only_accesses_same_tagged_models. Note: test_sensory_dimension_preservation is failing but this is a pre-existing issue on main branch - the LLM model (gpt-oss-20b) is not extracting facts from sensory text. Not related to security changes. * chore: apply formatting from pre-commit hook * fix: allow untagged mental models to be refreshed by any consolidation Untagged mental models are considered "global" and should be refreshed by any consolidation, regardless of whether tagged or untagged memories were consolidated. This maintains security boundaries while allowing global mental models to stay fresh. When tagged memories are consolidated: - Refresh mental models with matching tags (security boundary) - Also refresh untagged mental models (they're global) - DO NOT refresh mental models with different tags When untagged memories are consolidated: - Only refresh untagged mental models - DO NOT refresh tagged mental models (security boundary) Fixes test_consolidation_only_refreshes_matching_tagged_models.
6248 lines
No EOL
165 KiB
JSON
6248 lines
No EOL
165 KiB
JSON
{
|
|
"openapi": "3.1.0",
|
|
"info": {
|
|
"title": "Hindsight HTTP API",
|
|
"description": "HTTP API for Hindsight",
|
|
"contact": {
|
|
"name": "Memory System"
|
|
},
|
|
"license": {
|
|
"name": "Apache 2.0",
|
|
"url": "https://www.apache.org/licenses/LICENSE-2.0.html"
|
|
},
|
|
"version": "0.4.8"
|
|
},
|
|
"paths": {
|
|
"/health": {
|
|
"get": {
|
|
"tags": [
|
|
"Monitoring"
|
|
],
|
|
"summary": "Health check endpoint",
|
|
"description": "Checks the health of the API and database connection",
|
|
"operationId": "health_endpoint_health_get",
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/version": {
|
|
"get": {
|
|
"tags": [
|
|
"Monitoring"
|
|
],
|
|
"summary": "Get API version and feature flags",
|
|
"description": "Returns API version information and enabled feature flags. Use this to check which capabilities are available in this deployment.",
|
|
"operationId": "get_version",
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/VersionResponse"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/metrics": {
|
|
"get": {
|
|
"tags": [
|
|
"Monitoring"
|
|
],
|
|
"summary": "Prometheus metrics endpoint",
|
|
"description": "Exports metrics in Prometheus format for scraping",
|
|
"operationId": "metrics_endpoint_metrics_get",
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/default/banks/{bank_id}/graph": {
|
|
"get": {
|
|
"tags": [
|
|
"Memory"
|
|
],
|
|
"summary": "Get memory graph data",
|
|
"description": "Retrieve graph data for visualization, optionally filtered by type (world/experience/opinion).",
|
|
"operationId": "get_graph",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "type",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Type"
|
|
}
|
|
},
|
|
{
|
|
"name": "limit",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "integer",
|
|
"default": 1000,
|
|
"title": "Limit"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/GraphDataResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/default/banks/{bank_id}/memories/list": {
|
|
"get": {
|
|
"tags": [
|
|
"Memory"
|
|
],
|
|
"summary": "List memory units",
|
|
"description": "List memory units with pagination and optional full-text search. Supports filtering by type. Results are sorted by most recent first (mentioned_at DESC, then created_at DESC).",
|
|
"operationId": "list_memories",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "type",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Type"
|
|
}
|
|
},
|
|
{
|
|
"name": "q",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Q"
|
|
}
|
|
},
|
|
{
|
|
"name": "limit",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "integer",
|
|
"default": 100,
|
|
"title": "Limit"
|
|
}
|
|
},
|
|
{
|
|
"name": "offset",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "integer",
|
|
"default": 0,
|
|
"title": "Offset"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ListMemoryUnitsResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/default/banks/{bank_id}/memories/{memory_id}": {
|
|
"get": {
|
|
"tags": [
|
|
"Memory"
|
|
],
|
|
"summary": "Get memory unit",
|
|
"description": "Get a single memory unit by ID with all its metadata including entities and tags.",
|
|
"operationId": "get_memory",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "memory_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Memory Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/default/banks/{bank_id}/memories/recall": {
|
|
"post": {
|
|
"tags": [
|
|
"Memory"
|
|
],
|
|
"summary": "Recall memory",
|
|
"description": "Recall memory using semantic similarity and spreading activation.\n\nThe type parameter is optional and must be one of:\n- `world`: General knowledge about people, places, events, and things that happen\n- `experience`: Memories about experience, conversations, actions taken, and tasks performed",
|
|
"operationId": "recall_memories",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/RecallRequest"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/RecallResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/default/banks/{bank_id}/reflect": {
|
|
"post": {
|
|
"tags": [
|
|
"Memory"
|
|
],
|
|
"summary": "Reflect and generate answer",
|
|
"description": "Reflect and formulate an answer using bank identity, world facts, and opinions.\n\nThis endpoint:\n1. Retrieves experience (conversations and events)\n2. Retrieves world facts relevant to the query\n3. Retrieves existing opinions (bank's perspectives)\n4. Uses LLM to formulate a contextual answer\n5. Returns plain text answer and the facts used",
|
|
"operationId": "reflect",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ReflectRequest"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ReflectResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/default/banks": {
|
|
"get": {
|
|
"tags": [
|
|
"Banks"
|
|
],
|
|
"summary": "List all memory banks",
|
|
"description": "Get a list of all agents with their profiles",
|
|
"operationId": "list_banks",
|
|
"parameters": [
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/BankListResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/default/banks/{bank_id}/stats": {
|
|
"get": {
|
|
"tags": [
|
|
"Banks"
|
|
],
|
|
"summary": "Get statistics for memory bank",
|
|
"description": "Get statistics about nodes and links for a specific agent",
|
|
"operationId": "get_agent_stats",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/BankStatsResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/default/banks/{bank_id}/entities": {
|
|
"get": {
|
|
"tags": [
|
|
"Entities"
|
|
],
|
|
"summary": "List entities",
|
|
"description": "List all entities (people, organizations, etc.) known by the bank, ordered by mention count. Supports pagination.",
|
|
"operationId": "list_entities",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "limit",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "integer",
|
|
"description": "Maximum number of entities to return",
|
|
"default": 100,
|
|
"title": "Limit"
|
|
},
|
|
"description": "Maximum number of entities to return"
|
|
},
|
|
{
|
|
"name": "offset",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "integer",
|
|
"description": "Offset for pagination",
|
|
"default": 0,
|
|
"title": "Offset"
|
|
},
|
|
"description": "Offset for pagination"
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"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"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/default/banks/{bank_id}/entities/{entity_id}": {
|
|
"get": {
|
|
"tags": [
|
|
"Entities"
|
|
],
|
|
"summary": "Get entity details",
|
|
"description": "Get detailed information about an entity including observations (mental model).",
|
|
"operationId": "get_entity",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "entity_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Entity Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/EntityDetailResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/default/banks/{bank_id}/entities/{entity_id}/regenerate": {
|
|
"post": {
|
|
"tags": [
|
|
"Entities"
|
|
],
|
|
"summary": "Regenerate entity observations (deprecated)",
|
|
"description": "This endpoint is deprecated. Entity observations have been replaced by mental models.",
|
|
"operationId": "regenerate_entity_observations",
|
|
"deprecated": true,
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "entity_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Entity Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/EntityDetailResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/default/banks/{bank_id}/mental-models": {
|
|
"get": {
|
|
"tags": [
|
|
"Mental Models"
|
|
],
|
|
"summary": "List mental models",
|
|
"description": "List user-curated living documents that stay current.",
|
|
"operationId": "list_mental_models",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "tags",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"description": "Filter by tags",
|
|
"title": "Tags"
|
|
},
|
|
"description": "Filter by tags"
|
|
},
|
|
{
|
|
"name": "tags_match",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"enum": [
|
|
"any",
|
|
"all",
|
|
"exact"
|
|
],
|
|
"type": "string",
|
|
"description": "How to match tags",
|
|
"default": "any",
|
|
"title": "Tags Match"
|
|
},
|
|
"description": "How to match tags"
|
|
},
|
|
{
|
|
"name": "limit",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "integer",
|
|
"maximum": 1000,
|
|
"minimum": 1,
|
|
"default": 100,
|
|
"title": "Limit"
|
|
}
|
|
},
|
|
{
|
|
"name": "offset",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"default": 0,
|
|
"title": "Offset"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/MentalModelListResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"post": {
|
|
"tags": [
|
|
"Mental Models"
|
|
],
|
|
"summary": "Create mental model",
|
|
"description": "Create a mental model by running reflect with the source query in the background. Returns an operation ID to track progress. The content is auto-generated by the reflect endpoint. Use the operations endpoint to check completion status.",
|
|
"operationId": "create_mental_model",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/CreateMentalModelRequest"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/CreateMentalModelResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/default/banks/{bank_id}/mental-models/{mental_model_id}": {
|
|
"get": {
|
|
"tags": [
|
|
"Mental Models"
|
|
],
|
|
"summary": "Get mental model",
|
|
"description": "Get a specific mental model by ID.",
|
|
"operationId": "get_mental_model",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "mental_model_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Mental Model Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/MentalModelResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"patch": {
|
|
"tags": [
|
|
"Mental Models"
|
|
],
|
|
"summary": "Update mental model",
|
|
"description": "Update a mental model's name and/or source query.",
|
|
"operationId": "update_mental_model",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "mental_model_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Mental Model Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/UpdateMentalModelRequest"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/MentalModelResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"delete": {
|
|
"tags": [
|
|
"Mental Models"
|
|
],
|
|
"summary": "Delete mental model",
|
|
"description": "Delete a mental model.",
|
|
"operationId": "delete_mental_model",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "mental_model_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Mental Model Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/default/banks/{bank_id}/mental-models/{mental_model_id}/refresh": {
|
|
"post": {
|
|
"tags": [
|
|
"Mental Models"
|
|
],
|
|
"summary": "Refresh mental model",
|
|
"description": "Submit an async task to re-run the source query through reflect and update the content.",
|
|
"operationId": "refresh_mental_model",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "mental_model_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Mental Model Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AsyncOperationSubmitResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/default/banks/{bank_id}/directives": {
|
|
"get": {
|
|
"tags": [
|
|
"Directives"
|
|
],
|
|
"summary": "List directives",
|
|
"description": "List hard rules that are injected into prompts.",
|
|
"operationId": "list_directives",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "tags",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"description": "Filter by tags",
|
|
"title": "Tags"
|
|
},
|
|
"description": "Filter by tags"
|
|
},
|
|
{
|
|
"name": "tags_match",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"enum": [
|
|
"any",
|
|
"all",
|
|
"exact"
|
|
],
|
|
"type": "string",
|
|
"description": "How to match tags",
|
|
"default": "any",
|
|
"title": "Tags Match"
|
|
},
|
|
"description": "How to match tags"
|
|
},
|
|
{
|
|
"name": "active_only",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "boolean",
|
|
"description": "Only return active directives",
|
|
"default": true,
|
|
"title": "Active Only"
|
|
},
|
|
"description": "Only return active directives"
|
|
},
|
|
{
|
|
"name": "limit",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "integer",
|
|
"maximum": 1000,
|
|
"minimum": 1,
|
|
"default": 100,
|
|
"title": "Limit"
|
|
}
|
|
},
|
|
{
|
|
"name": "offset",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"default": 0,
|
|
"title": "Offset"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/DirectiveListResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"post": {
|
|
"tags": [
|
|
"Directives"
|
|
],
|
|
"summary": "Create directive",
|
|
"description": "Create a hard rule that will be injected into prompts.",
|
|
"operationId": "create_directive",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/CreateDirectiveRequest"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/DirectiveResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/default/banks/{bank_id}/directives/{directive_id}": {
|
|
"get": {
|
|
"tags": [
|
|
"Directives"
|
|
],
|
|
"summary": "Get directive",
|
|
"description": "Get a specific directive by ID.",
|
|
"operationId": "get_directive",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "directive_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Directive Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/DirectiveResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"patch": {
|
|
"tags": [
|
|
"Directives"
|
|
],
|
|
"summary": "Update directive",
|
|
"description": "Update a directive's properties.",
|
|
"operationId": "update_directive",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "directive_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Directive Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/UpdateDirectiveRequest"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/DirectiveResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"delete": {
|
|
"tags": [
|
|
"Directives"
|
|
],
|
|
"summary": "Delete directive",
|
|
"description": "Delete a directive.",
|
|
"operationId": "delete_directive",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "directive_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Directive Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/default/banks/{bank_id}/documents": {
|
|
"get": {
|
|
"tags": [
|
|
"Documents"
|
|
],
|
|
"summary": "List documents",
|
|
"description": "List documents with pagination and optional search. Documents are the source content from which memory units are extracted.",
|
|
"operationId": "list_documents",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "q",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Q"
|
|
}
|
|
},
|
|
{
|
|
"name": "limit",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "integer",
|
|
"default": 100,
|
|
"title": "Limit"
|
|
}
|
|
},
|
|
{
|
|
"name": "offset",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "integer",
|
|
"default": 0,
|
|
"title": "Offset"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ListDocumentsResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/default/banks/{bank_id}/documents/{document_id}": {
|
|
"get": {
|
|
"tags": [
|
|
"Documents"
|
|
],
|
|
"summary": "Get document details",
|
|
"description": "Get a specific document including its original text",
|
|
"operationId": "get_document",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "document_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Document Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/DocumentResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"delete": {
|
|
"tags": [
|
|
"Documents"
|
|
],
|
|
"summary": "Delete a document",
|
|
"description": "Delete a document and all its associated memory units and links.\n\nThis will cascade delete:\n- The document itself\n- All memory units extracted from this document\n- All links (temporal, semantic, entity) associated with those memory units\n\nThis operation cannot be undone.",
|
|
"operationId": "delete_document",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "document_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Document Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/DeleteDocumentResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/default/banks/{bank_id}/tags": {
|
|
"get": {
|
|
"tags": [
|
|
"Memory"
|
|
],
|
|
"summary": "List tags",
|
|
"description": "List all unique tags in a memory bank with usage counts. Supports wildcard search using '*' (e.g., 'user:*', '*-fred', 'tag*-2'). Case-insensitive.",
|
|
"operationId": "list_tags",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "q",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"description": "Wildcard pattern to filter tags (e.g., 'user:*' for user:alice, '*-admin' for role-admin). Use '*' as wildcard. Case-insensitive.",
|
|
"title": "Q"
|
|
},
|
|
"description": "Wildcard pattern to filter tags (e.g., 'user:*' for user:alice, '*-admin' for role-admin). Use '*' as wildcard. Case-insensitive."
|
|
},
|
|
{
|
|
"name": "limit",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "integer",
|
|
"description": "Maximum number of tags to return",
|
|
"default": 100,
|
|
"title": "Limit"
|
|
},
|
|
"description": "Maximum number of tags to return"
|
|
},
|
|
{
|
|
"name": "offset",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "integer",
|
|
"description": "Offset for pagination",
|
|
"default": 0,
|
|
"title": "Offset"
|
|
},
|
|
"description": "Offset for pagination"
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ListTagsResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/default/chunks/{chunk_id}": {
|
|
"get": {
|
|
"tags": [
|
|
"Documents"
|
|
],
|
|
"summary": "Get chunk details",
|
|
"description": "Get a specific chunk by its ID",
|
|
"operationId": "get_chunk",
|
|
"parameters": [
|
|
{
|
|
"name": "chunk_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Chunk Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ChunkResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/default/banks/{bank_id}/operations": {
|
|
"get": {
|
|
"tags": [
|
|
"Operations"
|
|
],
|
|
"summary": "List async operations",
|
|
"description": "Get a list of async operations for a specific agent, with optional filtering by status. Results are sorted by most recent first.",
|
|
"operationId": "list_operations",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "status",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"description": "Filter by status: pending, completed, or failed",
|
|
"title": "Status"
|
|
},
|
|
"description": "Filter by status: pending, completed, or failed"
|
|
},
|
|
{
|
|
"name": "limit",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "integer",
|
|
"maximum": 100,
|
|
"minimum": 1,
|
|
"description": "Maximum number of operations to return",
|
|
"default": 20,
|
|
"title": "Limit"
|
|
},
|
|
"description": "Maximum number of operations to return"
|
|
},
|
|
{
|
|
"name": "offset",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"description": "Number of operations to skip",
|
|
"default": 0,
|
|
"title": "Offset"
|
|
},
|
|
"description": "Number of operations to skip"
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/OperationsListResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/default/banks/{bank_id}/operations/{operation_id}": {
|
|
"get": {
|
|
"tags": [
|
|
"Operations"
|
|
],
|
|
"summary": "Get operation status",
|
|
"description": "Get the status of a specific async operation. Returns 'pending', 'completed', or 'failed'. Completed operations are removed from storage, so 'completed' means the operation finished successfully.",
|
|
"operationId": "get_operation_status",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "operation_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Operation Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/OperationStatusResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"delete": {
|
|
"tags": [
|
|
"Operations"
|
|
],
|
|
"summary": "Cancel a pending async operation",
|
|
"description": "Cancel a pending async operation by removing it from the queue",
|
|
"operationId": "cancel_operation",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "operation_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Operation Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/CancelOperationResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/default/banks/{bank_id}/profile": {
|
|
"get": {
|
|
"tags": [
|
|
"Banks"
|
|
],
|
|
"summary": "Get memory bank profile",
|
|
"description": "Get disposition traits and mission for a memory bank. Auto-creates agent with defaults if not exists.",
|
|
"operationId": "get_bank_profile",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/BankProfileResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"put": {
|
|
"tags": [
|
|
"Banks"
|
|
],
|
|
"summary": "Update memory bank disposition",
|
|
"description": "Update bank's disposition traits (skepticism, literalism, empathy)",
|
|
"operationId": "update_bank_disposition",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/UpdateDispositionRequest"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/BankProfileResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/default/banks/{bank_id}/background": {
|
|
"post": {
|
|
"tags": [
|
|
"Banks"
|
|
],
|
|
"summary": "Add/merge memory bank background (deprecated)",
|
|
"description": "Deprecated: Use PUT /mission instead. This endpoint now updates the mission field.",
|
|
"operationId": "add_bank_background",
|
|
"deprecated": true,
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/AddBackgroundRequest"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/BackgroundResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/default/banks/{bank_id}": {
|
|
"put": {
|
|
"tags": [
|
|
"Banks"
|
|
],
|
|
"summary": "Create or update memory bank",
|
|
"description": "Create a new agent or update existing agent with disposition and mission. Auto-fills missing fields with defaults.",
|
|
"operationId": "create_or_update_bank",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/CreateBankRequest"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/BankProfileResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"patch": {
|
|
"tags": [
|
|
"Banks"
|
|
],
|
|
"summary": "Partial update memory bank",
|
|
"description": "Partially update an agent's profile. Only provided fields will be updated.",
|
|
"operationId": "update_bank",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/CreateBankRequest"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/BankProfileResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"delete": {
|
|
"tags": [
|
|
"Banks"
|
|
],
|
|
"summary": "Delete memory bank",
|
|
"description": "Delete an entire memory bank including all memories, entities, documents, and the bank profile itself. This is a destructive operation that cannot be undone.",
|
|
"operationId": "delete_bank",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/DeleteResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/default/banks/{bank_id}/observations": {
|
|
"delete": {
|
|
"tags": [
|
|
"Banks"
|
|
],
|
|
"summary": "Clear all observations",
|
|
"description": "Delete all observations for a memory bank. This is useful for resetting the consolidated knowledge.",
|
|
"operationId": "clear_observations",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/DeleteResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/default/banks/{bank_id}/consolidate": {
|
|
"post": {
|
|
"tags": [
|
|
"Banks"
|
|
],
|
|
"summary": "Trigger consolidation",
|
|
"description": "Run memory consolidation to create/update observations from recent memories.",
|
|
"operationId": "trigger_consolidation",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/ConsolidationResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"/v1/default/banks/{bank_id}/memories": {
|
|
"post": {
|
|
"tags": [
|
|
"Memory"
|
|
],
|
|
"summary": "Retain memories",
|
|
"description": "Retain memory items with automatic fact extraction.\n\nThis is the main endpoint for storing memories. It supports both synchronous and asynchronous processing via the `async` parameter.\n\n**Features:**\n- Efficient batch processing\n- Automatic fact extraction from natural language\n- Entity recognition and linking\n- Document tracking with automatic upsert (when document_id is provided)\n- Temporal and semantic linking\n- Optional asynchronous processing\n\n**The system automatically:**\n1. Extracts semantic facts from the content\n2. Generates embeddings\n3. Deduplicates similar facts\n4. Creates temporal, semantic, and entity links\n5. Tracks document metadata\n\n**When `async=true`:** Returns immediately after queuing. Use the operations endpoint to monitor progress.\n\n**When `async=false` (default):** Waits for processing to complete.\n\n**Note:** If a memory item has a `document_id` that already exists, the old document and its memory units will be deleted before creating new ones (upsert behavior).",
|
|
"operationId": "retain_memories",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"requestBody": {
|
|
"required": true,
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/RetainRequest"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/RetainResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"delete": {
|
|
"tags": [
|
|
"Memory"
|
|
],
|
|
"summary": "Clear memory bank memories",
|
|
"description": "Delete memory units for a memory bank. Optionally filter by type (world, experience, opinion) to delete only specific types. This is a destructive operation that cannot be undone. The bank profile (disposition and background) will be preserved.",
|
|
"operationId": "clear_bank_memories",
|
|
"parameters": [
|
|
{
|
|
"name": "bank_id",
|
|
"in": "path",
|
|
"required": true,
|
|
"schema": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
}
|
|
},
|
|
{
|
|
"name": "type",
|
|
"in": "query",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"description": "Optional fact type filter (world, experience, opinion)",
|
|
"title": "Type"
|
|
},
|
|
"description": "Optional fact type filter (world, experience, opinion)"
|
|
},
|
|
{
|
|
"name": "authorization",
|
|
"in": "header",
|
|
"required": false,
|
|
"schema": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Authorization"
|
|
}
|
|
}
|
|
],
|
|
"responses": {
|
|
"200": {
|
|
"description": "Successful Response",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/DeleteResponse"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"422": {
|
|
"description": "Validation Error",
|
|
"content": {
|
|
"application/json": {
|
|
"schema": {
|
|
"$ref": "#/components/schemas/HTTPValidationError"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"components": {
|
|
"schemas": {
|
|
"AddBackgroundRequest": {
|
|
"properties": {
|
|
"content": {
|
|
"type": "string",
|
|
"title": "Content",
|
|
"description": "New background information to add or merge"
|
|
},
|
|
"update_disposition": {
|
|
"type": "boolean",
|
|
"title": "Update Disposition",
|
|
"description": "Deprecated - disposition is no longer auto-inferred from mission",
|
|
"default": true
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"content"
|
|
],
|
|
"title": "AddBackgroundRequest",
|
|
"description": "Request model for adding/merging background information. Deprecated: use SetMissionRequest instead.",
|
|
"example": {
|
|
"content": "I was born in Texas",
|
|
"update_disposition": true
|
|
}
|
|
},
|
|
"AsyncOperationSubmitResponse": {
|
|
"properties": {
|
|
"operation_id": {
|
|
"type": "string",
|
|
"title": "Operation Id"
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"title": "Status"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"operation_id",
|
|
"status"
|
|
],
|
|
"title": "AsyncOperationSubmitResponse",
|
|
"description": "Response model for submitting an async operation.",
|
|
"example": {
|
|
"operation_id": "550e8400-e29b-41d4-a716-446655440000",
|
|
"status": "queued"
|
|
}
|
|
},
|
|
"BackgroundResponse": {
|
|
"properties": {
|
|
"mission": {
|
|
"type": "string",
|
|
"title": "Mission"
|
|
},
|
|
"background": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Background",
|
|
"description": "Deprecated: same as mission"
|
|
},
|
|
"disposition": {
|
|
"anyOf": [
|
|
{
|
|
"$ref": "#/components/schemas/DispositionTraits"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"mission"
|
|
],
|
|
"title": "BackgroundResponse",
|
|
"description": "Response model for background update. Deprecated: use MissionResponse instead.",
|
|
"example": {
|
|
"mission": "I was born in Texas. I am a software engineer with 10 years of experience."
|
|
}
|
|
},
|
|
"BankListItem": {
|
|
"properties": {
|
|
"bank_id": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
},
|
|
"name": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Name"
|
|
},
|
|
"disposition": {
|
|
"$ref": "#/components/schemas/DispositionTraits"
|
|
},
|
|
"mission": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Mission"
|
|
},
|
|
"created_at": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Created At"
|
|
},
|
|
"updated_at": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Updated At"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"bank_id",
|
|
"disposition"
|
|
],
|
|
"title": "BankListItem",
|
|
"description": "Bank list item with profile summary."
|
|
},
|
|
"BankListResponse": {
|
|
"properties": {
|
|
"banks": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/BankListItem"
|
|
},
|
|
"type": "array",
|
|
"title": "Banks"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"banks"
|
|
],
|
|
"title": "BankListResponse",
|
|
"description": "Response model for listing all banks.",
|
|
"example": {
|
|
"banks": [
|
|
{
|
|
"bank_id": "user123",
|
|
"created_at": "2024-01-15T10:30:00Z",
|
|
"disposition": {
|
|
"empathy": 3,
|
|
"literalism": 3,
|
|
"skepticism": 3
|
|
},
|
|
"mission": "I am a software engineer helping my team ship quality code",
|
|
"name": "Alice",
|
|
"updated_at": "2024-01-16T14:20:00Z"
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"BankProfileResponse": {
|
|
"properties": {
|
|
"bank_id": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"title": "Name"
|
|
},
|
|
"disposition": {
|
|
"$ref": "#/components/schemas/DispositionTraits"
|
|
},
|
|
"mission": {
|
|
"type": "string",
|
|
"title": "Mission",
|
|
"description": "The agent's mission - who they are and what they're trying to accomplish"
|
|
},
|
|
"background": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Background",
|
|
"description": "Deprecated: use mission instead"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"bank_id",
|
|
"name",
|
|
"disposition",
|
|
"mission"
|
|
],
|
|
"title": "BankProfileResponse",
|
|
"description": "Response model for bank profile.",
|
|
"example": {
|
|
"bank_id": "user123",
|
|
"disposition": {
|
|
"empathy": 3,
|
|
"literalism": 3,
|
|
"skepticism": 3
|
|
},
|
|
"mission": "I am a software engineer helping my team stay organized and ship quality code",
|
|
"name": "Alice"
|
|
}
|
|
},
|
|
"BankStatsResponse": {
|
|
"properties": {
|
|
"bank_id": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
},
|
|
"total_nodes": {
|
|
"type": "integer",
|
|
"title": "Total Nodes"
|
|
},
|
|
"total_links": {
|
|
"type": "integer",
|
|
"title": "Total Links"
|
|
},
|
|
"total_documents": {
|
|
"type": "integer",
|
|
"title": "Total Documents"
|
|
},
|
|
"nodes_by_fact_type": {
|
|
"additionalProperties": {
|
|
"type": "integer"
|
|
},
|
|
"type": "object",
|
|
"title": "Nodes By Fact Type"
|
|
},
|
|
"links_by_link_type": {
|
|
"additionalProperties": {
|
|
"type": "integer"
|
|
},
|
|
"type": "object",
|
|
"title": "Links By Link Type"
|
|
},
|
|
"links_by_fact_type": {
|
|
"additionalProperties": {
|
|
"type": "integer"
|
|
},
|
|
"type": "object",
|
|
"title": "Links By Fact Type"
|
|
},
|
|
"links_breakdown": {
|
|
"additionalProperties": {
|
|
"additionalProperties": {
|
|
"type": "integer"
|
|
},
|
|
"type": "object"
|
|
},
|
|
"type": "object",
|
|
"title": "Links Breakdown"
|
|
},
|
|
"pending_operations": {
|
|
"type": "integer",
|
|
"title": "Pending Operations"
|
|
},
|
|
"failed_operations": {
|
|
"type": "integer",
|
|
"title": "Failed Operations"
|
|
},
|
|
"last_consolidated_at": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Last Consolidated At",
|
|
"description": "When consolidation last ran (ISO format)"
|
|
},
|
|
"pending_consolidation": {
|
|
"type": "integer",
|
|
"title": "Pending Consolidation",
|
|
"description": "Number of memories not yet processed into observations",
|
|
"default": 0
|
|
},
|
|
"total_observations": {
|
|
"type": "integer",
|
|
"title": "Total Observations",
|
|
"description": "Total number of observations",
|
|
"default": 0
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"bank_id",
|
|
"total_nodes",
|
|
"total_links",
|
|
"total_documents",
|
|
"nodes_by_fact_type",
|
|
"links_by_link_type",
|
|
"links_by_fact_type",
|
|
"links_breakdown",
|
|
"pending_operations",
|
|
"failed_operations"
|
|
],
|
|
"title": "BankStatsResponse",
|
|
"description": "Response model for bank statistics endpoint.",
|
|
"example": {
|
|
"bank_id": "user123",
|
|
"failed_operations": 0,
|
|
"last_consolidated_at": "2024-01-15T10:30:00Z",
|
|
"links_breakdown": {
|
|
"fact": {
|
|
"entity": 40,
|
|
"semantic": 60,
|
|
"temporal": 100
|
|
}
|
|
},
|
|
"links_by_fact_type": {
|
|
"fact": 200,
|
|
"observation": 40,
|
|
"preference": 60
|
|
},
|
|
"links_by_link_type": {
|
|
"entity": 50,
|
|
"semantic": 100,
|
|
"temporal": 150
|
|
},
|
|
"nodes_by_fact_type": {
|
|
"fact": 100,
|
|
"observation": 20,
|
|
"preference": 30
|
|
},
|
|
"pending_consolidation": 0,
|
|
"pending_operations": 2,
|
|
"total_documents": 10,
|
|
"total_links": 300,
|
|
"total_nodes": 150,
|
|
"total_observations": 45
|
|
}
|
|
},
|
|
"Budget": {
|
|
"type": "string",
|
|
"enum": [
|
|
"low",
|
|
"mid",
|
|
"high"
|
|
],
|
|
"title": "Budget",
|
|
"description": "Budget levels for recall/reflect operations."
|
|
},
|
|
"CancelOperationResponse": {
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"title": "Success"
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"title": "Message"
|
|
},
|
|
"operation_id": {
|
|
"type": "string",
|
|
"title": "Operation Id"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"success",
|
|
"message",
|
|
"operation_id"
|
|
],
|
|
"title": "CancelOperationResponse",
|
|
"description": "Response model for cancel operation endpoint.",
|
|
"example": {
|
|
"message": "Operation 550e8400-e29b-41d4-a716-446655440000 cancelled",
|
|
"operation_id": "550e8400-e29b-41d4-a716-446655440000",
|
|
"success": true
|
|
}
|
|
},
|
|
"ChunkData": {
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"title": "Id"
|
|
},
|
|
"text": {
|
|
"type": "string",
|
|
"title": "Text"
|
|
},
|
|
"chunk_index": {
|
|
"type": "integer",
|
|
"title": "Chunk Index"
|
|
},
|
|
"truncated": {
|
|
"type": "boolean",
|
|
"title": "Truncated",
|
|
"description": "Whether the chunk text was truncated due to token limits",
|
|
"default": false
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"id",
|
|
"text",
|
|
"chunk_index"
|
|
],
|
|
"title": "ChunkData",
|
|
"description": "Chunk data for a single chunk."
|
|
},
|
|
"ChunkIncludeOptions": {
|
|
"properties": {
|
|
"max_tokens": {
|
|
"type": "integer",
|
|
"title": "Max Tokens",
|
|
"description": "Maximum tokens for chunks (chunks may be truncated)",
|
|
"default": 8192
|
|
}
|
|
},
|
|
"type": "object",
|
|
"title": "ChunkIncludeOptions",
|
|
"description": "Options for including chunks in recall results."
|
|
},
|
|
"ChunkResponse": {
|
|
"properties": {
|
|
"chunk_id": {
|
|
"type": "string",
|
|
"title": "Chunk Id"
|
|
},
|
|
"document_id": {
|
|
"type": "string",
|
|
"title": "Document Id"
|
|
},
|
|
"bank_id": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
},
|
|
"chunk_index": {
|
|
"type": "integer",
|
|
"title": "Chunk Index"
|
|
},
|
|
"chunk_text": {
|
|
"type": "string",
|
|
"title": "Chunk Text"
|
|
},
|
|
"created_at": {
|
|
"type": "string",
|
|
"title": "Created At"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"chunk_id",
|
|
"document_id",
|
|
"bank_id",
|
|
"chunk_index",
|
|
"chunk_text",
|
|
"created_at"
|
|
],
|
|
"title": "ChunkResponse",
|
|
"description": "Response model for get chunk endpoint.",
|
|
"example": {
|
|
"bank_id": "user123",
|
|
"chunk_id": "user123_session_1_0",
|
|
"chunk_index": 0,
|
|
"chunk_text": "This is the first chunk of the document...",
|
|
"created_at": "2024-01-15T10:30:00Z",
|
|
"document_id": "session_1"
|
|
}
|
|
},
|
|
"ConsolidationResponse": {
|
|
"properties": {
|
|
"operation_id": {
|
|
"type": "string",
|
|
"title": "Operation Id",
|
|
"description": "ID of the async consolidation operation"
|
|
},
|
|
"deduplicated": {
|
|
"type": "boolean",
|
|
"title": "Deduplicated",
|
|
"description": "True if an existing pending task was reused",
|
|
"default": false
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"operation_id"
|
|
],
|
|
"title": "ConsolidationResponse",
|
|
"description": "Response model for consolidation trigger endpoint."
|
|
},
|
|
"CreateBankRequest": {
|
|
"properties": {
|
|
"name": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Name"
|
|
},
|
|
"disposition": {
|
|
"anyOf": [
|
|
{
|
|
"$ref": "#/components/schemas/DispositionTraits"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
]
|
|
},
|
|
"mission": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Mission",
|
|
"description": "The agent's mission"
|
|
},
|
|
"background": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Background",
|
|
"description": "Deprecated: use mission instead"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"title": "CreateBankRequest",
|
|
"description": "Request model for creating/updating a bank.",
|
|
"example": {
|
|
"disposition": {
|
|
"empathy": 3,
|
|
"literalism": 3,
|
|
"skepticism": 3
|
|
},
|
|
"mission": "I am a PM helping my engineering team stay organized",
|
|
"name": "Alice"
|
|
}
|
|
},
|
|
"CreateDirectiveRequest": {
|
|
"properties": {
|
|
"name": {
|
|
"type": "string",
|
|
"title": "Name",
|
|
"description": "Human-readable name for the directive"
|
|
},
|
|
"content": {
|
|
"type": "string",
|
|
"title": "Content",
|
|
"description": "The directive text to inject into prompts"
|
|
},
|
|
"priority": {
|
|
"type": "integer",
|
|
"title": "Priority",
|
|
"description": "Higher priority directives are injected first",
|
|
"default": 0
|
|
},
|
|
"is_active": {
|
|
"type": "boolean",
|
|
"title": "Is Active",
|
|
"description": "Whether this directive is active",
|
|
"default": true
|
|
},
|
|
"tags": {
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array",
|
|
"title": "Tags",
|
|
"description": "Tags for filtering"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"name",
|
|
"content"
|
|
],
|
|
"title": "CreateDirectiveRequest",
|
|
"description": "Request model for creating a directive."
|
|
},
|
|
"CreateMentalModelRequest": {
|
|
"properties": {
|
|
"id": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Id",
|
|
"description": "Optional custom ID for the mental model (alphanumeric lowercase with hyphens)"
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"title": "Name",
|
|
"description": "Human-readable name for the mental model"
|
|
},
|
|
"source_query": {
|
|
"type": "string",
|
|
"title": "Source Query",
|
|
"description": "The query to run to generate content"
|
|
},
|
|
"tags": {
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array",
|
|
"title": "Tags",
|
|
"description": "Tags for scoped visibility"
|
|
},
|
|
"max_tokens": {
|
|
"type": "integer",
|
|
"maximum": 8192.0,
|
|
"minimum": 256.0,
|
|
"title": "Max Tokens",
|
|
"description": "Maximum tokens for generated content",
|
|
"default": 2048
|
|
},
|
|
"trigger": {
|
|
"$ref": "#/components/schemas/MentalModelTrigger",
|
|
"description": "Trigger settings"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"name",
|
|
"source_query"
|
|
],
|
|
"title": "CreateMentalModelRequest",
|
|
"description": "Request model for creating a mental model.",
|
|
"example": {
|
|
"id": "team-communication",
|
|
"max_tokens": 2048,
|
|
"name": "Team Communication Preferences",
|
|
"source_query": "How does the team prefer to communicate?",
|
|
"tags": [
|
|
"team"
|
|
],
|
|
"trigger": {
|
|
"refresh_after_consolidation": false
|
|
}
|
|
}
|
|
},
|
|
"CreateMentalModelResponse": {
|
|
"properties": {
|
|
"mental_model_id": {
|
|
"type": "string",
|
|
"title": "Mental Model Id",
|
|
"description": "ID of the created mental model"
|
|
},
|
|
"operation_id": {
|
|
"type": "string",
|
|
"title": "Operation Id",
|
|
"description": "Operation ID to track refresh progress"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"mental_model_id",
|
|
"operation_id"
|
|
],
|
|
"title": "CreateMentalModelResponse",
|
|
"description": "Response model for mental model creation."
|
|
},
|
|
"DeleteDocumentResponse": {
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"title": "Success"
|
|
},
|
|
"message": {
|
|
"type": "string",
|
|
"title": "Message"
|
|
},
|
|
"document_id": {
|
|
"type": "string",
|
|
"title": "Document Id"
|
|
},
|
|
"memory_units_deleted": {
|
|
"type": "integer",
|
|
"title": "Memory Units Deleted"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"success",
|
|
"message",
|
|
"document_id",
|
|
"memory_units_deleted"
|
|
],
|
|
"title": "DeleteDocumentResponse",
|
|
"description": "Response model for delete document endpoint.",
|
|
"example": {
|
|
"document_id": "session_1",
|
|
"memory_units_deleted": 5,
|
|
"message": "Document 'session_1' and 5 associated memory units deleted successfully",
|
|
"success": true
|
|
}
|
|
},
|
|
"DeleteResponse": {
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"title": "Success"
|
|
},
|
|
"message": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Message"
|
|
},
|
|
"deleted_count": {
|
|
"anyOf": [
|
|
{
|
|
"type": "integer"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Deleted Count"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"success"
|
|
],
|
|
"title": "DeleteResponse",
|
|
"description": "Response model for delete operations.",
|
|
"example": {
|
|
"deleted_count": 10,
|
|
"message": "Deleted successfully",
|
|
"success": true
|
|
}
|
|
},
|
|
"DirectiveListResponse": {
|
|
"properties": {
|
|
"items": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/DirectiveResponse"
|
|
},
|
|
"type": "array",
|
|
"title": "Items"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"items"
|
|
],
|
|
"title": "DirectiveListResponse",
|
|
"description": "Response model for listing directives."
|
|
},
|
|
"DirectiveResponse": {
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"title": "Id"
|
|
},
|
|
"bank_id": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"title": "Name"
|
|
},
|
|
"content": {
|
|
"type": "string",
|
|
"title": "Content"
|
|
},
|
|
"priority": {
|
|
"type": "integer",
|
|
"title": "Priority",
|
|
"default": 0
|
|
},
|
|
"is_active": {
|
|
"type": "boolean",
|
|
"title": "Is Active",
|
|
"default": true
|
|
},
|
|
"tags": {
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array",
|
|
"title": "Tags"
|
|
},
|
|
"created_at": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Created At"
|
|
},
|
|
"updated_at": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Updated At"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"id",
|
|
"bank_id",
|
|
"name",
|
|
"content"
|
|
],
|
|
"title": "DirectiveResponse",
|
|
"description": "Response model for a directive."
|
|
},
|
|
"DispositionTraits": {
|
|
"properties": {
|
|
"skepticism": {
|
|
"type": "integer",
|
|
"maximum": 5.0,
|
|
"minimum": 1.0,
|
|
"title": "Skepticism",
|
|
"description": "How skeptical vs trusting (1=trusting, 5=skeptical)"
|
|
},
|
|
"literalism": {
|
|
"type": "integer",
|
|
"maximum": 5.0,
|
|
"minimum": 1.0,
|
|
"title": "Literalism",
|
|
"description": "How literally to interpret information (1=flexible, 5=literal)"
|
|
},
|
|
"empathy": {
|
|
"type": "integer",
|
|
"maximum": 5.0,
|
|
"minimum": 1.0,
|
|
"title": "Empathy",
|
|
"description": "How much to consider emotional context (1=detached, 5=empathetic)"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"skepticism",
|
|
"literalism",
|
|
"empathy"
|
|
],
|
|
"title": "DispositionTraits",
|
|
"description": "Disposition traits that influence how memories are formed and interpreted.",
|
|
"example": {
|
|
"empathy": 3,
|
|
"literalism": 3,
|
|
"skepticism": 3
|
|
}
|
|
},
|
|
"DocumentResponse": {
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"title": "Id"
|
|
},
|
|
"bank_id": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
},
|
|
"original_text": {
|
|
"type": "string",
|
|
"title": "Original Text"
|
|
},
|
|
"content_hash": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Content Hash"
|
|
},
|
|
"created_at": {
|
|
"type": "string",
|
|
"title": "Created At"
|
|
},
|
|
"updated_at": {
|
|
"type": "string",
|
|
"title": "Updated At"
|
|
},
|
|
"memory_unit_count": {
|
|
"type": "integer",
|
|
"title": "Memory Unit Count"
|
|
},
|
|
"tags": {
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array",
|
|
"title": "Tags",
|
|
"description": "Tags associated with this document"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"id",
|
|
"bank_id",
|
|
"original_text",
|
|
"content_hash",
|
|
"created_at",
|
|
"updated_at",
|
|
"memory_unit_count"
|
|
],
|
|
"title": "DocumentResponse",
|
|
"description": "Response model for get document endpoint.",
|
|
"example": {
|
|
"bank_id": "user123",
|
|
"content_hash": "abc123",
|
|
"created_at": "2024-01-15T10:30:00Z",
|
|
"id": "session_1",
|
|
"memory_unit_count": 15,
|
|
"original_text": "Full document text here...",
|
|
"tags": [
|
|
"user_a",
|
|
"session_123"
|
|
],
|
|
"updated_at": "2024-01-15T10:30:00Z"
|
|
}
|
|
},
|
|
"EntityDetailResponse": {
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"title": "Id"
|
|
},
|
|
"canonical_name": {
|
|
"type": "string",
|
|
"title": "Canonical Name"
|
|
},
|
|
"mention_count": {
|
|
"type": "integer",
|
|
"title": "Mention Count"
|
|
},
|
|
"first_seen": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "First Seen"
|
|
},
|
|
"last_seen": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Last Seen"
|
|
},
|
|
"metadata": {
|
|
"anyOf": [
|
|
{
|
|
"additionalProperties": true,
|
|
"type": "object"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Metadata"
|
|
},
|
|
"observations": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/EntityObservationResponse"
|
|
},
|
|
"type": "array",
|
|
"title": "Observations"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"id",
|
|
"canonical_name",
|
|
"mention_count",
|
|
"observations"
|
|
],
|
|
"title": "EntityDetailResponse",
|
|
"description": "Response model for entity detail endpoint.",
|
|
"example": {
|
|
"canonical_name": "John",
|
|
"first_seen": "2024-01-15T10:30:00Z",
|
|
"id": "123e4567-e89b-12d3-a456-426614174000",
|
|
"last_seen": "2024-02-01T14:00:00Z",
|
|
"mention_count": 15,
|
|
"observations": [
|
|
{
|
|
"mentioned_at": "2024-01-15T10:30:00Z",
|
|
"text": "John works at Google"
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"EntityIncludeOptions": {
|
|
"properties": {
|
|
"max_tokens": {
|
|
"type": "integer",
|
|
"title": "Max Tokens",
|
|
"description": "Maximum tokens for entity observations",
|
|
"default": 500
|
|
}
|
|
},
|
|
"type": "object",
|
|
"title": "EntityIncludeOptions",
|
|
"description": "Options for including entity observations in recall results."
|
|
},
|
|
"EntityInput": {
|
|
"properties": {
|
|
"text": {
|
|
"type": "string",
|
|
"title": "Text",
|
|
"description": "The entity name/text"
|
|
},
|
|
"type": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Type",
|
|
"description": "Optional entity type (e.g., 'PERSON', 'ORG', 'CONCEPT')"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"text"
|
|
],
|
|
"title": "EntityInput",
|
|
"description": "Entity to associate with retained content."
|
|
},
|
|
"EntityListItem": {
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"title": "Id"
|
|
},
|
|
"canonical_name": {
|
|
"type": "string",
|
|
"title": "Canonical Name"
|
|
},
|
|
"mention_count": {
|
|
"type": "integer",
|
|
"title": "Mention Count"
|
|
},
|
|
"first_seen": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "First Seen"
|
|
},
|
|
"last_seen": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Last Seen"
|
|
},
|
|
"metadata": {
|
|
"anyOf": [
|
|
{
|
|
"additionalProperties": true,
|
|
"type": "object"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Metadata"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"id",
|
|
"canonical_name",
|
|
"mention_count"
|
|
],
|
|
"title": "EntityListItem",
|
|
"description": "Entity list item with summary.",
|
|
"example": {
|
|
"canonical_name": "John",
|
|
"first_seen": "2024-01-15T10:30:00Z",
|
|
"id": "123e4567-e89b-12d3-a456-426614174000",
|
|
"last_seen": "2024-02-01T14:00:00Z",
|
|
"mention_count": 15
|
|
}
|
|
},
|
|
"EntityListResponse": {
|
|
"properties": {
|
|
"items": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/EntityListItem"
|
|
},
|
|
"type": "array",
|
|
"title": "Items"
|
|
},
|
|
"total": {
|
|
"type": "integer",
|
|
"title": "Total"
|
|
},
|
|
"limit": {
|
|
"type": "integer",
|
|
"title": "Limit"
|
|
},
|
|
"offset": {
|
|
"type": "integer",
|
|
"title": "Offset"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"items",
|
|
"total",
|
|
"limit",
|
|
"offset"
|
|
],
|
|
"title": "EntityListResponse",
|
|
"description": "Response model for entity list endpoint.",
|
|
"example": {
|
|
"items": [
|
|
{
|
|
"canonical_name": "John",
|
|
"first_seen": "2024-01-15T10:30:00Z",
|
|
"id": "123e4567-e89b-12d3-a456-426614174000",
|
|
"last_seen": "2024-02-01T14:00:00Z",
|
|
"mention_count": 15
|
|
}
|
|
],
|
|
"limit": 100,
|
|
"offset": 0,
|
|
"total": 150
|
|
}
|
|
},
|
|
"EntityObservationResponse": {
|
|
"properties": {
|
|
"text": {
|
|
"type": "string",
|
|
"title": "Text"
|
|
},
|
|
"mentioned_at": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Mentioned At"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"text"
|
|
],
|
|
"title": "EntityObservationResponse",
|
|
"description": "An observation about an entity."
|
|
},
|
|
"EntityStateResponse": {
|
|
"properties": {
|
|
"entity_id": {
|
|
"type": "string",
|
|
"title": "Entity Id"
|
|
},
|
|
"canonical_name": {
|
|
"type": "string",
|
|
"title": "Canonical Name"
|
|
},
|
|
"observations": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/EntityObservationResponse"
|
|
},
|
|
"type": "array",
|
|
"title": "Observations"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"entity_id",
|
|
"canonical_name",
|
|
"observations"
|
|
],
|
|
"title": "EntityStateResponse",
|
|
"description": "Current mental model of an entity."
|
|
},
|
|
"FactsIncludeOptions": {
|
|
"properties": {},
|
|
"type": "object",
|
|
"title": "FactsIncludeOptions",
|
|
"description": "Options for including facts (based_on) in reflect results."
|
|
},
|
|
"FeaturesInfo": {
|
|
"properties": {
|
|
"observations": {
|
|
"type": "boolean",
|
|
"title": "Observations",
|
|
"description": "Whether observations (auto-consolidation) are enabled"
|
|
},
|
|
"mcp": {
|
|
"type": "boolean",
|
|
"title": "Mcp",
|
|
"description": "Whether MCP (Model Context Protocol) server is enabled"
|
|
},
|
|
"worker": {
|
|
"type": "boolean",
|
|
"title": "Worker",
|
|
"description": "Whether the background worker is enabled"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"observations",
|
|
"mcp",
|
|
"worker"
|
|
],
|
|
"title": "FeaturesInfo",
|
|
"description": "Feature flags indicating which capabilities are enabled."
|
|
},
|
|
"GraphDataResponse": {
|
|
"properties": {
|
|
"nodes": {
|
|
"items": {
|
|
"additionalProperties": true,
|
|
"type": "object"
|
|
},
|
|
"type": "array",
|
|
"title": "Nodes"
|
|
},
|
|
"edges": {
|
|
"items": {
|
|
"additionalProperties": true,
|
|
"type": "object"
|
|
},
|
|
"type": "array",
|
|
"title": "Edges"
|
|
},
|
|
"table_rows": {
|
|
"items": {
|
|
"additionalProperties": true,
|
|
"type": "object"
|
|
},
|
|
"type": "array",
|
|
"title": "Table Rows"
|
|
},
|
|
"total_units": {
|
|
"type": "integer",
|
|
"title": "Total Units"
|
|
},
|
|
"limit": {
|
|
"type": "integer",
|
|
"title": "Limit"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"nodes",
|
|
"edges",
|
|
"table_rows",
|
|
"total_units",
|
|
"limit"
|
|
],
|
|
"title": "GraphDataResponse",
|
|
"description": "Response model for graph data endpoint.",
|
|
"example": {
|
|
"edges": [
|
|
{
|
|
"from": "1",
|
|
"to": "2",
|
|
"type": "semantic",
|
|
"weight": 0.8
|
|
}
|
|
],
|
|
"limit": 1000,
|
|
"nodes": [
|
|
{
|
|
"id": "1",
|
|
"label": "Alice works at Google",
|
|
"type": "world"
|
|
},
|
|
{
|
|
"id": "2",
|
|
"label": "Bob went hiking",
|
|
"type": "world"
|
|
}
|
|
],
|
|
"table_rows": [
|
|
{
|
|
"context": "Work info",
|
|
"date": "2024-01-15 10:30",
|
|
"entities": "Alice (PERSON), Google (ORGANIZATION)",
|
|
"id": "abc12345...",
|
|
"text": "Alice works at Google"
|
|
}
|
|
],
|
|
"total_units": 2
|
|
}
|
|
},
|
|
"HTTPValidationError": {
|
|
"properties": {
|
|
"detail": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/ValidationError"
|
|
},
|
|
"type": "array",
|
|
"title": "Detail"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"title": "HTTPValidationError"
|
|
},
|
|
"IncludeOptions": {
|
|
"properties": {
|
|
"entities": {
|
|
"anyOf": [
|
|
{
|
|
"$ref": "#/components/schemas/EntityIncludeOptions"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"description": "Include entity observations. Set to null to disable entity inclusion.",
|
|
"default": {
|
|
"max_tokens": 500
|
|
}
|
|
},
|
|
"chunks": {
|
|
"anyOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ChunkIncludeOptions"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"description": "Include raw chunks. Set to {} to enable, null to disable (default: disabled)."
|
|
}
|
|
},
|
|
"type": "object",
|
|
"title": "IncludeOptions",
|
|
"description": "Options for including additional data in recall results."
|
|
},
|
|
"ListDocumentsResponse": {
|
|
"properties": {
|
|
"items": {
|
|
"items": {
|
|
"additionalProperties": true,
|
|
"type": "object"
|
|
},
|
|
"type": "array",
|
|
"title": "Items"
|
|
},
|
|
"total": {
|
|
"type": "integer",
|
|
"title": "Total"
|
|
},
|
|
"limit": {
|
|
"type": "integer",
|
|
"title": "Limit"
|
|
},
|
|
"offset": {
|
|
"type": "integer",
|
|
"title": "Offset"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"items",
|
|
"total",
|
|
"limit",
|
|
"offset"
|
|
],
|
|
"title": "ListDocumentsResponse",
|
|
"description": "Response model for list documents endpoint.",
|
|
"example": {
|
|
"items": [
|
|
{
|
|
"bank_id": "user123",
|
|
"content_hash": "abc123",
|
|
"created_at": "2024-01-15T10:30:00Z",
|
|
"id": "session_1",
|
|
"memory_unit_count": 15,
|
|
"tags": [
|
|
"user_a",
|
|
"session_123"
|
|
],
|
|
"text_length": 5420,
|
|
"updated_at": "2024-01-15T10:30:00Z"
|
|
}
|
|
],
|
|
"limit": 100,
|
|
"offset": 0,
|
|
"total": 50
|
|
}
|
|
},
|
|
"ListMemoryUnitsResponse": {
|
|
"properties": {
|
|
"items": {
|
|
"items": {
|
|
"additionalProperties": true,
|
|
"type": "object"
|
|
},
|
|
"type": "array",
|
|
"title": "Items"
|
|
},
|
|
"total": {
|
|
"type": "integer",
|
|
"title": "Total"
|
|
},
|
|
"limit": {
|
|
"type": "integer",
|
|
"title": "Limit"
|
|
},
|
|
"offset": {
|
|
"type": "integer",
|
|
"title": "Offset"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"items",
|
|
"total",
|
|
"limit",
|
|
"offset"
|
|
],
|
|
"title": "ListMemoryUnitsResponse",
|
|
"description": "Response model for list memory units endpoint.",
|
|
"example": {
|
|
"items": [
|
|
{
|
|
"context": "Work conversation",
|
|
"date": "2024-01-15T10:30:00Z",
|
|
"entities": "Alice (PERSON), Google (ORGANIZATION)",
|
|
"id": "550e8400-e29b-41d4-a716-446655440000",
|
|
"text": "Alice works at Google on the AI team",
|
|
"type": "world"
|
|
}
|
|
],
|
|
"limit": 100,
|
|
"offset": 0,
|
|
"total": 150
|
|
}
|
|
},
|
|
"ListTagsResponse": {
|
|
"properties": {
|
|
"items": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/TagItem"
|
|
},
|
|
"type": "array",
|
|
"title": "Items"
|
|
},
|
|
"total": {
|
|
"type": "integer",
|
|
"title": "Total"
|
|
},
|
|
"limit": {
|
|
"type": "integer",
|
|
"title": "Limit"
|
|
},
|
|
"offset": {
|
|
"type": "integer",
|
|
"title": "Offset"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"items",
|
|
"total",
|
|
"limit",
|
|
"offset"
|
|
],
|
|
"title": "ListTagsResponse",
|
|
"description": "Response model for list tags endpoint.",
|
|
"example": {
|
|
"items": [
|
|
{
|
|
"count": 42,
|
|
"tag": "user:alice"
|
|
},
|
|
{
|
|
"count": 15,
|
|
"tag": "user:bob"
|
|
},
|
|
{
|
|
"count": 8,
|
|
"tag": "session:abc123"
|
|
}
|
|
],
|
|
"limit": 100,
|
|
"offset": 0,
|
|
"total": 25
|
|
}
|
|
},
|
|
"MemoryItem": {
|
|
"properties": {
|
|
"content": {
|
|
"type": "string",
|
|
"title": "Content"
|
|
},
|
|
"timestamp": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string",
|
|
"format": "date-time"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Timestamp"
|
|
},
|
|
"context": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Context"
|
|
},
|
|
"metadata": {
|
|
"anyOf": [
|
|
{
|
|
"additionalProperties": {
|
|
"type": "string"
|
|
},
|
|
"type": "object"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Metadata"
|
|
},
|
|
"document_id": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Document Id",
|
|
"description": "Optional document ID for this memory item."
|
|
},
|
|
"entities": {
|
|
"anyOf": [
|
|
{
|
|
"items": {
|
|
"$ref": "#/components/schemas/EntityInput"
|
|
},
|
|
"type": "array"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Entities",
|
|
"description": "Optional entities to combine with auto-extracted entities."
|
|
},
|
|
"tags": {
|
|
"anyOf": [
|
|
{
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Tags",
|
|
"description": "Optional tags for visibility scoping. Memories with tags can be filtered during recall."
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"content"
|
|
],
|
|
"title": "MemoryItem",
|
|
"description": "Single memory item for retain.",
|
|
"example": {
|
|
"content": "Alice mentioned she's working on a new ML model",
|
|
"context": "team meeting",
|
|
"document_id": "meeting_notes_2024_01_15",
|
|
"entities": [
|
|
{
|
|
"text": "Alice"
|
|
},
|
|
{
|
|
"text": "ML model",
|
|
"type": "CONCEPT"
|
|
}
|
|
],
|
|
"metadata": {
|
|
"channel": "engineering",
|
|
"source": "slack"
|
|
},
|
|
"tags": [
|
|
"user_a",
|
|
"user_b"
|
|
],
|
|
"timestamp": "2024-01-15T10:30:00Z"
|
|
}
|
|
},
|
|
"MentalModelListResponse": {
|
|
"properties": {
|
|
"items": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/MentalModelResponse"
|
|
},
|
|
"type": "array",
|
|
"title": "Items"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"items"
|
|
],
|
|
"title": "MentalModelListResponse",
|
|
"description": "Response model for listing mental models."
|
|
},
|
|
"MentalModelResponse": {
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"title": "Id"
|
|
},
|
|
"bank_id": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"title": "Name"
|
|
},
|
|
"source_query": {
|
|
"type": "string",
|
|
"title": "Source Query"
|
|
},
|
|
"content": {
|
|
"type": "string",
|
|
"title": "Content"
|
|
},
|
|
"tags": {
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array",
|
|
"title": "Tags"
|
|
},
|
|
"max_tokens": {
|
|
"type": "integer",
|
|
"title": "Max Tokens",
|
|
"default": 2048
|
|
},
|
|
"trigger": {
|
|
"$ref": "#/components/schemas/MentalModelTrigger"
|
|
},
|
|
"last_refreshed_at": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Last Refreshed At"
|
|
},
|
|
"created_at": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Created At"
|
|
},
|
|
"reflect_response": {
|
|
"anyOf": [
|
|
{
|
|
"additionalProperties": true,
|
|
"type": "object"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Reflect Response",
|
|
"description": "Full reflect API response payload including based_on facts and observations"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"id",
|
|
"bank_id",
|
|
"name",
|
|
"source_query",
|
|
"content"
|
|
],
|
|
"title": "MentalModelResponse",
|
|
"description": "Response model for a mental model (stored reflect response)."
|
|
},
|
|
"MentalModelTrigger": {
|
|
"properties": {
|
|
"refresh_after_consolidation": {
|
|
"type": "boolean",
|
|
"title": "Refresh After Consolidation",
|
|
"description": "If true, refresh this mental model after observations consolidation (real-time mode)",
|
|
"default": false
|
|
}
|
|
},
|
|
"type": "object",
|
|
"title": "MentalModelTrigger",
|
|
"description": "Trigger settings for a mental model."
|
|
},
|
|
"OperationResponse": {
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"title": "Id"
|
|
},
|
|
"task_type": {
|
|
"type": "string",
|
|
"title": "Task Type"
|
|
},
|
|
"items_count": {
|
|
"type": "integer",
|
|
"title": "Items Count"
|
|
},
|
|
"document_id": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Document Id"
|
|
},
|
|
"created_at": {
|
|
"type": "string",
|
|
"title": "Created At"
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"title": "Status"
|
|
},
|
|
"error_message": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Error Message"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"id",
|
|
"task_type",
|
|
"items_count",
|
|
"created_at",
|
|
"status",
|
|
"error_message"
|
|
],
|
|
"title": "OperationResponse",
|
|
"description": "Response model for a single async operation.",
|
|
"example": {
|
|
"created_at": "2024-01-15T10:30:00Z",
|
|
"id": "550e8400-e29b-41d4-a716-446655440000",
|
|
"items_count": 5,
|
|
"status": "pending",
|
|
"task_type": "retain"
|
|
}
|
|
},
|
|
"OperationStatusResponse": {
|
|
"properties": {
|
|
"operation_id": {
|
|
"type": "string",
|
|
"title": "Operation Id"
|
|
},
|
|
"status": {
|
|
"type": "string",
|
|
"enum": [
|
|
"pending",
|
|
"completed",
|
|
"failed",
|
|
"not_found"
|
|
],
|
|
"title": "Status"
|
|
},
|
|
"operation_type": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Operation Type"
|
|
},
|
|
"created_at": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Created At"
|
|
},
|
|
"updated_at": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Updated At"
|
|
},
|
|
"completed_at": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Completed At"
|
|
},
|
|
"error_message": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Error Message"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"operation_id",
|
|
"status"
|
|
],
|
|
"title": "OperationStatusResponse",
|
|
"description": "Response model for getting a single operation status.",
|
|
"example": {
|
|
"completed_at": "2024-01-15T10:31:30Z",
|
|
"created_at": "2024-01-15T10:30:00Z",
|
|
"operation_id": "550e8400-e29b-41d4-a716-446655440000",
|
|
"operation_type": "refresh_mental_models",
|
|
"status": "completed",
|
|
"updated_at": "2024-01-15T10:31:30Z"
|
|
}
|
|
},
|
|
"OperationsListResponse": {
|
|
"properties": {
|
|
"bank_id": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
},
|
|
"total": {
|
|
"type": "integer",
|
|
"title": "Total"
|
|
},
|
|
"limit": {
|
|
"type": "integer",
|
|
"title": "Limit"
|
|
},
|
|
"offset": {
|
|
"type": "integer",
|
|
"title": "Offset"
|
|
},
|
|
"operations": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/OperationResponse"
|
|
},
|
|
"type": "array",
|
|
"title": "Operations"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"bank_id",
|
|
"total",
|
|
"limit",
|
|
"offset",
|
|
"operations"
|
|
],
|
|
"title": "OperationsListResponse",
|
|
"description": "Response model for list operations endpoint.",
|
|
"example": {
|
|
"bank_id": "user123",
|
|
"limit": 20,
|
|
"offset": 0,
|
|
"operations": [
|
|
{
|
|
"created_at": "2024-01-15T10:30:00Z",
|
|
"id": "550e8400-e29b-41d4-a716-446655440000",
|
|
"status": "pending",
|
|
"task_type": "retain"
|
|
}
|
|
],
|
|
"total": 150
|
|
}
|
|
},
|
|
"RecallRequest": {
|
|
"properties": {
|
|
"query": {
|
|
"type": "string",
|
|
"title": "Query"
|
|
},
|
|
"types": {
|
|
"anyOf": [
|
|
{
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Types",
|
|
"description": "List of fact types to recall: 'world', 'experience', 'observation'. Defaults to world and experience if not specified."
|
|
},
|
|
"budget": {
|
|
"$ref": "#/components/schemas/Budget",
|
|
"default": "mid"
|
|
},
|
|
"max_tokens": {
|
|
"type": "integer",
|
|
"title": "Max Tokens",
|
|
"default": 4096
|
|
},
|
|
"trace": {
|
|
"type": "boolean",
|
|
"title": "Trace",
|
|
"default": false
|
|
},
|
|
"query_timestamp": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Query Timestamp",
|
|
"description": "ISO format date string (e.g., '2023-05-30T23:40:00')"
|
|
},
|
|
"include": {
|
|
"$ref": "#/components/schemas/IncludeOptions",
|
|
"description": "Options for including additional data (entities are included by default)"
|
|
},
|
|
"tags": {
|
|
"anyOf": [
|
|
{
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Tags",
|
|
"description": "Filter memories by tags. If not specified, all memories are returned."
|
|
},
|
|
"tags_match": {
|
|
"type": "string",
|
|
"enum": [
|
|
"any",
|
|
"all",
|
|
"any_strict",
|
|
"all_strict"
|
|
],
|
|
"title": "Tags Match",
|
|
"description": "How to match tags: 'any' (OR, includes untagged), 'all' (AND, includes untagged), 'any_strict' (OR, excludes untagged), 'all_strict' (AND, excludes untagged).",
|
|
"default": "any"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"query"
|
|
],
|
|
"title": "RecallRequest",
|
|
"description": "Request model for recall endpoint.",
|
|
"example": {
|
|
"budget": "mid",
|
|
"include": {
|
|
"entities": {
|
|
"max_tokens": 500
|
|
}
|
|
},
|
|
"max_tokens": 4096,
|
|
"query": "What did Alice say about machine learning?",
|
|
"query_timestamp": "2023-05-30T23:40:00",
|
|
"tags": [
|
|
"user_a"
|
|
],
|
|
"tags_match": "any",
|
|
"trace": true,
|
|
"types": [
|
|
"world",
|
|
"experience"
|
|
]
|
|
}
|
|
},
|
|
"RecallResponse": {
|
|
"properties": {
|
|
"results": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/RecallResult"
|
|
},
|
|
"type": "array",
|
|
"title": "Results"
|
|
},
|
|
"trace": {
|
|
"anyOf": [
|
|
{
|
|
"additionalProperties": true,
|
|
"type": "object"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Trace"
|
|
},
|
|
"entities": {
|
|
"anyOf": [
|
|
{
|
|
"additionalProperties": {
|
|
"$ref": "#/components/schemas/EntityStateResponse"
|
|
},
|
|
"type": "object"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Entities",
|
|
"description": "Entity states for entities mentioned in results"
|
|
},
|
|
"chunks": {
|
|
"anyOf": [
|
|
{
|
|
"additionalProperties": {
|
|
"$ref": "#/components/schemas/ChunkData"
|
|
},
|
|
"type": "object"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Chunks",
|
|
"description": "Chunks for facts, keyed by chunk_id"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"results"
|
|
],
|
|
"title": "RecallResponse",
|
|
"description": "Response model for recall endpoints.",
|
|
"example": {
|
|
"chunks": {
|
|
"456e7890-e12b-34d5-a678-901234567890": {
|
|
"chunk_index": 0,
|
|
"id": "456e7890-e12b-34d5-a678-901234567890",
|
|
"text": "Alice works at Google on the AI team. She's been there for 3 years..."
|
|
}
|
|
},
|
|
"entities": {
|
|
"Alice": {
|
|
"canonical_name": "Alice",
|
|
"entity_id": "123e4567-e89b-12d3-a456-426614174001",
|
|
"observations": [
|
|
{
|
|
"mentioned_at": "2024-01-15T10:30:00Z",
|
|
"text": "Alice works at Google on the AI team"
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"results": [
|
|
{
|
|
"chunk_id": "456e7890-e12b-34d5-a678-901234567890",
|
|
"context": "work info",
|
|
"entities": [
|
|
"Alice",
|
|
"Google"
|
|
],
|
|
"id": "123e4567-e89b-12d3-a456-426614174000",
|
|
"occurred_end": "2024-01-15T10:30:00Z",
|
|
"occurred_start": "2024-01-15T10:30:00Z",
|
|
"text": "Alice works at Google on the AI team",
|
|
"type": "world"
|
|
}
|
|
],
|
|
"trace": {
|
|
"num_results": 1,
|
|
"query": "What did Alice say about machine learning?",
|
|
"time_seconds": 0.123
|
|
}
|
|
}
|
|
},
|
|
"RecallResult": {
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"title": "Id"
|
|
},
|
|
"text": {
|
|
"type": "string",
|
|
"title": "Text"
|
|
},
|
|
"type": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Type"
|
|
},
|
|
"entities": {
|
|
"anyOf": [
|
|
{
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Entities"
|
|
},
|
|
"context": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Context"
|
|
},
|
|
"occurred_start": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Occurred Start"
|
|
},
|
|
"occurred_end": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Occurred End"
|
|
},
|
|
"mentioned_at": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Mentioned At"
|
|
},
|
|
"document_id": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Document Id"
|
|
},
|
|
"metadata": {
|
|
"anyOf": [
|
|
{
|
|
"additionalProperties": {
|
|
"type": "string"
|
|
},
|
|
"type": "object"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Metadata"
|
|
},
|
|
"chunk_id": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Chunk Id"
|
|
},
|
|
"tags": {
|
|
"anyOf": [
|
|
{
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Tags"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"id",
|
|
"text"
|
|
],
|
|
"title": "RecallResult",
|
|
"description": "Single recall result item.",
|
|
"example": {
|
|
"chunk_id": "456e7890-e12b-34d5-a678-901234567890",
|
|
"context": "work info",
|
|
"document_id": "session_abc123",
|
|
"entities": [
|
|
"Alice",
|
|
"Google"
|
|
],
|
|
"id": "123e4567-e89b-12d3-a456-426614174000",
|
|
"mentioned_at": "2024-01-15T10:30:00Z",
|
|
"metadata": {
|
|
"source": "slack"
|
|
},
|
|
"occurred_end": "2024-01-15T10:30:00Z",
|
|
"occurred_start": "2024-01-15T10:30:00Z",
|
|
"tags": [
|
|
"user_a",
|
|
"user_b"
|
|
],
|
|
"text": "Alice works at Google on the AI team",
|
|
"type": "world"
|
|
}
|
|
},
|
|
"ReflectBasedOn": {
|
|
"properties": {
|
|
"memories": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/ReflectFact"
|
|
},
|
|
"type": "array",
|
|
"title": "Memories",
|
|
"description": "Memory facts used to generate the response"
|
|
},
|
|
"mental_models": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/ReflectMentalModel"
|
|
},
|
|
"type": "array",
|
|
"title": "Mental Models",
|
|
"description": "Mental models used during reflection"
|
|
},
|
|
"directives": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/ReflectDirective"
|
|
},
|
|
"type": "array",
|
|
"title": "Directives",
|
|
"description": "Directives applied during reflection"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"title": "ReflectBasedOn",
|
|
"description": "Evidence the response is based on: memories, mental models, and directives."
|
|
},
|
|
"ReflectDirective": {
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"title": "Id",
|
|
"description": "Directive ID"
|
|
},
|
|
"name": {
|
|
"type": "string",
|
|
"title": "Name",
|
|
"description": "Directive name"
|
|
},
|
|
"content": {
|
|
"type": "string",
|
|
"title": "Content",
|
|
"description": "Directive content"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"id",
|
|
"name",
|
|
"content"
|
|
],
|
|
"title": "ReflectDirective",
|
|
"description": "A directive applied during reflect."
|
|
},
|
|
"ReflectFact": {
|
|
"properties": {
|
|
"id": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Id"
|
|
},
|
|
"text": {
|
|
"type": "string",
|
|
"title": "Text"
|
|
},
|
|
"type": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Type"
|
|
},
|
|
"context": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Context"
|
|
},
|
|
"occurred_start": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Occurred Start"
|
|
},
|
|
"occurred_end": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Occurred End"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"text"
|
|
],
|
|
"title": "ReflectFact",
|
|
"description": "A fact used in think response.",
|
|
"example": {
|
|
"context": "healthcare discussion",
|
|
"id": "123e4567-e89b-12d3-a456-426614174000",
|
|
"occurred_end": "2024-01-15T10:30:00Z",
|
|
"occurred_start": "2024-01-15T10:30:00Z",
|
|
"text": "AI is used in healthcare",
|
|
"type": "world"
|
|
}
|
|
},
|
|
"ReflectIncludeOptions": {
|
|
"properties": {
|
|
"facts": {
|
|
"anyOf": [
|
|
{
|
|
"$ref": "#/components/schemas/FactsIncludeOptions"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"description": "Include facts that the answer is based on. Set to {} to enable, null to disable (default: disabled)."
|
|
},
|
|
"tool_calls": {
|
|
"anyOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ToolCallsIncludeOptions"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"description": "Include tool calls trace. Set to {} for full trace (input+output), {output: false} for inputs only."
|
|
}
|
|
},
|
|
"type": "object",
|
|
"title": "ReflectIncludeOptions",
|
|
"description": "Options for including additional data in reflect results."
|
|
},
|
|
"ReflectLLMCall": {
|
|
"properties": {
|
|
"scope": {
|
|
"type": "string",
|
|
"title": "Scope",
|
|
"description": "Call scope: agent_1, agent_2, final, etc."
|
|
},
|
|
"duration_ms": {
|
|
"type": "integer",
|
|
"title": "Duration Ms",
|
|
"description": "Execution time in milliseconds"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"scope",
|
|
"duration_ms"
|
|
],
|
|
"title": "ReflectLLMCall",
|
|
"description": "An LLM call made during reflect agent execution."
|
|
},
|
|
"ReflectMentalModel": {
|
|
"properties": {
|
|
"id": {
|
|
"type": "string",
|
|
"title": "Id",
|
|
"description": "Mental model ID"
|
|
},
|
|
"text": {
|
|
"type": "string",
|
|
"title": "Text",
|
|
"description": "Mental model content"
|
|
},
|
|
"context": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Context",
|
|
"description": "Additional context"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"id",
|
|
"text"
|
|
],
|
|
"title": "ReflectMentalModel",
|
|
"description": "A mental model used during reflect."
|
|
},
|
|
"ReflectRequest": {
|
|
"properties": {
|
|
"query": {
|
|
"type": "string",
|
|
"title": "Query"
|
|
},
|
|
"budget": {
|
|
"$ref": "#/components/schemas/Budget",
|
|
"default": "low"
|
|
},
|
|
"context": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Context",
|
|
"description": "DEPRECATED: Additional context is now concatenated with the query. Pass context directly in the query field instead. If provided, it will be appended to the query for backward compatibility.",
|
|
"deprecated": true
|
|
},
|
|
"max_tokens": {
|
|
"type": "integer",
|
|
"title": "Max Tokens",
|
|
"description": "Maximum tokens for the response",
|
|
"default": 4096
|
|
},
|
|
"include": {
|
|
"$ref": "#/components/schemas/ReflectIncludeOptions",
|
|
"description": "Options for including additional data (disabled by default)"
|
|
},
|
|
"response_schema": {
|
|
"anyOf": [
|
|
{
|
|
"additionalProperties": true,
|
|
"type": "object"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Response Schema",
|
|
"description": "Optional JSON Schema for structured output. When provided, the response will include a 'structured_output' field with the LLM response parsed according to this schema."
|
|
},
|
|
"tags": {
|
|
"anyOf": [
|
|
{
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Tags",
|
|
"description": "Filter memories by tags during reflection. If not specified, all memories are considered."
|
|
},
|
|
"tags_match": {
|
|
"type": "string",
|
|
"enum": [
|
|
"any",
|
|
"all",
|
|
"any_strict",
|
|
"all_strict"
|
|
],
|
|
"title": "Tags Match",
|
|
"description": "How to match tags: 'any' (OR, includes untagged), 'all' (AND, includes untagged), 'any_strict' (OR, excludes untagged), 'all_strict' (AND, excludes untagged).",
|
|
"default": "any"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"query"
|
|
],
|
|
"title": "ReflectRequest",
|
|
"description": "Request model for reflect endpoint.",
|
|
"example": {
|
|
"budget": "low",
|
|
"include": {
|
|
"facts": {}
|
|
},
|
|
"max_tokens": 4096,
|
|
"query": "What do you think about artificial intelligence?",
|
|
"response_schema": {
|
|
"properties": {
|
|
"summary": {
|
|
"type": "string"
|
|
},
|
|
"key_points": {
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
}
|
|
},
|
|
"required": [
|
|
"summary",
|
|
"key_points"
|
|
],
|
|
"type": "object"
|
|
},
|
|
"tags": [
|
|
"user_a"
|
|
],
|
|
"tags_match": "any"
|
|
}
|
|
},
|
|
"ReflectResponse": {
|
|
"properties": {
|
|
"text": {
|
|
"type": "string",
|
|
"title": "Text"
|
|
},
|
|
"based_on": {
|
|
"anyOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ReflectBasedOn"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"description": "Evidence used to generate the response. Only present when include.facts is set."
|
|
},
|
|
"structured_output": {
|
|
"anyOf": [
|
|
{
|
|
"additionalProperties": true,
|
|
"type": "object"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Structured Output",
|
|
"description": "Structured output parsed according to the request's response_schema. Only present when response_schema was provided in the request."
|
|
},
|
|
"usage": {
|
|
"anyOf": [
|
|
{
|
|
"$ref": "#/components/schemas/TokenUsage"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"description": "Token usage metrics for LLM calls during reflection."
|
|
},
|
|
"trace": {
|
|
"anyOf": [
|
|
{
|
|
"$ref": "#/components/schemas/ReflectTrace"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"description": "Execution trace of tool and LLM calls. Only present when include.tool_calls is set."
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"text"
|
|
],
|
|
"title": "ReflectResponse",
|
|
"description": "Response model for think endpoint.",
|
|
"example": {
|
|
"based_on": {
|
|
"memories": [
|
|
{
|
|
"id": "123",
|
|
"text": "AI is used in healthcare",
|
|
"type": "world"
|
|
},
|
|
{
|
|
"id": "456",
|
|
"text": "I discussed AI applications last week",
|
|
"type": "experience"
|
|
}
|
|
]
|
|
},
|
|
"structured_output": {
|
|
"key_points": [
|
|
"Used in healthcare",
|
|
"Discussed recently"
|
|
],
|
|
"summary": "AI is transformative"
|
|
},
|
|
"text": "Based on my understanding, AI is a transformative technology...",
|
|
"trace": {
|
|
"llm_calls": [
|
|
{
|
|
"duration_ms": 1200,
|
|
"scope": "agent_1"
|
|
}
|
|
],
|
|
"observations": [
|
|
{
|
|
"id": "obs-1",
|
|
"name": "AI Technology",
|
|
"subtype": "structural",
|
|
"type": "concept"
|
|
}
|
|
],
|
|
"tool_calls": [
|
|
{
|
|
"duration_ms": 150,
|
|
"input": {
|
|
"query": "AI"
|
|
},
|
|
"tool": "recall"
|
|
}
|
|
]
|
|
},
|
|
"usage": {
|
|
"input_tokens": 1500,
|
|
"output_tokens": 500,
|
|
"total_tokens": 2000
|
|
}
|
|
}
|
|
},
|
|
"ReflectToolCall": {
|
|
"properties": {
|
|
"tool": {
|
|
"type": "string",
|
|
"title": "Tool",
|
|
"description": "Tool name: lookup, recall, learn, expand"
|
|
},
|
|
"input": {
|
|
"additionalProperties": true,
|
|
"type": "object",
|
|
"title": "Input",
|
|
"description": "Tool input parameters"
|
|
},
|
|
"output": {
|
|
"anyOf": [
|
|
{
|
|
"additionalProperties": true,
|
|
"type": "object"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Output",
|
|
"description": "Tool output (only included when include.tool_calls.output is true)"
|
|
},
|
|
"duration_ms": {
|
|
"type": "integer",
|
|
"title": "Duration Ms",
|
|
"description": "Execution time in milliseconds"
|
|
},
|
|
"iteration": {
|
|
"type": "integer",
|
|
"title": "Iteration",
|
|
"description": "Iteration number (1-based) when this tool was called",
|
|
"default": 0
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"tool",
|
|
"input",
|
|
"duration_ms"
|
|
],
|
|
"title": "ReflectToolCall",
|
|
"description": "A tool call made during reflect agent execution."
|
|
},
|
|
"ReflectTrace": {
|
|
"properties": {
|
|
"tool_calls": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/ReflectToolCall"
|
|
},
|
|
"type": "array",
|
|
"title": "Tool Calls",
|
|
"description": "Tool calls made during reflection"
|
|
},
|
|
"llm_calls": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/ReflectLLMCall"
|
|
},
|
|
"type": "array",
|
|
"title": "Llm Calls",
|
|
"description": "LLM calls made during reflection"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"title": "ReflectTrace",
|
|
"description": "Execution trace of LLM and tool calls during reflection."
|
|
},
|
|
"RetainRequest": {
|
|
"properties": {
|
|
"items": {
|
|
"items": {
|
|
"$ref": "#/components/schemas/MemoryItem"
|
|
},
|
|
"type": "array",
|
|
"title": "Items"
|
|
},
|
|
"async": {
|
|
"type": "boolean",
|
|
"title": "Async",
|
|
"description": "If true, process asynchronously in background. If false, wait for completion (default: false)",
|
|
"default": false
|
|
},
|
|
"document_tags": {
|
|
"anyOf": [
|
|
{
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Document Tags",
|
|
"description": "Tags applied to all items in this request. These are merged with any item-level tags."
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"items"
|
|
],
|
|
"title": "RetainRequest",
|
|
"description": "Request model for retain endpoint.",
|
|
"example": {
|
|
"async": false,
|
|
"document_tags": [
|
|
"user_a",
|
|
"user_b"
|
|
],
|
|
"items": [
|
|
{
|
|
"content": "Alice works at Google",
|
|
"context": "work",
|
|
"document_id": "conversation_123"
|
|
},
|
|
{
|
|
"content": "Bob went hiking yesterday",
|
|
"document_id": "conversation_123",
|
|
"timestamp": "2024-01-15T10:00:00Z"
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"RetainResponse": {
|
|
"properties": {
|
|
"success": {
|
|
"type": "boolean",
|
|
"title": "Success"
|
|
},
|
|
"bank_id": {
|
|
"type": "string",
|
|
"title": "Bank Id"
|
|
},
|
|
"items_count": {
|
|
"type": "integer",
|
|
"title": "Items Count"
|
|
},
|
|
"async": {
|
|
"type": "boolean",
|
|
"title": "Async",
|
|
"description": "Whether the operation was processed asynchronously"
|
|
},
|
|
"operation_id": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Operation Id",
|
|
"description": "Operation ID for tracking async operations. Use GET /v1/default/banks/{bank_id}/operations to list operations and find this ID. Only present when async=true."
|
|
},
|
|
"usage": {
|
|
"anyOf": [
|
|
{
|
|
"$ref": "#/components/schemas/TokenUsage"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"description": "Token usage metrics for LLM calls during fact extraction (only present for synchronous operations)"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"success",
|
|
"bank_id",
|
|
"items_count",
|
|
"async"
|
|
],
|
|
"title": "RetainResponse",
|
|
"description": "Response model for retain endpoint.",
|
|
"example": {
|
|
"async": false,
|
|
"bank_id": "user123",
|
|
"items_count": 2,
|
|
"success": true,
|
|
"usage": {
|
|
"input_tokens": 500,
|
|
"output_tokens": 100,
|
|
"total_tokens": 600
|
|
}
|
|
}
|
|
},
|
|
"TagItem": {
|
|
"properties": {
|
|
"tag": {
|
|
"type": "string",
|
|
"title": "Tag",
|
|
"description": "The tag value"
|
|
},
|
|
"count": {
|
|
"type": "integer",
|
|
"title": "Count",
|
|
"description": "Number of memories with this tag"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"tag",
|
|
"count"
|
|
],
|
|
"title": "TagItem",
|
|
"description": "Single tag with usage count."
|
|
},
|
|
"TokenUsage": {
|
|
"properties": {
|
|
"input_tokens": {
|
|
"type": "integer",
|
|
"title": "Input Tokens",
|
|
"description": "Number of input/prompt tokens consumed",
|
|
"default": 0
|
|
},
|
|
"output_tokens": {
|
|
"type": "integer",
|
|
"title": "Output Tokens",
|
|
"description": "Number of output/completion tokens generated",
|
|
"default": 0
|
|
},
|
|
"total_tokens": {
|
|
"type": "integer",
|
|
"title": "Total Tokens",
|
|
"description": "Total tokens (input + output)",
|
|
"default": 0
|
|
}
|
|
},
|
|
"type": "object",
|
|
"title": "TokenUsage",
|
|
"description": "Token usage metrics for LLM calls.\n\nTracks input/output tokens for a single request to enable\nper-request cost tracking and monitoring.",
|
|
"example": {
|
|
"input_tokens": 1500,
|
|
"output_tokens": 500,
|
|
"total_tokens": 2000
|
|
}
|
|
},
|
|
"ToolCallsIncludeOptions": {
|
|
"properties": {
|
|
"output": {
|
|
"type": "boolean",
|
|
"title": "Output",
|
|
"description": "Include tool outputs in the trace. Set to false to only include inputs (smaller payload).",
|
|
"default": true
|
|
}
|
|
},
|
|
"type": "object",
|
|
"title": "ToolCallsIncludeOptions",
|
|
"description": "Options for including tool calls in reflect results."
|
|
},
|
|
"UpdateDirectiveRequest": {
|
|
"properties": {
|
|
"name": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Name",
|
|
"description": "New name"
|
|
},
|
|
"content": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Content",
|
|
"description": "New content"
|
|
},
|
|
"priority": {
|
|
"anyOf": [
|
|
{
|
|
"type": "integer"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Priority",
|
|
"description": "New priority"
|
|
},
|
|
"is_active": {
|
|
"anyOf": [
|
|
{
|
|
"type": "boolean"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Is Active",
|
|
"description": "New active status"
|
|
},
|
|
"tags": {
|
|
"anyOf": [
|
|
{
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Tags",
|
|
"description": "New tags"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"title": "UpdateDirectiveRequest",
|
|
"description": "Request model for updating a directive."
|
|
},
|
|
"UpdateDispositionRequest": {
|
|
"properties": {
|
|
"disposition": {
|
|
"$ref": "#/components/schemas/DispositionTraits"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"disposition"
|
|
],
|
|
"title": "UpdateDispositionRequest",
|
|
"description": "Request model for updating disposition traits."
|
|
},
|
|
"UpdateMentalModelRequest": {
|
|
"properties": {
|
|
"name": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Name",
|
|
"description": "New name for the mental model"
|
|
},
|
|
"source_query": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Source Query",
|
|
"description": "New source query for the mental model"
|
|
},
|
|
"max_tokens": {
|
|
"anyOf": [
|
|
{
|
|
"type": "integer",
|
|
"maximum": 8192.0,
|
|
"minimum": 256.0
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Max Tokens",
|
|
"description": "Maximum tokens for generated content"
|
|
},
|
|
"tags": {
|
|
"anyOf": [
|
|
{
|
|
"items": {
|
|
"type": "string"
|
|
},
|
|
"type": "array"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"title": "Tags",
|
|
"description": "Tags for scoped visibility"
|
|
},
|
|
"trigger": {
|
|
"anyOf": [
|
|
{
|
|
"$ref": "#/components/schemas/MentalModelTrigger"
|
|
},
|
|
{
|
|
"type": "null"
|
|
}
|
|
],
|
|
"description": "Trigger settings"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"title": "UpdateMentalModelRequest",
|
|
"description": "Request model for updating a mental model.",
|
|
"example": {
|
|
"max_tokens": 4096,
|
|
"name": "Updated Team Communication Preferences",
|
|
"source_query": "How does the team prefer to communicate?",
|
|
"tags": [
|
|
"team",
|
|
"communication"
|
|
],
|
|
"trigger": {
|
|
"refresh_after_consolidation": true
|
|
}
|
|
}
|
|
},
|
|
"ValidationError": {
|
|
"properties": {
|
|
"loc": {
|
|
"items": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "integer"
|
|
}
|
|
]
|
|
},
|
|
"type": "array",
|
|
"title": "Location"
|
|
},
|
|
"msg": {
|
|
"type": "string",
|
|
"title": "Message"
|
|
},
|
|
"type": {
|
|
"type": "string",
|
|
"title": "Error Type"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"loc",
|
|
"msg",
|
|
"type"
|
|
],
|
|
"title": "ValidationError"
|
|
},
|
|
"VersionResponse": {
|
|
"properties": {
|
|
"api_version": {
|
|
"type": "string",
|
|
"title": "Api Version",
|
|
"description": "API version string"
|
|
},
|
|
"features": {
|
|
"$ref": "#/components/schemas/FeaturesInfo",
|
|
"description": "Enabled feature flags"
|
|
}
|
|
},
|
|
"type": "object",
|
|
"required": [
|
|
"api_version",
|
|
"features"
|
|
],
|
|
"title": "VersionResponse",
|
|
"description": "Response model for the version/info endpoint.",
|
|
"example": {
|
|
"api_version": "0.4.0",
|
|
"features": {
|
|
"mcp": true,
|
|
"observations": false,
|
|
"worker": true
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
} |