{"openapi":"3.1.0","info":{"title":"OSF Knowledge Base API","description":"Order-Sorted Feature logic knowledge base with fuzzy reasoning, inference, and constraint solving. Note: Some endpoints are hidden from Swagger due to recursive type limitations but work via API calls.","contact":{"name":"OSF KB Team"},"license":{"name":"Proprietary","url":"https://github.com/osfkb/osfkb/blob/main/LICENSE"},"version":"1.0.0"},"paths":{"/api/v1/action-reviews/approve":{"post":{"tags":["action-reviews"],"summary":"Approve an action for execution","description":"POST /api/v1/action-reviews/approve\n\nApproves the action to be executed as-is.","operationId":"approve_action","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApproveActionRequest"}}},"required":true},"responses":{"200":{"description":"Action approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionReviewResponse"}}}},"404":{"description":"Review not found"},"409":{"description":"Review already decided"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/action-reviews/bulk-approve":{"post":{"tags":["action-reviews"],"summary":"Bulk approve multiple action reviews","description":"POST /api/v1/action-reviews/bulk-approve","operationId":"bulk_approve_actions","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkApproveActionsRequest"}}},"required":true},"responses":{"200":{"description":"Bulk approval result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkActionReviewResponse"}}}},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/action-reviews/bulk-reject":{"post":{"tags":["action-reviews"],"summary":"Bulk reject multiple action reviews","description":"POST /api/v1/action-reviews/bulk-reject","operationId":"bulk_reject_actions","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkRejectActionsRequest"}}},"required":true},"responses":{"200":{"description":"Bulk rejection result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkActionReviewResponse"}}}},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/action-reviews/modify":{"post":{"tags":["action-reviews"],"summary":"Modify and approve an action","description":"POST /api/v1/action-reviews/modify\n\nModifies the action parameters and approves for execution.","operationId":"modify_action","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModifyActionRequest"}}},"required":true},"responses":{"200":{"description":"Action modified and approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionReviewResponse"}}}},"404":{"description":"Review not found"},"409":{"description":"Review already decided"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/action-reviews/pending":{"get":{"tags":["action-reviews"],"summary":"List pending action reviews for a tenant","description":"GET /api/v1/action-reviews/pending\n\nReturns paginated list of actions requiring human review.","operationId":"list_pending_action_reviews","responses":{"200":{"description":"List pending action reviews","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListActionReviewsResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/action-reviews/reject":{"post":{"tags":["action-reviews"],"summary":"Reject an action","description":"POST /api/v1/action-reviews/reject\n\nRejects the action. It will not be executed.","operationId":"reject_action","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectActionRequest"}}},"required":true},"responses":{"200":{"description":"Action rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionReviewResponse"}}}},"404":{"description":"Review not found"},"409":{"description":"Review already decided"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/action-reviews/summary":{"get":{"tags":["action-reviews"],"summary":"Get action review summary statistics","description":"GET /api/v1/action-reviews/summary\n\nReturns summary statistics for pending action reviews.","operationId":"get_action_review_summary","parameters":[{"name":"tenant_id","in":"query","description":"Tenant ID to get summary for","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Review summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActionReviewSummaryDto"}}}},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/admin/clear-all":{"post":{"tags":["admin"],"summary":"Factory reset — wipe ALL data","description":"Destructive operation that wipes all PostgreSQL tables, Qdrant vector collections, Valkey cache, and in-memory tenant inference states. Equivalent to docker volume rm. Use only for development/testing.","operationId":"clear_all_data","responses":{"200":{"description":"Factory reset completed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FactoryResetResponse"}}}},"500":{"description":"Factory reset failed (partial wipe may have occurred)"}}}},"/api/v1/admin/clear-tenant/{tenant_id}":{"post":{"tags":["admin"],"summary":"Clear all data for a specific tenant","description":"Destructive operation that wipes all PostgreSQL rows, in-memory inference state, and cache entries for the specified tenant. Other tenants are unaffected. Use for tenant offboarding or testing.","operationId":"clear_tenant_data","parameters":[{"name":"tenant_id","in":"path","description":"The tenant UUID whose data should be cleared","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Tenant data cleared successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClearTenantResponse"}}}},"500":{"description":"Tenant data reset failed (partial wipe may have occurred)"}}}},"/api/v1/admin/neuro-symbolic/diagnostics":{"get":{"tags":["neuro-symbolic"],"summary":"GET /api/v1/admin/neuro-symbolic/diagnostics","description":"Returns per-choice-type success rates, weakest choice points, and trace buffer\nstatistics from the shared TraceCollector. Identifies which decision points\nthe scorer is worst at -- the primary diagnostic for targeted improvement.","operationId":"neuro_symbolic_diagnostics","responses":{"200":{"description":"Diagnostics snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiagnosticsResponse"}}}}}}},"/api/v1/admin/neuro-symbolic/embeddings/sort-box":{"post":{"tags":["neuro-symbolic"],"summary":"POST /api/v1/admin/neuro-symbolic/embeddings/sort-box","description":"Looks up a single sort's box embedding by name.\nReturns the min/max coordinates, log-volume, and dimensionality.","operationId":"neuro_symbolic_sort_box","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SortBoxRequest"}}},"required":true},"responses":{"200":{"description":"Sort box embedding lookup result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SortBoxResponse"}}}},"404":{"description":"Neuro-symbolic subsystem not enabled"}}}},"/api/v1/admin/neuro-symbolic/embeddings/verify":{"get":{"tags":["neuro-symbolic"],"summary":"GET /api/v1/admin/neuro-symbolic/embeddings/verify","description":"Verifies that trained box embeddings faithfully represent the sort hierarchy.\nRuns three verification checks:\n- Containment: subtype boxes are contained in supertype boxes\n- Meet-preservation: box intersection approximates GLB embedding\n- Volume-specificity: more specific sorts have smaller volumes","operationId":"neuro_symbolic_verify_embeddings","responses":{"200":{"description":"Embedding verification results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbeddingVerificationResponse"}}}},"404":{"description":"Neuro-symbolic subsystem not enabled"},"500":{"description":"Verification task panicked"}}}},"/api/v1/admin/neuro-symbolic/save-weights":{"post":{"tags":["neuro-symbolic"],"summary":"POST /api/v1/admin/neuro-symbolic/save-weights","description":"Persists all trained weights (scorer, embeddings, GFlowNet) to disk.\nThis is a blocking operation -- the response is returned after saving completes.","operationId":"neuro_symbolic_save_weights","responses":{"200":{"description":"Weights saved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SaveWeightsResponse"}}}},"404":{"description":"Neuro-symbolic subsystem not enabled"},"500":{"description":"Save task panicked"}}}},"/api/v1/admin/neuro-symbolic/status":{"get":{"tags":["neuro-symbolic"],"summary":"GET /api/v1/admin/neuro-symbolic/status","description":"Returns the current status of the neuro-symbolic training subsystem,\nincluding scorer metrics, embedding metrics, and background loop state.","operationId":"neuro_symbolic_status","responses":{"200":{"description":"Neuro-symbolic subsystem status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NeuroSymbolicStatusResponse"}}}}}}},"/api/v1/admin/neuro-symbolic/train":{"post":{"tags":["neuro-symbolic"],"summary":"POST /api/v1/admin/neuro-symbolic/train","description":"Triggers synthetic training using the training harness.\nGenerates synthetic knowledge bases and trains on derivation traces.\nThis is a blocking operation -- the response is returned after training completes.","operationId":"neuro_symbolic_train","responses":{"200":{"description":"Training completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrainingTriggerResponse"}}}},"404":{"description":"Neuro-symbolic subsystem not enabled"},"500":{"description":"Training task panicked"}}}},"/api/v1/admin/neuro-symbolic/train/e2e":{"post":{"tags":["neuro-symbolic"],"summary":"POST /api/v1/admin/neuro-symbolic/train/e2e","description":"Triggers end-to-end differentiable training using tagged forward chaining\nwith a probabilistic semiring. Runs the specified number of epochs,\ncomputing BCE loss against ground truth at each epoch.\n\nThis is a blocking operation -- the response is returned after all epochs complete.","operationId":"neuro_symbolic_train_e2e","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/E2eTrainingRequest"}}},"required":true},"responses":{"200":{"description":"E2E training completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/E2eTrainingResponse"}}}},"500":{"description":"Training task panicked"}},"security":[{"tenant_id":[]}]}},"/api/v1/admin/neuro-symbolic/train/embeddings":{"post":{"tags":["neuro-symbolic"],"summary":"POST /api/v1/admin/neuro-symbolic/train/embeddings","description":"Triggers box embedding refinement using containment loss from the sort hierarchy.\nThis is a blocking operation -- the response is returned after training completes.","operationId":"neuro_symbolic_train_embeddings","responses":{"200":{"description":"Embedding training completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrainingTriggerResponse"}}}},"404":{"description":"Neuro-symbolic subsystem not enabled"},"500":{"description":"Training task panicked"}}}},"/api/v1/admin/neuro-symbolic/train/from-traces":{"post":{"tags":["neuro-symbolic"],"summary":"POST /api/v1/admin/neuro-symbolic/train/from-traces","description":"Trains the neural scorer from accumulated search traces.\nDrains the trace buffer collected during guided searches and runs\na training cycle. This is the feedback loop for AlphaProof-style learning:\nsearch -> collect traces -> train -> improved search.","operationId":"neuro_symbolic_train_from_traces","responses":{"200":{"description":"Trace-based training completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrainFromTracesResponse"}}}},"404":{"description":"Neuro-symbolic subsystem not enabled"},"500":{"description":"Training task panicked"}}}},"/api/v1/admin/neuro-symbolic/train/gflownet":{"post":{"tags":["neuro-symbolic"],"summary":"POST /api/v1/admin/neuro-symbolic/train/gflownet","description":"Triggers GFlowNet trajectory-balance training from accumulated trajectories.\nDrains the trajectory buffer and runs one TB training step.\nThis is a blocking operation -- the response is returned after training completes.","operationId":"neuro_symbolic_train_gflownet","responses":{"200":{"description":"GFlowNet training completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GFlowNetTrainResponse"}}}},"404":{"description":"Neuro-symbolic subsystem not enabled"},"500":{"description":"Training task panicked"}}}},"/api/v1/admin/snapshots":{"get":{"tags":["snapshots"],"summary":"List all snapshots (global)","description":"Returns all snapshots across all tenants, ordered by creation time (newest first). Does not return the data payload. Admin endpoint.","operationId":"list_snapshots","responses":{"200":{"description":"Snapshots listed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListSnapshotsResponse"}}}},"501":{"description":"Snapshots require PostgreSQL (running in in-memory mode)"}}}},"/api/v1/admin/snapshots/create/{tenant_id}":{"post":{"tags":["snapshots"],"summary":"Create a tenant data snapshot","description":"Captures a point-in-time snapshot of all tenant-scoped PostgreSQL data. Returns snapshot metadata including per-table row counts and size.","operationId":"create_snapshot","parameters":[{"name":"tenant_id","in":"path","description":"The tenant UUID to snapshot","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSnapshotRequest"}}},"required":true},"responses":{"201":{"description":"Snapshot created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SnapshotResponse"}}}},"500":{"description":"Snapshot creation failed"},"501":{"description":"Snapshots require PostgreSQL (running in in-memory mode)"}}}},"/api/v1/admin/snapshots/import":{"post":{"tags":["snapshots"],"summary":"Import a snapshot from an exported envelope","description":"Accepts an osfkb-snapshot JSON envelope, validates the structure, and stores it as a new snapshot. Use ?name=override to rename.","operationId":"import_snapshot","parameters":[{"name":"name","in":"query","description":"Optional name override for the imported snapshot","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{}}},"required":true},"responses":{"201":{"description":"Snapshot imported successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SnapshotResponse"}}}},"400":{"description":"Invalid snapshot format or validation errors"},"422":{"description":"Snapshot data validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SnapshotValidationErrorResponse"}}}},"501":{"description":"Snapshots require PostgreSQL (running in in-memory mode)"}}}},"/api/v1/admin/snapshots/{snapshot_id}":{"get":{"tags":["snapshots"],"summary":"Get a snapshot by ID","description":"Returns metadata for a single snapshot. Returns 404 if not found. Global admin endpoint.","operationId":"get_snapshot","parameters":[{"name":"snapshot_id","in":"path","description":"The snapshot UUID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Snapshot found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SnapshotResponse"}}}},"404":{"description":"Snapshot not found"},"501":{"description":"Snapshots require PostgreSQL (running in in-memory mode)"}}},"delete":{"tags":["snapshots"],"summary":"Delete a snapshot","description":"Deletes a snapshot. Returns 404 if not found. Global admin endpoint.","operationId":"delete_snapshot","parameters":[{"name":"snapshot_id","in":"path","description":"The snapshot UUID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Snapshot deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteSnapshotResponse"}}}},"404":{"description":"Snapshot not found"},"501":{"description":"Snapshots require PostgreSQL (running in in-memory mode)"}}}},"/api/v1/admin/snapshots/{snapshot_id}/apply/{target_tenant_id}":{"post":{"tags":["snapshots"],"summary":"Apply (restore) a snapshot to a target tenant","description":"Destructive operation: clears all target tenant data, restores from snapshot (rewriting tenant_id), and rebuilds in-memory state. The snapshot can be from any tenant.","operationId":"apply_snapshot","parameters":[{"name":"snapshot_id","in":"path","description":"The snapshot UUID to restore","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"target_tenant_id","in":"path","description":"The target tenant UUID to restore into","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Snapshot applied successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplySnapshotResponse"}}}},"404":{"description":"Snapshot not found"},"500":{"description":"Snapshot restore failed (partial state may exist)"},"501":{"description":"Snapshots require PostgreSQL (running in in-memory mode)"}}}},"/api/v1/admin/snapshots/{snapshot_id}/export":{"get":{"tags":["snapshots"],"summary":"Export a snapshot as a downloadable JSON file","description":"Returns the full snapshot wrapped in an osfkb-snapshot envelope for offline storage or import into another instance.","operationId":"export_snapshot","parameters":[{"name":"snapshot_id","in":"path","description":"The snapshot UUID to export","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Snapshot exported","content":{"application/json":{}}},"404":{"description":"Snapshot not found"},"501":{"description":"Snapshots require PostgreSQL (running in in-memory mode)"}}}},"/api/v1/admin/tenants":{"get":{"tags":["admin"],"summary":"List all tenants with data","description":"Returns all tenant IDs that have terms or ingestion sessions, with counts. No X-Tenant-Id header required. Works in both PostgreSQL and in-memory modes.","operationId":"list_tenants","responses":{"200":{"description":"Tenant list retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListTenantsResponse"}}}}}}},"/api/v1/analysis/attribute-exploration/start":{"post":{"tags":["analysis"],"summary":"Start a new attribute exploration session.","description":"Builds a formal context from the tenant's knowledge base terms and\ninitializes the Ganter exploration protocol.","operationId":"start_exploration","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartExplorationRequestDto"}}},"required":true},"responses":{"200":{"description":"Exploration session started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartExplorationResponseDto"}}}},"400":{"description":"Invalid request parameters"},"500":{"description":"Internal server error"}}}},"/api/v1/analysis/attribute-exploration/{session_id}/complete":{"post":{"tags":["analysis"],"summary":"Complete the exploration and create sort rules from confirmed implications.","description":"The exploration must be complete (no more questions) before calling this.\nCreates appropriateness sorts in the hierarchy from the Duquenne-Guigues basis.","operationId":"complete_exploration","parameters":[{"name":"session_id","in":"path","description":"Exploration session UUID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Exploration completed and rules created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExplorationCompleteResponseDto"}}}},"400":{"description":"Exploration not yet complete"},"404":{"description":"Session not found"}}}},"/api/v1/analysis/attribute-exploration/{session_id}/confirm":{"post":{"tags":["analysis"],"summary":"Confirm the current implication: the expert agrees it holds.","operationId":"confirm_implication","parameters":[{"name":"session_id","in":"path","description":"Exploration session UUID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Implication confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfirmResponseDto"}}}},"400":{"description":"Invalid operation"},"404":{"description":"Session not found"}}}},"/api/v1/analysis/attribute-exploration/{session_id}/refute":{"post":{"tags":["analysis"],"summary":"Refute the current implication with a counterexample.","description":"The counterexample must have all premise features but lack at least\none conclusion feature.","operationId":"refute_implication","parameters":[{"name":"session_id","in":"path","description":"Exploration session UUID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefuteRequestDto"}}},"required":true},"responses":{"200":{"description":"Implication refuted with counterexample","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefuteResponseDto"}}}},"400":{"description":"Invalid counterexample"},"404":{"description":"Session not found"}}}},"/api/v1/analysis/attribute-exploration/{session_id}/status":{"get":{"tags":["analysis"],"summary":"Get the current status of an exploration session.","operationId":"exploration_status","parameters":[{"name":"session_id","in":"path","description":"Exploration session UUID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Session status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExplorationStatusResponseDto"}}}},"404":{"description":"Session not found"}}}},"/api/v1/analysis/sort-discovery":{"post":{"tags":["analysis"],"summary":"Analyze the knowledge base for missing sort boundaries via FCA.","description":"Runs Ganter's Next Closure algorithm on existing PsiTerms to discover\nformal concepts (feature-set intersections) not captured by existing sorts.\nReturns ranked recommendations with confidence scores and optional auto-creation.\nWhen `fuzzy_thresholds` is non-empty, also runs fuzzy FCA at each alpha-cut level.","operationId":"analyze_sort_discovery","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SortDiscoveryRequestDto"}}},"required":true},"responses":{"200":{"description":"Sort discovery analysis completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SortDiscoveryResponseDto"}}}},"400":{"description":"Invalid request parameters"},"500":{"description":"Internal server error"}}}},"/api/v1/arithmetic/add":{"post":{"tags":["arithmetic"],"summary":"3-way addition: A + B = C\nPOST /api/v1/arithmetic/add","operationId":"arith_add","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelationalArithRequest"}}},"required":true},"responses":{"200":{"description":"3-way addition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelationalArithResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/arithmetic/bitwise":{"post":{"tags":["arithmetic"],"summary":"Execute a bitwise operation\nPOST /api/v1/arithmetic/bitwise","operationId":"bitwise_op","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BitwiseRequest"}}},"required":true},"responses":{"200":{"description":"Execute bitwise operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BitwiseResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/arithmetic/div":{"post":{"tags":["arithmetic"],"summary":"3-way division: A / B = C\nPOST /api/v1/arithmetic/div","operationId":"arith_div","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelationalArithRequest"}}},"required":true},"responses":{"200":{"description":"3-way division","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelationalArithResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/arithmetic/math":{"post":{"tags":["arithmetic"],"summary":"Execute a math function\nPOST /api/v1/arithmetic/math","operationId":"math_function","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MathFunctionRequest"}}},"required":true},"responses":{"200":{"description":"Execute a math function","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MathFunctionResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/arithmetic/modular":{"post":{"tags":["arithmetic"],"summary":"Execute modular arithmetic\nPOST /api/v1/arithmetic/modular","operationId":"modular_arith","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModularArithRequest"}}},"required":true},"responses":{"200":{"description":"Execute modular arithmetic","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModularArithResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/arithmetic/mult":{"post":{"tags":["arithmetic"],"summary":"3-way multiplication: A * B = C\nPOST /api/v1/arithmetic/mult","operationId":"arith_mult","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelationalArithRequest"}}},"required":true},"responses":{"200":{"description":"3-way multiplication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelationalArithResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/arithmetic/sub":{"post":{"tags":["arithmetic"],"summary":"3-way subtraction: A - B = C\nPOST /api/v1/arithmetic/sub","operationId":"arith_sub","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelationalArithRequest"}}},"required":true},"responses":{"200":{"description":"3-way subtraction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelationalArithResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/audit/entries":{"get":{"tags":["audit"],"summary":"GET /api/v1/audit/entries","description":"List audit entries with pagination and filters.","operationId":"list_entries","parameters":[{"name":"event_type","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"conversation_id","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"start_date","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"end_date","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"page","in":"query","required":false,"schema":{"type":["integer","null"],"minimum":0}},{"name":"page_size","in":"query","required":false,"schema":{"type":["integer","null"],"minimum":0}}],"responses":{"200":{"description":"Paginated audit entries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListAuditEntriesResponse"}}}}},"security":[{"tenant_id":[]}]},"post":{"tags":["audit"],"summary":"POST /api/v1/audit/entries","description":"Append an audit entry.","operationId":"append_entry","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppendAuditEntryRequest"}}},"required":true},"responses":{"201":{"description":"Audit entry appended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditEntryDto"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/audit/entries/count":{"get":{"tags":["audit"],"summary":"GET /api/v1/audit/entries/count","description":"Count matching audit entries.","operationId":"count_entries","parameters":[{"name":"event_type","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"conversation_id","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"start_date","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"end_date","in":"query","required":false,"schema":{"type":["string","null"]}},{"name":"page","in":"query","required":false,"schema":{"type":["integer","null"],"minimum":0}},{"name":"page_size","in":"query","required":false,"schema":{"type":["integer","null"],"minimum":0}}],"responses":{"200":{"description":"Count of matching entries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CountAuditEntriesResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/audit/entries/{conversation_id}":{"get":{"tags":["audit"],"summary":"GET /api/v1/audit/entries/{conversation_id}","description":"Get audit entries for a specific conversation.","operationId":"get_conversation_entries","parameters":[{"name":"conversation_id","in":"path","description":"Conversation ID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Conversation audit entries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListAuditEntriesResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/audit/verify-integrity":{"post":{"tags":["audit"],"summary":"POST /api/v1/audit/verify-integrity","operationId":"verify_integrity","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyIntegrityRequest"}}},"required":true},"responses":{"200":{"description":"Integrity verification result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrityResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/causal/ancestor":{"post":{"tags":["causal"],"summary":"Check if one variable is a causal ancestor of another","description":"Uses transitive closure over the causal graph to find ancestry.","operationId":"check_causal_ancestor","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CausalAncestorRequest"}}},"required":true},"responses":{"200":{"description":"Ancestry check result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CausalAncestorResponse"}}}},"400":{"description":"Bad request"}},"security":[{"tenant_id":[]}]}},"/api/v1/causal/causes":{"post":{"tags":["causal"],"summary":"Check if one variable directly causes another","description":"Uses the CausalInferenceBuiltins to check direct causal relationships.","operationId":"check_causes","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CausesRequest"}}},"required":true},"responses":{"200":{"description":"Causation check result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CausesResponse"}}}},"400":{"description":"Bad request"}},"security":[{"tenant_id":[]}]}},"/api/v1/causal/counterfactual":{"post":{"tags":["causal"],"summary":"Evaluate a counterfactual query using Pearl's three-step algorithm","description":"Steps:\n1. Abduction: Compute exogenous variables from factual evidence\n2. Action: Apply intervention do(X=x)\n3. Prediction: Query in the modified world","operationId":"evaluate_counterfactual","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CounterfactualRequest"}}},"required":true},"responses":{"200":{"description":"Counterfactual result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CounterfactualResponse"}}}},"400":{"description":"Bad request"}},"security":[{"tenant_id":[]}]}},"/api/v1/causal/d-separated":{"post":{"tags":["causal"],"summary":"Check d-separation between two variables given a conditioning set","description":"Uses Bayes-Ball algorithm to determine conditional independence.","operationId":"check_d_separated","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DSeparatedRequest"}}},"required":true},"responses":{"200":{"description":"D-separation check result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DSeparatedResponse"}}}},"400":{"description":"Bad request"}},"security":[{"tenant_id":[]}]}},"/api/v1/causal/intervention":{"post":{"tags":["causal"],"summary":"Apply a do-calculus intervention and query the result","description":"Implements Pearl's do(X=x) operator by disabling incoming edges to X.","operationId":"apply_intervention","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InterventionRequest"}}},"required":true},"responses":{"200":{"description":"Intervention result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InterventionResponse"}}}},"400":{"description":"Bad request"}},"security":[{"tenant_id":[]}]}},"/api/v1/causal/model":{"get":{"tags":["causal"],"summary":"Get the full causal model for the tenant","operationId":"get_causal_model","responses":{"200":{"description":"Causal model","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetCausalModelResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/causal/relations":{"post":{"tags":["causal"],"summary":"Add a causal relationship to the model","operationId":"add_causal_relation","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddCausalRelationRequest"}}},"required":true},"responses":{"201":{"description":"Causal relation added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddCausalRelationResponse"}}}},"400":{"description":"Bad request"}},"security":[{"tenant_id":[]}]}},"/api/v1/causal/root-cause":{"post":{"tags":["causal"],"summary":"Perform root cause analysis for an effect","operationId":"analyze_root_causes","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RootCauseAnalysisRequest"}}},"required":true},"responses":{"200":{"description":"Root cause analysis result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RootCauseAnalysisResponse"}}}},"400":{"description":"Bad request"}},"security":[{"tenant_id":[]}]}},"/api/v1/causal/root-cause-with-proof":{"post":{"tags":["causal"],"summary":"Perform root cause analysis with full proof tree for audit trail","operationId":"analyze_root_causes_with_proof","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RootCauseAnalysisRequest"}}},"required":true},"responses":{"200":{"description":"Root cause analysis with proof tree","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RootCauseWithProofResponse"}}}},"400":{"description":"Bad request"}},"security":[{"tenant_id":[]}]}},"/api/v1/causal/validate-did":{"post":{"tags":["causal"],"summary":"Validate a Difference-in-Differences (DiD) design","description":"This endpoint validates whether a DiD design is theoretically sound\ngiven the known causal structure and unobserved confounding.\nIt uses the Transformed SWIG (Delta-SWIG) framework from Knaus & Pfleiderer (2026).","operationId":"validate_did","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiDValidationRequest"}}},"required":true},"responses":{"200":{"description":"Validation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiDValidationResponse"}}}},"400":{"description":"Bad request"}},"security":[{"tenant_id":[]}]}},"/api/v1/cdl/classify-safety":{"post":{"tags":["cdl"],"summary":"Classify text for safety violations using the CDL fact grounding layer (Phase 5).\nEncodes text to embedding, then runs through CDL sort-hierarchy-constrained classifier.","operationId":"classify_safety","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassifySafetyRequest"}}},"required":true},"responses":{"200":{"description":"Safety classification result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClassifySafetyResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/cdl/derived-inference":{"post":{"tags":["cdl"],"summary":"Run the composed CDL derived layer (Phase 4): unification matcher → residuation gate → sort classifier.\nTakes pairs of feature vectors and produces match scores, gate decisions, and sort predictions.","operationId":"derived_inference","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DerivedInferenceRequest"}}},"required":true},"responses":{"200":{"description":"Derived inference result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DerivedInferenceResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/cdl/dynamic/add-sort":{"post":{"tags":["cdl"],"summary":"Dynamically add a sort to the CDL architecture (Phase 6).\nNew sort weights are initialized from parent sort weights (functorial inheritance).\nExisting predictions are preserved within tolerance.","operationId":"dynamic_add_sort","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DynamicAddSortRequest"}}},"required":true},"responses":{"200":{"description":"Sort added to CDL architecture","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DynamicAddSortResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/cdl/forward-chain/differentiable":{"post":{"tags":["cdl"],"summary":"Run differentiable forward chaining (Phase 2) on the tenant's knowledge base.\nPerforms symbolic FC for soundness, then annotates facts with continuous weights\nbased on rule attention and soft unification scores.","operationId":"differentiable_forward_chain","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DifferentiableFcRequest"}}},"required":true},"responses":{"200":{"description":"Differentiable FC result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DifferentiableFcResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/cdl/forward-chain/tagged":{"post":{"tags":["cdl"],"summary":"Run provenance-annotated forward chaining (Phase 1) with probabilistic semiring.\nEach derived fact carries a probability tag propagated via noisy-OR / product.","operationId":"tagged_forward_chain","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaggedFcRequest"}}},"required":true},"responses":{"200":{"description":"Tagged FC result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaggedFcResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/cdl/monadic-fixpoint":{"post":{"tags":["cdl"],"summary":"Run monadic inference to fixpoint (Phase 3).\nRepeatedly applies the OSF endofunctor T and monad multiplication μ\nuntil no new facts are derived: fixpoint(X) = μ(T(μ(T(... μ(T(η(X)))...))))","operationId":"monadic_fixpoint_handler","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonadicFixpointRequest"}}},"required":true},"responses":{"200":{"description":"Monadic fixpoint result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonadicFixpointResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/cdl/soft-unify":{"post":{"tags":["cdl"],"summary":"Perform soft (differentiable) unification between two terms (Phase 2).\nReturns a continuous confidence score ∈ [0,1] alongside the hard boolean result.","operationId":"soft_unify_terms","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SoftUnifyRequest"}}},"required":true},"responses":{"200":{"description":"Soft unification result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SoftUnifyResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/cdl/status":{"get":{"tags":["cdl"],"summary":"Returns the status of all CDL subsystem components.","operationId":"cdl_status","responses":{"200":{"description":"CDL subsystem status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CdlStatusResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/cognitive/agents":{"post":{"tags":["cognitive"],"summary":"Create a new cognitive agent.","description":"## Example\n\n```bash\ncurl -X POST http://localhost:3000/api/v1/cognitive/agents \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\": \"reasoning_agent\", \"tenant_id\": \"...\"}'\n```","operationId":"create_agent","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentRequest"}}},"required":true},"responses":{"201":{"description":"Agent created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAgentResponse"}}}},"400":{"description":"Invalid request"},"500":{"description":"Internal error"}}}},"/api/v1/cognitive/agents/adapt":{"post":{"tags":["cognitive"],"summary":"Adaptive modification: agent modifies rules during inference.","description":"This demonstrates TRUE HOMOICONICITY - rules can be\nasserted/retracted during inference, not just at API boundaries.","operationId":"adaptive_modify","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdaptiveModifyRequest"}}},"required":true},"responses":{"200":{"description":"Modification result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdaptiveModifyResponse"}}}},"400":{"description":"Invalid action"},"404":{"description":"Agent not found"},"500":{"description":"Internal error"}}}},"/api/v1/cognitive/agents/beliefs":{"post":{"tags":["cognitive"],"summary":"Add a belief to an agent.","operationId":"add_belief","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddBeliefRequest"}}},"required":true},"responses":{"200":{"description":"Belief added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddBeliefResponse"}}}},"404":{"description":"Agent not found"},"500":{"description":"Internal error"}}}},"/api/v1/cognitive/agents/cycle":{"post":{"tags":["cognitive"],"summary":"Run one cycle of the agent's cognitive loop.","description":"Executes: perceive → reason → act → learn","operationId":"run_cycle","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunCycleRequest"}}},"required":true},"responses":{"200":{"description":"Cycle completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunCycleResponse"}}}},"404":{"description":"Agent not found"},"500":{"description":"Internal error"}}}},"/api/v1/cognitive/agents/episodes":{"post":{"tags":["Cognitive Agents - Episodic Memory"],"summary":"Record an episode in memory.","operationId":"record_episode","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordEpisodeRequest"}}},"required":true},"responses":{"200":{"description":"Episode recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordEpisodeResponse"}}}},"404":{"description":"Tenant not found"}}}},"/api/v1/cognitive/agents/episodes/recall":{"post":{"tags":["Cognitive Agents - Episodic Memory"],"summary":"Recall similar episodes from memory.","operationId":"recall_episodes","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecallEpisodesRequest"}}},"required":true},"responses":{"200":{"description":"Episodes recalled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecallEpisodesResponse"}}}},"404":{"description":"Tenant not found"}}}},"/api/v1/cognitive/agents/episodes/stats":{"post":{"tags":["Cognitive Agents - Episodic Memory"],"summary":"Get episode statistics.","operationId":"get_episode_stats","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetEpisodeStatsRequest"}}},"required":true},"responses":{"200":{"description":"Statistics retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EpisodeStatsResponse"}}}},"404":{"description":"Tenant not found"}}}},"/api/v1/cognitive/agents/goals":{"post":{"tags":["cognitive"],"summary":"Add a goal to an agent.","description":"The goal is stored as a Ψ-term with the agent_id feature set, allowing\nthe CognitiveAgentEngine to query goals for a specific agent.","operationId":"add_goal","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddGoalRequest"}}},"required":true},"responses":{"200":{"description":"Goal added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddGoalResponse"}}}},"404":{"description":"Agent not found"},"500":{"description":"Internal error"}}}},"/api/v1/cognitive/agents/htn/decompose":{"post":{"tags":["Cognitive Agents - HTN"],"summary":"Decompose a goal using HTN planning.","description":"Recursively decomposes a goal into executable primitive actions.","operationId":"decompose_goal","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecomposeGoalRequest"}}},"required":true},"responses":{"200":{"description":"Goal decomposed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecomposeGoalResponse"}}}},"404":{"description":"Tenant not found"}}}},"/api/v1/cognitive/agents/htn/methods":{"post":{"tags":["Cognitive Agents - HTN"],"summary":"Add an HTN decomposition method.","description":"Registers a method that decomposes a task into subtasks.","operationId":"add_htn_method","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddHtnMethodRequest"}}},"required":true},"responses":{"200":{"description":"Method added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddHtnMethodResponse"}}}},"404":{"description":"Tenant not found"}}}},"/api/v1/cognitive/agents/htn/methods/list":{"post":{"tags":["Cognitive Agents - HTN"],"summary":"Get HTN methods, optionally filtered by task sort.","operationId":"get_htn_methods","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetHtnMethodsRequest"}}},"required":true},"responses":{"200":{"description":"Methods retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetHtnMethodsResponse"}}}},"404":{"description":"Tenant not found"}}}},"/api/v1/cognitive/agents/integrated-cycle":{"post":{"tags":["cognitive"],"summary":"Run an integrated cognitive cycle.","description":"This executes the full cognitive cycle using all 9 modules:\nPERCEIVE → ACTIVATE → DELIBERATE → PREDICT → SIMULATE → EXECUTE → IMPASSE → LEARN → DECAY\n\n## Example\n\n```bash\ncurl -X POST http://localhost:3000/api/v1/cognitive/agents/integrated-cycle \\\n -H \"Content-Type: application/json\" \\\n -d '{\"agent_id\": \"...\", \"tenant_id\": \"...\"}'\n```","operationId":"run_integrated_cycle","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunIntegratedCycleRequest"}}},"required":true},"responses":{"200":{"description":"Integrated cycle completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunIntegratedCycleResponse"}}}},"404":{"description":"Agent not found"},"500":{"description":"Internal error"}}}},"/api/v1/cognitive/agents/messages":{"post":{"tags":["Cognitive Agents - Messaging"],"summary":"Send a message to another agent.","operationId":"send_message","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageRequest"}}},"required":true},"responses":{"200":{"description":"Message sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageResponse"}}}},"404":{"description":"Tenant not found"}}}},"/api/v1/cognitive/agents/messages/broadcast":{"post":{"tags":["Cognitive Agents - Messaging"],"summary":"Broadcast a message to all agents.","operationId":"broadcast_message","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BroadcastMessageRequest"}}},"required":true},"responses":{"200":{"description":"Message broadcast","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BroadcastMessageResponse"}}}},"404":{"description":"Tenant not found"}}}},"/api/v1/cognitive/agents/messages/inbox":{"post":{"tags":["Cognitive Agents - Messaging"],"summary":"Get an agent's inbox.","operationId":"get_inbox","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetInboxRequest"}}},"required":true},"responses":{"200":{"description":"Inbox retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetInboxResponse"}}}},"404":{"description":"Tenant not found"}}}},"/api/v1/cognitive/agents/messages/read":{"post":{"tags":["Cognitive Agents - Messaging"],"summary":"Mark messages as read.","operationId":"mark_messages_read","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkMessagesReadRequest"}}},"required":true},"responses":{"200":{"description":"Messages marked as read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkMessagesReadResponse"}}}},"404":{"description":"Tenant not found"}}}},"/api/v1/cognitive/agents/plans":{"post":{"tags":["Cognitive Agents - Plan Library"],"summary":"Store a plan in the library.","description":"Stores a successful action sequence as a reusable plan template.","operationId":"store_plan","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorePlanRequest"}}},"required":true},"responses":{"200":{"description":"Plan stored successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StorePlanResponse"}}}},"404":{"description":"Tenant or agent not found"}}}},"/api/v1/cognitive/agents/plans/find":{"post":{"tags":["Cognitive Agents - Plan Library"],"summary":"Find matching plans for a goal.","description":"Searches the plan library for plans that match the given goal.","operationId":"find_plans","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindPlansRequest"}}},"required":true},"responses":{"200":{"description":"Plans found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindPlansResponse"}}}},"404":{"description":"Tenant or agent not found"}}}},"/api/v1/cognitive/agents/plans/stats":{"post":{"tags":["Cognitive Agents - Plan Library"],"summary":"Update plan statistics after execution.","operationId":"update_plan_stats","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePlanStatsRequest"}}},"required":true},"responses":{"200":{"description":"Stats updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePlanStatsResponse"}}}},"404":{"description":"Tenant or plan not found"}}}},"/api/v1/cognitive/agents/plans/{plan_id}":{"delete":{"tags":["Cognitive Agents - Plan Library"],"summary":"Delete a plan from the library.\nTenant is identified by the `X-Tenant-Id` header.","operationId":"delete_plan","parameters":[{"name":"plan_id","in":"path","description":"Plan ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Plan deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletePlanResponse"}}}},"404":{"description":"Tenant not found"}},"security":[{"tenant_auth":[]}]}},"/api/v1/cognitive/agents/reflect":{"post":{"tags":["cognitive"],"summary":"Reflection query: agent queries its own rules.","description":"This demonstrates TRUE HOMOICONICITY - the agent can\nreason about its own inference rules using the same\nunification-based query mechanism.","operationId":"reflection_query","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReflectionQueryRequest"}}},"required":true},"responses":{"200":{"description":"Reflection results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReflectionQueryResponse"}}}},"404":{"description":"Agent not found"},"500":{"description":"Internal error"}}}},"/api/v1/cognitive/agents/rules":{"post":{"tags":["cognitive"],"summary":"Add a rule to the cognitive agent's ruleset.","description":"This allows adding rules that the cognitive agent can use during its cycle.\nRules are stored in the agent registry's ruleset (separate from the inference API).","operationId":"add_cognitive_rule","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddCognitiveRuleRequest"}}},"required":true},"responses":{"200":{"description":"Rule added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddCognitiveRuleResponse"}}}},"404":{"description":"Tenant not found"},"500":{"description":"Internal error"}}}},"/api/v1/cognitive/agents/sorts":{"post":{"tags":["cognitive"],"summary":"Create a sort in the cognitive agent registry.","description":"This is necessary because cognitive agents use their own sort hierarchy\nseparate from the inference system. Sorts must exist before rules can use them.","operationId":"create_cognitive_sort","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCognitiveSortRequest"}}},"required":true},"responses":{"201":{"description":"Sort created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCognitiveSortResponse"}}}},"404":{"description":"Tenant not found"},"500":{"description":"Internal error"}}}},"/api/v1/cognitive/agents/state":{"post":{"tags":["cognitive"],"summary":"Get agent state (goals, beliefs).","operationId":"get_agent_state","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetAgentStateRequest"}}},"required":true},"responses":{"200":{"description":"Agent state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetAgentStateResponse"}}}},"404":{"description":"Agent not found"},"500":{"description":"Internal error"}}}},"/api/v1/cognitive/agents/subscribe":{"post":{"tags":["cognitive"],"summary":"Subscribe an agent to KB changes.","description":"When subscribed, the agent will receive notifications about changes\nto the specified sorts and features, enabling reactive behavior.\n\n## Example\n\n```bash\ncurl -X POST http://localhost:3000/api/v1/cognitive/agents/subscribe \\\n -H \"Content-Type: application/json\" \\\n -d '{\"agent_id\": \"...\", \"tenant_id\": \"...\", \"watched_sorts\": [\"person\", \"event\"]}'\n```","operationId":"subscribe_to_kb","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscribeToKbRequest"}}},"required":true},"responses":{"200":{"description":"Subscription created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscribeToKbResponse"}}}},"404":{"description":"Agent not found"},"500":{"description":"Internal error"}}}},"/api/v1/cognitive/agents/{agent_id}":{"get":{"tags":["cognitive"],"summary":"Get a single agent by ID.","description":"Returns the agent's basic state including beliefs and goals.\nTenant is identified by the `X-Tenant-Id` header.","operationId":"get_single_agent","parameters":[{"name":"agent_id","in":"path","description":"Agent ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Agent state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetAgentStateResponse"}}}},"404":{"description":"Agent not found"},"500":{"description":"Internal error"}},"security":[{"tenant_auth":[]}]},"delete":{"tags":["cognitive"],"summary":"Delete a cognitive agent.","description":"Removes the agent and its associated goals from the registry.\nTenant is identified by the `X-Tenant-Id` header.","operationId":"delete_agent","parameters":[{"name":"agent_id","in":"path","description":"Agent ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Agent deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteAgentResponse"}}}},"404":{"description":"Agent not found"}},"security":[{"tenant_auth":[]}]}},"/api/v1/cognitive/agents/{agent_id}/drives":{"get":{"tags":["cognitive"],"summary":"Get agent drives and motivation state.","description":"Returns drives, deficits, curiosity targets, and the dominant drive.\nTenant is identified by the `X-Tenant-Id` header.","operationId":"get_agent_drives","parameters":[{"name":"agent_id","in":"path","description":"Agent ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Agent motivation state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MotivationStateDto"}}}},"404":{"description":"Agent not found"},"500":{"description":"Internal error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/cognitive/agents/{agent_id}/extended-state":{"get":{"tags":["cognitive"],"summary":"Get extended agent state including full cognitive state.","description":"Returns beliefs, goals, intentions, pending perceptions, activations,\nrecent episodes, and rule utilities.\nTenant is identified by the `X-Tenant-Id` header.","operationId":"get_extended_agent_state","parameters":[{"name":"agent_id","in":"path","description":"Agent ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Extended agent state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetExtendedAgentStateResponse"}}}},"404":{"description":"Agent not found"},"500":{"description":"Internal error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/cognitive/feedback":{"post":{"tags":["cognitive"],"summary":"Provide user feedback on agent results.","description":"This enables the agent to learn from user corrections and preferences.\nAll feedback is stored as Ψ-terms for TRUE HOMOICONICITY - they are\nqueryable, unifiable, and can be reasoned about by the agent.\n\n## Feedback Rating\n- `+1`: Result was correct/helpful - increases rule utility\n- `0`: Neutral - no learning\n- `-1`: Result was wrong - decreases rule utility, triggers correction learning\n\n## Corrections\nWhen a correction is provided:\n1. A `user_correction` Ψ-term is created with the correct answer pattern\n2. Rules that produced the wrong result have their utility decreased\n3. A new rule may be learned from the correction\n\n## Preferences\nWhen a preference is provided:\n1. A `user_preference` Ψ-term is created (subsort of constraint)\n2. Future reasoning can consider this preference","operationId":"provide_feedback","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProvideFeedbackRequest"}}},"required":true},"responses":{"200":{"description":"Feedback recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProvideFeedbackResponse"}}}},"404":{"description":"Agent not found"},"500":{"description":"Internal error"}}}},"/api/v1/cognitive/learn_correction":{"post":{"tags":["cognitive"],"summary":"Learn from a user correction with explicit pattern.","description":"Unlike `provide_feedback` which accepts natural language corrections,\nthis endpoint accepts a structured correction pattern directly as Ψ-term features.\nThis is useful when the client has already parsed the correction.","operationId":"learn_from_correction","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LearnFromCorrectionRequest"}}},"required":true},"responses":{"200":{"description":"Correction learned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LearnFromCorrectionResponse"}}}},"404":{"description":"Agent not found"},"500":{"description":"Internal error"}}}},"/api/v1/collections":{"post":{"tags":["collections"],"summary":"Create a collection","description":"# Authorization\nRequires X-Namespace-Id header. The namespace_id field in the request body is ignored.","operationId":"create_collection","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCollectionRequest"}}},"required":true},"responses":{"201":{"description":"Create a collection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/collections/namespace/{namespace_id}":{"get":{"tags":["collections"],"summary":"List all collections in a namespace","operationId":"list_collections","parameters":[{"name":"namespace_id","in":"path","description":"Namespace ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"List all collections","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionListResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/collections/namespace/{namespace_id}/roots":{"get":{"tags":["collections"],"summary":"Get root collections in a namespace","operationId":"get_root_collections","parameters":[{"name":"namespace_id","in":"path","description":"Namespace ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Get root collections","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionListResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/collections/path/{namespace_id}/{path}":{"get":{"tags":["collections"],"summary":"Get a collection by path within a namespace","operationId":"get_collection_by_path","parameters":[{"name":"namespace_id","in":"path","description":"Namespace ID","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"path","in":"path","description":"Collection path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Get collection by path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/collections/query/by-path":{"post":{"tags":["collections"],"summary":"Query terms by collection path prefix (placeholder - needs term integration)","operationId":"query_terms_by_collection_path","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryByCollectionPathRequest"}}},"required":true},"responses":{"200":{"description":"Query terms by path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TermListResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/collections/query/in-collection":{"post":{"tags":["collections"],"summary":"Query terms in a collection (placeholder - needs term integration)","operationId":"query_terms_in_collection","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryInCollectionRequest"}}},"required":true},"responses":{"200":{"description":"Query terms in collection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TermListResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/collections/{id}":{"get":{"tags":["collections"],"summary":"Get a collection by ID","operationId":"get_collection","parameters":[{"name":"id","in":"path","description":"Collection ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Get a collection by ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]},"put":{"tags":["collections"],"summary":"Update collection metadata","operationId":"update_collection","parameters":[{"name":"id","in":"path","description":"Collection ID","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCollectionRequest"}}},"required":true},"responses":{"200":{"description":"Update collection metadata"},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]},"delete":{"tags":["collections"],"summary":"Delete a collection","operationId":"delete_collection","parameters":[{"name":"id","in":"path","description":"Collection ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Delete a collection"},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/collections/{id}/ancestors":{"get":{"tags":["collections"],"summary":"Get ancestors of a collection","operationId":"get_collection_ancestors","parameters":[{"name":"id","in":"path","description":"Collection ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Get ancestors","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionListResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/collections/{id}/children":{"get":{"tags":["collections"],"summary":"Get children of a collection","operationId":"get_collection_children","parameters":[{"name":"id","in":"path","description":"Collection ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Get children of a collection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionListResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/collections/{id}/descendants":{"get":{"tags":["collections"],"summary":"Get all descendants of a collection","operationId":"get_collection_descendants","parameters":[{"name":"id","in":"path","description":"Collection ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Get all descendants","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectionListResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/communities/detect":{"post":{"tags":["communities"],"summary":"Detect communities from terms","description":"POST /api/v1/communities/detect\n\nRuns Leiden community detection on terms belonging to the specified tenant.\nCreates Community and CommunityMembership PsiTerms in the knowledge base.","operationId":"detect_communities","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetectCommunitiesRequest"}}},"required":true},"responses":{"200":{"description":"Detect communities from terms","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetectCommunitiesResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/communities/memberships":{"post":{"tags":["communities"],"summary":"Get community memberships for a term","description":"POST /api/v1/communities/memberships\n\nReturns all communities that a term belongs to, with membership degrees.","operationId":"get_memberships","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetMembershipsRequest"}}},"required":true},"responses":{"200":{"description":"Get community memberships","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetMembershipsResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/communities/search":{"post":{"tags":["communities"],"summary":"Search communities","description":"POST /api/v1/communities/search\n\nSearch for communities by various criteria:\n- ByEntities: Find communities containing specific terms\n- ByImpact: Find high-impact communities\n- ByLevel: Find communities at a specific hierarchy level\n- ByKeyword: Search community reports by keyword","operationId":"search_communities","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchCommunitiesRequest"}}},"required":true},"responses":{"200":{"description":"Search communities","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchCommunitiesResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/connector-types":{"get":{"tags":["connectors"],"summary":"List available connector types (global catalog).","description":"GET /api/v1/connector-types","operationId":"list_types","responses":{"200":{"description":"Global catalog of connector types","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ConnectorTypeDto"}}}}},"500":{"description":"Internal server error"}}}},"/api/v1/connectors/manage":{"get":{"tags":["connectors"],"summary":"List tenant's connectors.","description":"GET /api/v1/connectors/manage","operationId":"list","responses":{"200":{"description":"Tenant's connector instances","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ConnectorInstanceDto"}}}}},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]},"post":{"tags":["connectors"],"summary":"Add a connector instance to the tenant.","description":"POST /api/v1/connectors/manage","operationId":"add","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddConnectorRequest"}}},"required":true},"responses":{"201":{"description":"Connector instance created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddConnectorResponse"}}}},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/connectors/manage/{name}":{"delete":{"tags":["connectors"],"summary":"Remove a connector from the tenant (cascades: deletes tokens).","description":"DELETE /api/v1/connectors/manage/{name}","operationId":"remove","parameters":[{"name":"name","in":"path","description":"Connector instance name","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Connector removed"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/connectors/manage/{name}/connect":{"post":{"tags":["connectors"],"summary":"Start OAuth flow — returns auth URL for popup.","description":"POST /api/v1/connectors/manage/{name}/connect","operationId":"start_oauth","parameters":[{"name":"name","in":"path","description":"Connector instance name","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OAuth authorization URL for the popup flow","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthStartResponse"}}}},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/connectors/manage/{name}/disconnect":{"post":{"tags":["connectors"],"summary":"Disconnect a connector (revoke tokens, set status=disconnected).","description":"POST /api/v1/connectors/manage/{name}/disconnect","operationId":"disconnect","parameters":[{"name":"name","in":"path","description":"Connector instance name","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Connector disconnected"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/connectors/manage/{name}/oauth/callback":{"get":{"tags":["connectors"],"summary":"OAuth callback — exchanges code for tokens, returns HTML that posts message to opener.","description":"GET /api/v1/connectors/manage/{name}/oauth/callback","operationId":"oauth_callback","parameters":[{"name":"name","in":"path","description":"Connector instance name","required":true,"schema":{"type":"string"}},{"name":"code","in":"query","description":"OAuth authorization code","required":false,"schema":{"type":"string"}},{"name":"error","in":"query","description":"OAuth error code if authorization failed","required":false,"schema":{"type":"string"}},{"name":"error_description","in":"query","description":"Human-readable OAuth error description","required":false,"schema":{"type":"string"}},{"name":"state","in":"query","description":"Opaque state parameter (tenant_id:connector_name)","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"HTML page that posts a message to the opener window and closes itself","content":{"text/html":{}}}}}},"/api/v1/constraint-sessions":{"get":{"tags":["constraints"],"summary":"List all active sessions (for debugging/admin)","operationId":"list_sessions","responses":{"200":{"description":"List all sessions","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ConstraintSessionStatusResponse"}}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]},"post":{"tags":["constraints"],"summary":"Create a new constraint session","operationId":"create_session","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateConstraintSessionRequest"}}},"required":true},"responses":{"200":{"description":"Create constraint session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSessionResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/constraint-sessions/cleanup":{"post":{"tags":["constraints"],"summary":"Clean up old sessions (should be called periodically)","operationId":"cleanup_old_sessions","responses":{"200":{"description":"Clean up old sessions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CleanupSessionsResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/constraint-sessions/{session_id}":{"get":{"tags":["constraints"],"summary":"Get status of a constraint session","operationId":"get_session_status","parameters":[{"name":"session_id","in":"path","description":"Session ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Get session status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConstraintSessionStatusResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]},"delete":{"tags":["constraints"],"summary":"Delete a constraint session","operationId":"delete_session","parameters":[{"name":"session_id","in":"path","description":"Session ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Delete constraint session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteSessionResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/constraint-sessions/{session_id}/bindings":{"post":{"tags":["constraints"],"summary":"Bind variables to trigger constraint propagation","operationId":"bind_variables","parameters":[{"name":"session_id","in":"path","description":"Session ID","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BindVariablesRequest"}}},"required":true},"responses":{"200":{"description":"Bind variables in session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BindVariablesResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/constraint-sessions/{session_id}/constraints":{"post":{"tags":["constraints"],"summary":"Add constraints incrementally to an existing session","operationId":"add_constraints","parameters":[{"name":"session_id","in":"path","description":"Session ID","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddConstraintsRequest"}}},"required":true},"responses":{"200":{"description":"Add constraints to session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddConstraintsResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/constraints/solve":{"post":{"tags":["constraints"],"summary":"Solve a constraint problem in one shot","description":"For problems where you have all constraints upfront and want immediate results.\nUses IncrementalConstraintStore internally with automatic cleanup.\n\nProcess:\n1. Creates temporary constraint store\n2. Binds initial variables (if provided)\n3. Adds all constraints\n4. Solves via automatic propagation\n5. Returns solution (store auto-cleans)\n\nFor incremental solving where constraints arrive over time:\nUse POST /api/v1/constraint-sessions and related endpoints.","operationId":"solve_constraints","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SolveConstraintRequest"}}},"required":true},"responses":{"200":{"description":"Solve constraints in one shot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SolveConstraintResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/context/assemble":{"post":{"tags":["context"],"summary":"Assemble structured context from the knowledge graph","description":"POST /api/v1/context/assemble\n\nTakes a query and assembles optimized, structured context from the knowledge\ngraph within a configurable token budget. The output is suitable for direct\ninclusion in LLM prompts.\n\nThe pipeline:\n1. Fuzzy search for matching concepts\n2. Graph traversal for prerequisites/dependents/related concepts\n3. Relation term scanning for ingestion-extracted relations\n4. Provenance lookup for source text excerpts\n5. Schema compression for hierarchy summary\n6. Priority-based assembly within token budget","operationId":"assemble_context","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssembleContextRequestDto"}}},"required":true},"responses":{"200":{"description":"Assembled context","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssembleContextResponseDto"}}}},"400":{"description":"Invalid request"},"500":{"description":"Internal error"}},"security":[{"tenant_id":[]}]}},"/api/v1/control/assign/backtrackable":{"post":{"tags":["control"],"summary":"Backtrackable assignment\nPOST /api/v1/control/assign/backtrackable","operationId":"assign_backtrackable","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BacktrackableAssignRequest"}}},"required":true},"responses":{"200":{"description":"Backtrackable assignment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BacktrackableAssignResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/control/assign/global":{"post":{"tags":["control"],"summary":"Global assignment\nPOST /api/v1/control/assign/global","operationId":"assign_global","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlobalAssignRequest"}}},"required":true},"responses":{"200":{"description":"Global assignment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlobalAssignResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/control/call-once":{"post":{"tags":["control"],"summary":"Execute with cut (call_once)\nPOST /api/v1/control/call-once","operationId":"control_call_once","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallOnceRequest"}}},"required":true},"responses":{"200":{"description":"Execute with cut","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallOnceResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/control/cond":{"post":{"tags":["control"],"summary":"Execute conditional (if-then-else)\nPOST /api/v1/control/cond","operationId":"control_cond","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CondRequest"}}},"required":true},"responses":{"200":{"description":"Execute conditional if-then-else","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CondResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/control/cut":{"post":{"tags":["control"],"summary":"Execute cut\nPOST /api/v1/control/cut","operationId":"control_cut","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CutRequest"}}},"required":true},"responses":{"200":{"description":"Execute cut","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CutResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/control/findall":{"post":{"tags":["control"],"summary":"Collect all solutions (findall)\nPOST /api/v1/control/findall","operationId":"control_findall","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindallRequest"}}},"required":true},"responses":{"200":{"description":"Collect all solutions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindallResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/control/forall":{"post":{"tags":["control"],"summary":"Universal quantification (forall)\nPOST /api/v1/control/forall","operationId":"control_forall","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForallRequest"}}},"required":true},"responses":{"200":{"description":"Universal quantification","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForallResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/control/global/get":{"post":{"tags":["control"],"summary":"Get global variable\nPOST /api/v1/control/global/get","operationId":"global_get","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlobalGetRequest"}}},"required":true},"responses":{"200":{"description":"Get global variable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlobalGetResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/control/global/incr":{"post":{"tags":["control"],"summary":"Global increment\nPOST /api/v1/control/global/incr","operationId":"global_increment","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlobalIncrementRequest"}}},"required":true},"responses":{"200":{"description":"Global increment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlobalIncrementResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/control/implies":{"post":{"tags":["control"],"summary":"Evaluate implication (A -> B)\nPOST /api/v1/control/implies","operationId":"control_implies","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImpliesRequest"}}},"required":true},"responses":{"200":{"description":"Evaluate implication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImpliesResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/control/naf":{"post":{"tags":["control"],"summary":"Negation as failure\nPOST /api/v1/control/naf","operationId":"control_naf","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NafRequest"}}},"required":true},"responses":{"200":{"description":"Negation as failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NafResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/control/undo":{"post":{"tags":["control"],"summary":"Register undo action\nPOST /api/v1/control/undo","operationId":"control_undo","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UndoRequest"}}},"required":true},"responses":{"200":{"description":"Register undo action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UndoResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/conversation/history":{"get":{"tags":["conversation"],"summary":"GET /api/v1/conversation/history","description":"List recent conversations for the authenticated user.","operationId":"list_conversations","responses":{"200":{"description":"Conversation list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListConversationsResponseDto"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/conversation/message":{"post":{"tags":["conversation"],"summary":"POST /api/v1/conversation/message","description":"Process a user message through the conversation pipeline.","operationId":"send_message","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationMessageRequestDto"}}},"required":true},"responses":{"200":{"description":"Message processed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationMessageResponseDto"}}}},"500":{"description":"Internal error"}},"security":[{"tenant_id":[]}]}},"/api/v1/conversation/{id}":{"delete":{"tags":["conversation"],"summary":"DELETE /api/v1/conversation/:id","description":"Delete a conversation and all its turns.","operationId":"delete_conversation","parameters":[{"name":"id","in":"path","description":"Conversation ID","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Conversation deleted"},"404":{"description":"Conversation not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/conversation/{id}/turns":{"get":{"tags":["conversation"],"summary":"GET /api/v1/conversation/:id/turns","description":"Get all turns for a conversation.","operationId":"get_conversation_turns","parameters":[{"name":"id","in":"path","description":"Conversation ID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Conversation turns","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationTurnsResponseDto"}}}},"404":{"description":"Conversation not found"}},"security":[{"tenant_id":[]}]}},"/api/v1/copy/batch":{"post":{"tags":["copy"],"summary":"Batch copy terms\nPOST /api/v1/copy/batch","operationId":"batch_copy","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchCopyRequest"}}},"required":true},"responses":{"200":{"description":"Batch copy terms","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchCopyResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/copy/deep":{"post":{"tags":["copy"],"summary":"Deep copy a term with cycle detection\nPOST /api/v1/copy/deep","operationId":"deep_copy","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeepCopyRequest"}}},"required":true},"responses":{"200":{"description":"Deep copy with cycle detection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeepCopyResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/copy/term":{"post":{"tags":["copy"],"summary":"Copy a term with specified semantics\nPOST /api/v1/copy/term","operationId":"copy_term","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CopyTermRequest"}}},"required":true},"responses":{"200":{"description":"Copy a term","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CopyTermResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/discovery/effects":{"post":{"tags":["discovery"],"summary":"Train effect discovery model from time series data.","description":"POST /api/v1/discovery/effects\n\nIngests time series data, discovers seasonal patterns, extracts effects,\nand stores everything in the OSF Knowledge Base as PsiTerms with FuzzyNumber features.\n\nThis endpoint creates:\n- A Sort hierarchy for discovered regimes (e.g., seasons for weather data)\n- PsiTerms representing historical observations with effect features\n- Effect distributions that can be queried via /fuzzy/predict-effect\n\n# Request Body\n\n```json\n{\n \"name\": \"weather_prediction\",\n \"data\": [\n { \"timestamp\": \"2024-01-01T12:00:00Z\", \"values\": { \"temperature\": 5.0, \"humidity\": 80.0 } },\n { \"timestamp\": \"2024-01-02T12:00:00Z\", \"values\": { \"temperature\": 7.0, \"humidity\": 75.0 } }\n ],\n \"target_feature\": \"temperature\",\n \"config\": { \"window_size\": 7, \"num_regimes\": 4 }\n}\n```\n\n# Response\n\n```json\n{\n \"success\": true,\n \"regimes_discovered\": 4,\n \"effects_extracted\": 12,\n \"discovered_horizons\": [{ \"horizon\": 7, \"score\": 0.85, \"confidence\": 0.9 }],\n \"sort_ids\": { \"winter\": \"uuid\", \"spring\": \"uuid\", \"summer\": \"uuid\", \"fall\": \"uuid\" },\n \"terms_created\": 365,\n \"root_sort_id\": \"uuid\",\n \"processing_time_ms\": 150\n}\n```","operationId":"discover_effects","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscoverEffectsRequest"}}},"required":true},"responses":{"200":{"description":"Effects discovered successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscoverEffectsResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/discovery/predict":{"post":{"tags":["discovery"],"summary":"Predict effects using discovered model.","description":"POST /api/v1/discovery/predict\n\nFinds similar historical patterns and predicts effects using\nfuzzy search with PRODUCT t-norm reweighting for better aggregation.","operationId":"predict_from_discovery","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PredictFromDiscoveryRequest"}}},"required":true},"responses":{"200":{"description":"Prediction successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PredictFromDiscoveryResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/documents/analyze":{"post":{"tags":["document-analysis"],"operationId":"analyze_documents","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyzeDocumentsRequestDto"}}},"required":true},"responses":{"200":{"description":"Analysis report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentAnalysisResponse"}}}},"503":{"description":"LLM not available"}},"security":[{"tenant_id":[]}]}},"/api/v1/execution/cleanup":{"post":{"tags":["execution"],"summary":"Clean up stale sessions from memory and optionally from database.\nThis should be called periodically (e.g., via cron or health check) to prevent memory leaks.","description":"Query parameters:\n- max_age_hours: Sessions older than this will be cleaned (default: 24)\n- include_db: Also clean stale sessions from database (default: false)","operationId":"cleanup_stale_sessions","parameters":[{"name":"max_age_hours","in":"query","description":"Sessions older than this many hours will be cleaned (default: 24)","required":false,"schema":{"type":"integer","format":"int64"}},{"name":"include_db","in":"query","description":"Also clean stale sessions from database (default: false)","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Clean up stale sessions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CleanupResponse"}}}},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/execution/curry":{"post":{"tags":["execution"],"summary":"Create a curried function","description":"NOTE: Curried functions are ephemeral and not persisted. They will be\nlost on server restart. Use within a single session lifecycle.","operationId":"create_curried_function","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCurriedFunctionRequest"}}},"required":true},"responses":{"200":{"description":"Create a curried function","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurriedFunctionResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/execution/curry/apply":{"post":{"tags":["execution"],"summary":"Apply arguments to a curried function","operationId":"apply_curried","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplyCurriedRequest"}}},"required":true},"responses":{"200":{"description":"Apply arguments to curried function","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplyCurriedResponse"}}}},"404":{"description":"Curried function not found"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/execution/curry/detect":{"post":{"tags":["execution"],"summary":"Detect missing attributes for currying decision","operationId":"detect_currying_context","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetectMissingAttributesRequest"}}},"required":true},"responses":{"200":{"description":"Detect currying context","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CurryingContextResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/execution/sessions":{"post":{"tags":["execution"],"summary":"Create a new execution session","operationId":"create_execution_session","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateExecutionSessionRequest"}}},"required":true},"responses":{"200":{"description":"Create a new execution session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecutionSessionResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/execution/sessions/{session_id}":{"get":{"tags":["execution"],"summary":"Get session status","operationId":"get_execution_session","parameters":[{"name":"session_id","in":"path","description":"Session ID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Get execution session status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecutionSessionResponse"}}}},"404":{"description":"Session not found"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]},"delete":{"tags":["execution"],"summary":"Delete an execution session","operationId":"delete_execution_session","parameters":[{"name":"session_id","in":"path","description":"Session ID","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Execution session deleted"},"404":{"description":"Session not found"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/execution/sessions/{session_id}/backtrack":{"post":{"tags":["execution"],"summary":"Backtrack to a choice point","operationId":"backtrack","parameters":[{"name":"session_id","in":"path","description":"Session ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BacktrackRequest"}}},"required":true},"responses":{"200":{"description":"Backtrack to a choice point","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BacktrackResponse"}}}},"404":{"description":"Session not found"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/execution/sessions/{session_id}/bind":{"post":{"tags":["execution"],"summary":"Bind a term in the session","operationId":"bind_term","parameters":[{"name":"session_id","in":"path","description":"Session ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BindTermRequest"}}},"required":true},"responses":{"200":{"description":"Bind a term in the session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BindTermResponse"}}}},"404":{"description":"Session not found"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/execution/sessions/{session_id}/bindings":{"post":{"tags":["execution"],"summary":"Get current bindings","operationId":"get_bindings","parameters":[{"name":"session_id","in":"path","description":"Session ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetBindingsRequest"}}},"required":true},"responses":{"200":{"description":"Get current bindings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BindingsResponse"}}}},"404":{"description":"Session not found"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/execution/sessions/{session_id}/goals":{"get":{"tags":["execution"],"summary":"Get the current goal stack","operationId":"get_goal_stack","parameters":[{"name":"session_id","in":"path","description":"Session ID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Get the goal stack","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoalStackResponse"}}}},"404":{"description":"Session not found"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]},"post":{"tags":["execution"],"summary":"Push a goal onto the stack","operationId":"push_goal","parameters":[{"name":"session_id","in":"path","description":"Session ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushGoalRequest"}}},"required":true},"responses":{"200":{"description":"Push a goal onto the stack","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushGoalResponse"}}}},"404":{"description":"Session not found"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/execution/sessions/{session_id}/goals/pop":{"post":{"tags":["execution"],"summary":"Pop a goal from the stack","operationId":"pop_goal","parameters":[{"name":"session_id","in":"path","description":"Session ID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Pop a goal from the stack","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoalStackResponse"}}}},"404":{"description":"Session not found"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/execution/sessions/{session_id}/lazy-eval":{"post":{"tags":["execution"],"summary":"Evaluate a term lazily","operationId":"lazy_eval","parameters":[{"name":"session_id","in":"path","description":"Session ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LazyEvalRequest"}}},"required":true},"responses":{"200":{"description":"Evaluate a term lazily","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LazyEvalResponse"}}}},"404":{"description":"Session not found"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/execution/sessions/{session_id}/mark":{"post":{"tags":["execution"],"summary":"Mark a choice point","operationId":"mark_choice_point","parameters":[{"name":"session_id","in":"path","description":"Session ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkChoicePointRequest"}}},"required":true},"responses":{"200":{"description":"Mark a choice point","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChoicePointMarkerResponse"}}}},"404":{"description":"Session not found"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/execution/sessions/{session_id}/residuate":{"post":{"tags":["execution"],"summary":"Residuate a goal on a variable","operationId":"residuate_goal","parameters":[{"name":"session_id","in":"path","description":"Session ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResiduateGoalRequest"}}},"required":true},"responses":{"200":{"description":"Residuate a goal on a variable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResiduatedTermDto"}}}},"404":{"description":"Session not found"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/execution/sessions/{session_id}/residuations":{"post":{"tags":["execution"],"summary":"Get residuations for a term","operationId":"get_residuations","parameters":[{"name":"session_id","in":"path","description":"Session ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetResiduationsRequest"}}},"required":true},"responses":{"200":{"description":"Get residuations for a term","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetResiduationsResponse"}}}},"404":{"description":"Session not found"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/execution/sessions/{session_id}/residuations/append":{"post":{"tags":["execution"],"summary":"Append residuations during unification","operationId":"append_residuations","parameters":[{"name":"session_id","in":"path","description":"Session ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppendResiduationsRequest"}}},"required":true},"responses":{"200":{"description":"Append residuations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppendResiduationsResponse"}}}},"404":{"description":"Session not found"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/execution/sessions/{session_id}/residuations/pending":{"post":{"tags":["execution"],"summary":"Mark a residuation as pending","operationId":"mark_pending","parameters":[{"name":"session_id","in":"path","description":"Session ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkPendingRequest"}}},"required":true},"responses":{"200":{"description":"Mark a residuation as pending","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkPendingResponse"}}}},"404":{"description":"Session not found"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/execution/sessions/{session_id}/residuations/release":{"post":{"tags":["execution"],"summary":"Release residuations for a term","operationId":"release_residuations","parameters":[{"name":"session_id","in":"path","description":"Session ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReleaseResiduationsRequest"}}},"required":true},"responses":{"200":{"description":"Release residuations for a term","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReleaseResiduationsResponse"}}}},"404":{"description":"Session not found"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/execution/stats":{"get":{"tags":["execution"],"operationId":"get_session_stats","responses":{"200":{"description":"Get session statistics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionStatsResponse"}}}},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/external-actions":{"get":{"tags":["webhook-actions"],"summary":"List all registered external actions for a tenant.","operationId":"list_external_actions","parameters":[{"name":"tenant_id","in":"query","description":"Tenant ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"List of actions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListExternalActionsResponse"}}}}}},"post":{"tags":["webhook-actions"],"summary":"Register a new external action type.","description":"Creates a sort inheriting from `effect` in the sort hierarchy.","operationId":"register_external_action","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterExternalActionRequest"}}},"required":true},"responses":{"201":{"description":"Action registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterExternalActionResponse"}}}},"400":{"description":"Invalid request"},"409":{"description":"Action already exists"}}}},"/api/v1/external-actions/{name}/invoke":{"post":{"tags":["webhook-actions"],"summary":"Invoke a registered external action.","description":"Creates an action Ψ-term with inputs, creates a pending invocation,\nattaches a demon for residuation, and returns the invocation ID.","operationId":"invoke_action","parameters":[{"name":"name","in":"path","description":"Action name","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvokeActionRequest"}}},"required":true},"responses":{"200":{"description":"Action invoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvokeActionResponse"}}}},"404":{"description":"Action not found"}}}},"/api/v1/extract/entities":{"post":{"tags":["extraction"],"summary":"Extract named entities from text using the tenant's sort hierarchy as labels.","description":"Uses GLiNER2 (zero-shot NER) with sort names from the tenant's knowledge base,\nguaranteeing that all returned entity labels are valid sort names.\n\nLabel selection (when no explicit labels provided):\nEmbed the input text and ANN-search the pre-computed sort embedding index\n(Qdrant) for the most semantically similar HPO sorts. This is O(log n) and\ntypically returns 20-100 highly relevant labels from 19K+ HPO sorts.\n\nRequires:\n- GLiNER2 NER service (`GLINER_NER_URL`)\n- Qdrant vector store for semantic label selection\n\nIf either is not configured, returns a 500 error.","operationId":"extract_entities","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractEntitiesRequest"}}},"required":true},"responses":{"200":{"description":"Extracted entities","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractEntitiesResponse"}}}},"400":{"description":"Invalid request"},"500":{"description":"NER extractor not configured or extraction failed"}},"security":[{"tenant_id":[]}]}},"/api/v1/extract/image":{"post":{"tags":["image-extraction"],"summary":"Extract concepts from an image using a vision LLM.","description":"Sends the image directly to a vision-capable model (Qwen3-VL) for concept\nextraction. Returns extracted entities, relations, and suggested sorts.\n\nIf `persist=true` (default), the extracted concepts are persisted as PsiTerms\nand synced to the homoiconic inference stores.","operationId":"extract_image","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractImageRequest"}}},"required":true},"responses":{"200":{"description":"Image concepts extracted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractImageResponse"}}}},"400":{"description":"Invalid request"},"500":{"description":"Internal server error"}},"security":[{"tenant_id":[]}]}},"/api/v1/functions/evaluate":{"post":{"tags":["functions"],"summary":"Handler to evaluate a function using LIFE-style FunctionEvaluator","operationId":"evaluate_function","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvaluateFunctionRequest"}}},"required":true},"responses":{"200":{"description":"Function evaluated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvaluateFunctionResponse"}}}},"400":{"description":"No clause matched or evaluation error"}},"security":[{"tenant_id":[]}]}},"/api/v1/functions/register":{"post":{"tags":["functions"],"summary":"Handler to register a user-defined function","operationId":"register_function","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterFunctionRequest"}}},"required":true},"responses":{"200":{"description":"Function registered successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterFunctionResponse"}}}},"400":{"description":"Invalid function definition"}},"security":[{"tenant_id":[]}]}},"/api/v1/fuzzy/predict-effect":{"post":{"tags":["fuzzy"],"summary":"Predict effect by finding similar terms and merging their effects","description":"POST /api/v1/fuzzy/predict-effect\n\nThis endpoint implements term-based Bayesian effect prediction:\n1. Finds similar terms using fuzzy similarity search\n2. Extracts FuzzyNumber effect values from matching terms\n3. Merges them using Bayesian conjugate update (for Gaussians)\n4. Returns the merged posterior distribution","operationId":"predict_effect","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PredictEffectRequest"}}},"required":true},"responses":{"200":{"description":"Effect prediction result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PredictEffectResponse"}}}},"404":{"description":"Query term not found"},"500":{"description":"Similarity search failed"}},"security":[{"tenant_id":[]}]}},"/api/v1/fuzzy/similar":{"post":{"tags":["fuzzy"],"summary":"Find similar terms","description":"POST /fuzzy/similar\n\nReturns all terms with similarity >= min_degree","operationId":"find_similar","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindSimilarRequest"}}},"required":true},"responses":{"200":{"description":"Similar terms","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimilaritySearchResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/fuzzy/top-k":{"post":{"tags":["fuzzy"],"summary":"Find top-K most similar terms (RAG-style retrieval)","description":"POST /api/v1/fuzzy/top-k\n\nImplements **Top-K similarity search** commonly used in RAG (Retrieval-Augmented\nGeneration) systems. Returns the K most similar terms to a query, sorted by\nfuzzy similarity degree in **descending order** (best matches first).\n\n# Algorithm\n\n1. Filter candidates by `min_degree` threshold (if specified)\n2. Compute fuzzy similarity degree μ ∈ [0,1] for each candidate\n3. Sort by similarity (descending - highest first)\n4. Return top K results\n\n# Request Body\n\n```json\n{\n \"query\": {\n \"term_id\": \"uuid\" // Or inline query with sort_id + features\n },\n \"k\": 5,\n \"min_degree\": 0.7 // Optional: minimum similarity threshold\n}\n```\n\n# Response\n\n```json\n{\n \"results\": [\n {\n \"term\": { \"id\": \"...\", \"sort\": \"...\", \"features\": {...} },\n \"degree\": 0.95,\n \"confidence_percent\": 95.0\n },\n // ... up to K results, sorted by degree (descending)\n ],\n \"count\": 5\n}\n```\n\n# Sorting Guarantee\n\nResults are **always sorted by similarity** (highest first):\n`response.results[i].degree >= response.results[i+1].degree`\n\n# Use Cases\n\n- **RAG Context Retrieval**: Find most relevant knowledge for LLM prompts\n- **Semantic Search**: Find similar items without exact matches\n- **Recommendation Systems**: Suggest similar items to users\n- **Deduplication**: Identify near-duplicate entries\n\n# Example\n\nFind 3 most similar sensors with at least 60% similarity:\n\n```bash\ncurl -X POST http://localhost:8080/api/v1/fuzzy/top-k \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"query\": { \"term_id\": \"abc-123\" },\n \"k\": 3,\n \"min_degree\": 0.6\n }'\n```\n\nResponse (sorted by similarity):\n```json\n{\n \"results\": [\n { \"term\": {...}, \"degree\": 0.92, \"confidence_percent\": 92.0 },\n { \"term\": {...}, \"degree\": 0.85, \"confidence_percent\": 85.0 },\n { \"term\": {...}, \"degree\": 0.73, \"confidence_percent\": 73.0 }\n ],\n \"count\": 3\n}\n```","operationId":"fuzzy_search_top_k","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuzzySearchTopKRequest"}}},"required":true},"responses":{"200":{"description":"Top-K similar terms sorted by similarity (descending)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimilaritySearchResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/fuzzy/unify":{"post":{"tags":["fuzzy"],"summary":"Fuzzy unify two terms","description":"POST /fuzzy/unify\n\nReturns unified term with confidence degree","operationId":"fuzzy_unify","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuzzyUnifyRequest"}}},"required":true},"responses":{"200":{"description":"Fuzzy unification result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuzzyUnifyResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/generate":{"post":{"tags":["generation"],"summary":"Runs the evidence-grounded generation pipeline for a given root term.","operationId":"generate_document","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateDocumentRequest"}}},"required":true},"responses":{"200":{"description":"Document generated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateDocumentResponse"}}}},"400":{"description":"Invalid request"},"503":{"description":"No LLM provider configured"}},"security":[{"tenant_id":[]}]}},"/api/v1/grounded-synthesis/runs":{"post":{"tags":["grounded-synthesis"],"summary":"Execute a full grounded-synthesis run against the server's configured LLM.","description":"Builds a scratch `SortHierarchy` / `TermStore` per request (like the\nother endpoints), translates any supplied SHACL shapes into OSF rules,\nruns the full `GroundedSynthesisService` pipeline, and returns a\ncompact DTO view. Requires `state.app.llm_text_port` to be configured;\nreturns 503 if not.","operationId":"run_synthesis","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunSynthesisRequest"}}},"required":true},"responses":{"200":{"description":"Run completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunSynthesisResponse"}}}},"400":{"description":"Invalid request"},"503":{"description":"LLM not configured"}}}},"/api/v1/grounded-synthesis/shacl/translate":{"post":{"tags":["grounded-synthesis"],"summary":"Translate SHACL shapes into homoiconic OSF rules.","operationId":"translate_shacl","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslateShaclRequest"}}},"required":true},"responses":{"200":{"description":"Shapes translated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranslateShaclResponse"}}}},"400":{"description":"Invalid SHACL shape"}}}},"/api/v1/grounded-synthesis/taxonomies/build":{"post":{"tags":["grounded-synthesis"],"summary":"Filter an ontology-derived sort set by relevance scores.","description":"Builds a scratch `SortHierarchy` from the request's `sort_names` (in\ninput order — the first name becomes a root, subsequent names are\nparented to previously-registered names only when a matching `_parent`\nprefix appears; otherwise each is an independent root). In practice\ncallers pass already-ordered topological levels because the frontend\nuploads an OWL import that preserves subClassOf order.","operationId":"build_taxonomy","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuildTaxonomyRequest"}}},"required":true},"responses":{"200":{"description":"Filtered taxonomy returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuildTaxonomyResponse"}}}},"400":{"description":"Invalid request"}}}},"/api/v1/grounded-synthesis/taxonomies/extract":{"post":{"tags":["grounded-synthesis"],"summary":"Reasoning-driven taxonomy extraction.","description":"Paper-inspired (Davidson et al., TMLR 03/2026) alternative to\nontology import: given only a natural-language dataset description,\nask the configured LLM to propose factors of variation, then run a\nbest-of-N taxonomy expansion over each factor. Returns both the\nproposed factors and the ranked child candidates per factor.\n\nUnlike `taxonomies/build` (which requires the caller to supply the\nsort names), this endpoint generates the taxonomy from scratch via\nLLM reasoning.","operationId":"extract_taxonomy","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractTaxonomyRequest"}}},"required":true},"responses":{"200":{"description":"Extracted taxonomy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtractTaxonomyResponse"}}}},"400":{"description":"Invalid request"},"503":{"description":"LLM not configured"}}}},"/api/v1/ilp/evaluate":{"post":{"tags":["ilp"],"summary":"Evaluate a learned pattern on new inputs.","description":"POST /api/v1/ilp/evaluate\n\nExecutes a previously learned arithmetic pattern on new input values\nthat were NOT in the training set. This proves the system learned the\nalgorithm, not just memorized the examples.\n\n# Request Body\n\n```json\n{\n \"pattern_id\": \"factorial_abc123\",\n \"inputs\": [6, 7, 8, 9, 10]\n}\n```\n\n# Response\n\n```json\n{\n \"success\": true,\n \"results\": [\n { \"input\": 6, \"output\": 720 },\n { \"input\": 7, \"output\": 5040 },\n { \"input\": 8, \"output\": 40320 },\n { \"input\": 9, \"output\": 362880 },\n { \"input\": 10, \"output\": 3628800 }\n ],\n \"processing_time_ms\": 1\n}\n```","operationId":"evaluate_pattern","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvaluatePatternRequest"}}},"required":true},"responses":{"200":{"description":"Pattern evaluated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvaluatePatternResponse"}}}},"400":{"description":"Bad request - pattern not found"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/ilp/gflownet/sample":{"post":{"tags":["ilp"],"summary":"Sample diverse hypotheses using GFlowNet.","description":"POST /api/v1/ilp/gflownet/sample\n\nCreates a GFlowNet synthesizer and samples diverse rule hypotheses\nfor the target sort. Uses the trained neural guide when available\nfor biased sampling toward promising regions.","operationId":"gflownet_sample","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GFlowNetSampleRequest"}}},"required":true},"responses":{"200":{"description":"Hypotheses sampled successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GFlowNetSampleResponse"}}}},"400":{"description":"Bad request - sort not found"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/ilp/learn":{"post":{"tags":["ilp"],"summary":"Learn a pattern from training examples.","description":"POST /api/v1/ilp/learn\n\nUses OSF/LIFE anti-unification and recursive schema detection to learn\narithmetic patterns like factorial, fibonacci, and triangular numbers.\n\n# Request Body\n\n```json\n{\n \"name\": \"factorial\",\n \"examples\": [\n { \"input\": 0, \"output\": 1 },\n { \"input\": 1, \"output\": 1 },\n { \"input\": 2, \"output\": 2 },\n { \"input\": 3, \"output\": 6 },\n { \"input\": 4, \"output\": 24 },\n { \"input\": 5, \"output\": 120 }\n ]\n}\n```\n\n# Response\n\n```json\n{\n \"success\": true,\n \"pattern\": {\n \"operation\": \"multiplication\",\n \"input_feature\": \"input\",\n \"output_feature\": \"output\",\n \"base_case_inputs\": [0],\n \"confidence\": 1.0,\n \"description\": \"factorial(n) = n * factorial(n-1), base: factorial(0) = 1\"\n },\n \"pattern_id\": \"factorial_abc123\",\n \"examples_used\": 6,\n \"processing_time_ms\": 5\n}\n```","operationId":"learn_pattern","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LearnPatternRequest"}}},"required":true},"responses":{"200":{"description":"Pattern learned successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LearnPatternResponse"}}}},"400":{"description":"Bad request - insufficient examples"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/ilp/patterns":{"get":{"tags":["ilp"],"summary":"List all learned patterns.","description":"GET /api/v1/ilp/patterns\n\nReturns all patterns that have been learned in this session.","operationId":"list_patterns","responses":{"200":{"description":"Patterns listed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListPatternsResponse"}}}}},"security":[{"tenant_auth":[]}]}},"/api/v1/ilp/synthesize":{"post":{"tags":["ilp"],"summary":"Synthesize rules using neural-guided ILP with optional GFlowNet.","description":"POST /api/v1/ilp/synthesize\n\nUses the trained GFlowNet neural guide (when available) for diverse\nhypothesis sampling, combined with symbolic verification against examples.\nFalls back to symbolic synthesis if GFlowNet doesn't find a solution.","operationId":"synthesize_pattern","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SynthesizeRequest"}}},"required":true},"responses":{"200":{"description":"Synthesis completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SynthesizeResponse"}}}},"400":{"description":"Bad request - insufficient examples"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/inference/backward-chain":{"post":{"tags":["inference"],"summary":"Execute backward chaining query","description":"# TRUE HOMOICONIC API\nRequest contains a goal term and optional constraints.\nResponse returns solutions with term-based substitutions.\n\n## Temporal Reasoning\nUse constraints to filter by temporal relations:\n```json\n{\n \"goal\": {\"sort_name\": \"Employment\", \"features\": {\"valid_to\": {\"name\": \"?EndTime\"}}},\n \"constraints\": [{\"type\": \"Guard\", \"left\": \"?EndTime\", \"op\": \"lt\", \"right\": \"1583020800000\"}]\n}\n```\n\n# Authorization\nRequires X-Tenant-Id header.","operationId":"backward_chain","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BackwardChainRequest"}}},"required":true},"responses":{"200":{"description":"Backward chaining result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BackwardChainResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/inference/bayesian-predict":{"post":{"tags":["inference"],"summary":"Execute Bayesian prediction by merging multiple FuzzyNumber sources","description":"This endpoint:\n1. Runs fuzzy_prove to find all matching facts (priors + learned data)\n2. Extracts FuzzyNumber values from the specified variable binding\n3. Merges them using Bayesian conjugate update (for Gaussians)\n4. Returns the merged posterior distribution\n\n# Authorization\nRequires X-Tenant-Id header. The tenant_id field in the request body is ignored.","operationId":"bayesian_predict","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BayesianPredictRequest"}}},"required":true},"responses":{"200":{"description":"Bayesian prediction successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BayesianPredictResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/inference/facts":{"post":{"tags":["inference"],"summary":"Add a fact to the knowledge base (fact is a rule with empty body)","description":"# DEPRECATED\nThis endpoint is deprecated. Use `POST /api/v1/terms` instead.\nBoth endpoints now do the same thing (TRUE HOMOICONICITY).\n\n# TRUE HOMOICONIC API\nRequest contains a term. Response returns the created fact as a PsiTermDto.\n\n# Authorization\nRequires X-Tenant-Id header.","operationId":"add_fact","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddFactRequest"}}},"required":true},"responses":{"201":{"description":"Fact added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddFactResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/inference/facts/bulk":{"post":{"tags":["inference"],"summary":"Add multiple facts to the knowledge base in bulk\nOptimized for high-throughput insertion (10K+ facts)","description":"# DEPRECATED\nThis endpoint is deprecated. Use `POST /api/v1/terms/bulk` instead.\nBoth endpoints now do the same thing (TRUE HOMOICONICITY).\n\n# TRUE HOMOICONIC API\nRequest contains list of terms. Response returns term IDs.\n\n# Authorization\nRequires X-Tenant-Id header.","operationId":"bulk_add_facts","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkAddFactsRequest"}}},"required":true},"responses":{"201":{"description":"Facts added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkAddFactsResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/inference/facts/{tenant_id}":{"get":{"tags":["inference"],"summary":"Get all facts for a tenant with their full data","description":"# DEPRECATED\nThis endpoint is deprecated. Use `GET /api/v1/terms?tenant_id={tenant_id}` instead.\nBoth endpoints now return the same data (TRUE HOMOICONICITY).\n\n# TRUE HOMOICONIC API\nReturns facts as PsiTermDto.\nUNIFIED: Hydrates from PostgreSQL on first access (facts survive server restarts)\n\n# Authorization\nRequires X-Tenant-Id header.","operationId":"get_facts","parameters":[{"name":"tenant_id","in":"path","description":"Tenant ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Facts list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetFactsResponse"}}}}},"security":[{"tenant_id":[]}]},"delete":{"tags":["inference"],"summary":"Clear all facts and rules for a tenant","description":"# DEPRECATED\nThis endpoint is deprecated. Use `DELETE /api/v1/terms/{term_id}` for individual terms.\n\n# TRUE HOMOICONIC API\n\n# Authorization\nRequires X-Tenant-Id header.","operationId":"clear_facts","parameters":[{"name":"tenant_id","in":"path","description":"Tenant ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Facts cleared","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClearFactsResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/inference/forward-chain":{"post":{"tags":["inference"],"summary":"Execute forward chaining materialization","description":"# TRUE HOMOICONIC API\nUses existing rules in the store. Initial facts can be provided or uses existing facts.\nReturns derived facts as PsiTermDto.\n\n# Authorization\nRequires X-Tenant-Id header.","operationId":"forward_chain","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForwardChainRequest"}}},"required":true},"responses":{"200":{"description":"Forward chaining result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForwardChainResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/inference/forward-chain-tagged":{"post":{"tags":["inference"],"summary":"POST /api/v1/inference/forward-chain-tagged","description":"Runs forward chaining with probabilistic provenance tags.\nEach derived fact carries a confidence value computed from the\nprovenance semiring operations (noisy-or for disjunction,\nproduct for conjunction).\n\nThis extends the standard forward chain endpoint by tracking\nhow confidence propagates through rule application, enabling\nprobabilistic reasoning over the knowledge base.","operationId":"forward_chain_tagged","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaggedForwardChainRequest"}}},"required":true},"responses":{"200":{"description":"Tagged forward chaining completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaggedForwardChainResponse"}}}},"500":{"description":"Forward chaining task panicked"}},"security":[{"tenant_id":[]}]}},"/api/v1/inference/fuzzy-prove":{"post":{"tags":["inference"],"summary":"Execute fuzzy inference","description":"# TRUE HOMOICONIC API\nRequest contains a goal term. Response returns solutions with fuzzy degrees.\n\n# Authorization\nRequires X-Tenant-Id header.","operationId":"fuzzy_prove","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuzzyProveRequest"}}},"required":true},"responses":{"200":{"description":"Fuzzy inference result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuzzyProveResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/inference/fuzzy-prove/bulk":{"post":{"tags":["inference"],"summary":"Execute bulk fuzzy inference - multiple goals in one request","description":"This endpoint dramatically reduces latency by:\n1. Single HTTP round-trip for multiple queries\n2. Shared hierarchy, term store overlay, and rules across all queries\n\n# TRUE HOMOICONIC API\nUses TermInputDto for goals with nested features.\nResponse uses homoiconic SolutionDto.\n\n# Authorization\nRequires X-Tenant-Id header.","operationId":"bulk_fuzzy_prove","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkFuzzyProveRequest"}}},"required":true},"responses":{"200":{"description":"Bulk fuzzy proof results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkFuzzyProveResponse"}}}},"400":{"description":"Invalid request"},"401":{"description":"Unauthorized - missing or invalid X-Tenant-Id"}},"security":[{"tenant_id":[]}]}},"/api/v1/inference/goals":{"get":{"tags":["inference"],"summary":"List all saved goals for the authenticated tenant","description":"# TRUE HOMOICONICITY\nGoals are Ψ-terms persisted to PostgreSQL. This endpoint returns\nall goals for the authenticated tenant with summary information.\n\n# Authorization\nRequires X-Tenant-Id header.","operationId":"list_goals","responses":{"200":{"description":"List of saved goals","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListGoalsResponse"}}}},"401":{"description":"Unauthorized - missing or invalid X-Tenant-Id"}},"security":[{"tenant_id":[]}]},"post":{"tags":["inference"],"summary":"Create and persist a new goal","description":"# TRUE HOMOICONICITY\nGoals are first-class Ψ-terms that can be created, persisted, and reused.\nThis endpoint creates a goal from clauses and optional constraints,\npersists it to PostgreSQL, and returns the goal ID for later use.\n\n# Authorization\nRequires X-Tenant-Id header.","operationId":"create_goal","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateGoalRequest"}}},"required":true},"responses":{"201":{"description":"Goal created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateGoalResponse"}}}},"400":{"description":"Invalid request"},"401":{"description":"Unauthorized - missing or invalid X-Tenant-Id"}},"security":[{"tenant_id":[]}]}},"/api/v1/inference/goals/{goal_id}":{"get":{"tags":["inference"],"summary":"Get a specific saved goal by ID","description":"# TRUE HOMOICONICITY\nReturns the full goal term with all its referenced terms.\n\n# Authorization\nRequires X-Tenant-Id header.","operationId":"get_goal","parameters":[{"name":"goal_id","in":"path","description":"Goal ID to retrieve","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Goal details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PsiTermDto"}}}},"401":{"description":"Unauthorized - missing or invalid X-Tenant-Id"},"404":{"description":"Goal not found"}},"security":[{"tenant_id":[]}]},"delete":{"tags":["inference"],"summary":"Delete a saved goal","description":"# TRUE HOMOICONICITY\nDeletes the goal term. Optionally deletes all referenced terms.\n\n# Authorization\nRequires X-Tenant-Id header.","operationId":"delete_goal","parameters":[{"name":"goal_id","in":"path","description":"Goal ID to delete","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"delete_references","in":"query","description":"Also delete referenced terms","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Goal deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteGoalResponse"}}}},"401":{"description":"Unauthorized - missing or invalid X-Tenant-Id"},"404":{"description":"Goal not found"}},"security":[{"tenant_id":[]}]}},"/api/v1/inference/meta-sorts":{"get":{"tags":["inference"],"summary":"Get meta sort IDs for TRUE HOMOICONICITY","description":"Returns the sort IDs of built-in meta sorts (guard_constraint, variable, etc.)\nClients need these IDs to create terms using built-in sorts.\n\n# TRUE HOMOICONICITY\nIn Aït-Kaci's vision, everything is referenced by ID, not by name.\nThis endpoint provides the IDs clients need for built-in sorts.\n\n# Authorization\nRequires X-Tenant-Id header.","operationId":"get_meta_sorts","responses":{"200":{"description":"Meta sort IDs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetaSortsResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/inference/naf-prove":{"post":{"tags":["inference"],"summary":"Execute NAF-enabled backward chaining","description":"# TRUE HOMOICONIC API\nUses LiteralInputDto with TermInputDto for literals.\nResponse uses homoiconic SolutionDto.\n\n# Authorization\nRequires X-Tenant-Id header.","operationId":"naf_prove","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NafProveRequest"}}},"required":true},"responses":{"200":{"description":"NAF inference result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BackwardChainResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/inference/rules":{"post":{"tags":["inference"],"summary":"Add a rule to the knowledge base","description":"# TRUE HOMOICONIC API\nRequest contains a term (head) and antecedents (body).\nResponse returns the created rule as a PsiTermDto.\n\n# Authorization\nRequires X-Tenant-Id header.","operationId":"add_rule","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddRuleRequest"}}},"required":true},"responses":{"201":{"description":"Rule added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddRuleResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/inference/rules/bulk":{"post":{"tags":["inference"],"summary":"Add multiple rules to the knowledge base in bulk\nOptimized for high-throughput insertion (100+ rules at once)","description":"# TRUE HOMOICONIC API\nRequest contains list of rules (head + antecedents). Response returns rule term IDs.\n\n# Authorization\nRequires X-Tenant-Id header.","operationId":"bulk_add_rules","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkAddRulesRequest"}}},"required":true},"responses":{"201":{"description":"Rules added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkAddRulesResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/ingest/dlq":{"get":{"tags":["ingestion"],"summary":"List pending DLQ entries for the current tenant.","description":"Returns paginated list of chunk failures in the dead-letter queue.","operationId":"list_dlq_entries","parameters":[{"name":"session_id","in":"query","description":"Filter by session ID","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Max entries to return","required":false,"schema":{"type":"integer","format":"int32","minimum":0}},{"name":"offset","in":"query","description":"Offset for pagination","required":false,"schema":{"type":"integer","format":"int32","minimum":0}}],"responses":{"200":{"description":"DLQ entries","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DlqListResponse"}}}},"500":{"description":"Internal server error"}},"security":[{"tenant_id":[]}]}},"/api/v1/ingest/dlq/count":{"get":{"tags":["ingestion"],"summary":"Count pending DLQ entries for the current tenant.","operationId":"count_dlq_entries","responses":{"200":{"description":"Pending DLQ count","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DlqCountResponse"}}}},"500":{"description":"Internal server error"}},"security":[{"tenant_id":[]}]}},"/api/v1/ingest/dlq/{id}/abandon":{"post":{"tags":["ingestion"],"summary":"Abandon a DLQ entry (operator decides to skip it permanently).","description":"Marks a pending DLQ entry as abandoned. Retained for audit but not retried.","operationId":"abandon_dlq_entry","parameters":[{"name":"id","in":"path","description":"DLQ entry ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Entry abandoned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DlqAbandonResponse"}}}},"500":{"description":"Internal server error"}},"security":[{"tenant_id":[]}]}},"/api/v1/ingest/document":{"post":{"tags":["ingestion"],"summary":"Ingest a single document (PDF, DOCX, etc.)","description":"POST /api/v1/ingest/document\n\nThis endpoint accepts a document (as base64 or URL) and:\n1. Parses it to Markdown using the document parser service (Docling)\n2. Processes the Markdown through the existing ingestion pipeline\n3. Returns combined statistics from both stages\n\n# Headers\n- `X-Tenant-Id`: Tenant ID for multi-tenancy isolation (required)\n\n# Request Body\n- `document`: Document source (base64 or URL)\n- `document_type`: Optional type hint (auto-detected if not provided)\n- `owner_id`: User ID who owns the ingested data\n- `ocr_config`: Optional OCR/parsing configuration\n- `ingestion_config`: Optional markdown ingestion configuration\n\n# Response\n- `success`: Whether ingestion completed successfully\n- `parse_stats`: Statistics from document parsing\n- `metadata`: Extracted document metadata\n- `ingestion_stats`: Statistics from markdown ingestion\n- `pending_review`: Entities that need human review","operationId":"ingest_document","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestDocumentRequest"}}},"required":true},"responses":{"201":{"description":"Document ingested successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestDocumentResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_id":[]}]}},"/api/v1/ingest/document/batch":{"post":{"tags":["ingestion"],"summary":"Ingest multiple documents in batch","description":"POST /api/v1/ingest/document/batch\n\nThis endpoint accepts multiple documents and processes them sequentially,\nsharing deduplication context across documents.\n\n# Headers\n- `X-Tenant-Id`: Tenant ID for multi-tenancy isolation (required)","operationId":"ingest_document_batch","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestDocumentBatchRequest"}}},"required":true},"responses":{"201":{"description":"Batch documents ingested successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestDocumentBatchResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_id":[]}]}},"/api/v1/ingest/markdown":{"post":{"tags":["ingestion"],"summary":"Ingest a single markdown document","description":"POST /api/v1/ingest/markdown\n\nThis endpoint accepts markdown content and extracts entities using:\n1. Semantic chunking for large documents\n2. LLM-based entity extraction\n3. Sort reconciliation (optionally creating new sorts)\n4. Entity deduplication against existing knowledge base\n\n# Headers\n- `X-Tenant-Id`: Tenant ID for multi-tenancy isolation (required)\n\n# Request Body\n- `content`: The markdown content to ingest\n- `owner_id`: User ID who owns the ingested data\n- `config`: Optional configuration overrides\n\n# Response\n- `success`: Whether ingestion completed successfully\n- `stats`: Statistics about the ingestion (chunks, entities, sorts)\n- `pending_review`: Entities that need human review for deduplication\n\n# Size Limits\n- Maximum content size is 100KB. For larger documents, use the document\n ingestion endpoint which handles chunking automatically.","operationId":"ingest_markdown","parameters":[{"name":"sync","in":"query","description":"When true, process synchronously (returns 201). When false/absent, process asynchronously (returns 202).","required":true,"schema":{"type":"boolean"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestMarkdownRequest"}}},"required":true},"responses":{"201":{"description":"Markdown ingested successfully (sync mode)"},"202":{"description":"Ingestion accepted for background processing (async mode)"},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_id":[]}]}},"/api/v1/ingest/markdown/batch":{"post":{"tags":["ingestion"],"summary":"Ingest multiple markdown documents in batch","description":"POST /api/v1/ingest/markdown/batch\n\nThis endpoint accepts multiple markdown documents and enqueues them\nfor background processing. Each document is processed independently\nby background workers, tracked under a single session.\n\nWhen a task queue is available (default), returns 202 Accepted immediately.\nFalls back to synchronous processing (201 Created) only when no queue is configured.\n\n# Headers\n- `X-Tenant-Id`: Tenant ID for multi-tenancy isolation (required)\n\n# Request Body\n- `documents`: List of markdown documents with IDs and content\n- `owner_id`: User ID who owns the ingested data\n- `config`: Optional configuration overrides\n\n# Response\n- Async (202): Session ID + document IDs for tracking\n- Sync fallback (201): Full ingestion result with stats","operationId":"ingest_markdown_batch","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestMarkdownBatchRequest"}}},"required":true},"responses":{"201":{"description":"Batch markdown ingested synchronously (fallback)"},"202":{"description":"Batch documents accepted for background processing"},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_id":[]}]}},"/api/v1/ingest/queue-metrics":{"get":{"tags":["ingestion"],"summary":"Get queue metrics for the ingestion pipeline.","description":"Returns current queue depth, document counts by status, circuit breaker\nstate, and worker count.","operationId":"get_queue_metrics","responses":{"200":{"description":"Queue metrics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueueMetricsResponse"}}}},"500":{"description":"Internal server error"}},"security":[{"tenant_id":[]}]}},"/api/v1/ingest/rdf":{"post":{"tags":["ingestion"],"summary":"Ingest RDF/OWL/SHACL data and convert to OSF.","description":"Defaults to async dispatch: returns `202` with a session id and the\npipeline runs in a background tokio task. Pass `?sync=true` to run the\nwhole pipeline inside the request and get a `201` with the full result —\nsuitable only for small ontologies because the embedding loop dominates\nwall time on large inputs.","operationId":"ingest_rdf","parameters":[{"name":"sync","in":"query","description":"When true, run synchronously (returns 201). Default false: returns 202 with a session id.","required":true,"schema":{"type":"boolean"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestRdfRequest"}}},"required":true},"responses":{"201":{"description":"RDF data ingested synchronously","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestRdfResponse"}}}},"202":{"description":"RDF ingestion accepted, running in background","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncIngestRdfResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/ingest/recover-stuck":{"post":{"tags":["ingestion"],"summary":"Recover stuck documents that have been in InProgress too long.","description":"Finds documents stuck in InProgress for longer than the specified timeout\nand releases them back to Pending for re-processing.","operationId":"recover_stuck_documents","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecoverStuckRequest"}}},"required":true},"responses":{"200":{"description":"Recovery result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecoverStuckResponse"}}}},"400":{"description":"Invalid request"},"500":{"description":"Internal server error"}},"security":[{"tenant_id":[]}]}},"/api/v1/ingest/reprocess-failed":{"post":{"tags":["ingestion"],"summary":"Reprocess failed documents by resetting them to Pending.","description":"Finds documents in Failed status, resets them and optionally re-enqueues them.","operationId":"reprocess_failed_documents","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReprocessFailedRequest"}}},"required":true},"responses":{"200":{"description":"Reprocess result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReprocessFailedResponse"}}}},"400":{"description":"Invalid request"},"500":{"description":"Internal server error"}},"security":[{"tenant_id":[]}]}},"/api/v1/ingest/sessions":{"get":{"tags":["ingestion"],"summary":"List all ingestion sessions for the tenant","description":"GET /api/v1/ingest/sessions\n\nReturns all ingestion sessions for the authenticated tenant.\n\n# Headers\n- `X-Tenant-Id`: Tenant ID for multi-tenancy isolation (required)\n\n# Response\n- List of sessions with their status and progress","operationId":"list_ingestion_sessions","responses":{"200":{"description":"List of sessions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListIngestionSessionsResponse"}}}},"500":{"description":"Internal server error"}},"security":[{"tenant_id":[]}]},"post":{"tags":["ingestion"],"summary":"Start a new ingestion session","description":"POST /api/v1/ingest/sessions\n\nCreates a resumable ingestion session for tracking batch document ingestion.\nReturns a session ID that can be used to track progress and resume interrupted ingestion.\n\n# Headers\n- `X-Tenant-Id`: Tenant ID for multi-tenancy isolation (required)\n\n# Request Body\n- `document_ids`: List of document IDs that will be ingested in this session\n\n# Response\n- Session details including ID, status, and document count","operationId":"start_ingestion_session","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartIngestionSessionRequest"}}},"required":true},"responses":{"201":{"description":"Session created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestionSessionResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_id":[]}]}},"/api/v1/ingest/sessions/{session_id}":{"get":{"tags":["ingestion"],"summary":"Get an ingestion session by ID","description":"GET /api/v1/ingest/sessions/{session_id}\n\nReturns details of a specific ingestion session.\n\n# Path Parameters\n- `session_id`: UUID of the session\n\n# Headers\n- `X-Tenant-Id`: Tenant ID for multi-tenancy isolation (required)\n\n# Response\n- Session details including status and progress","operationId":"get_ingestion_session","parameters":[{"name":"session_id","in":"path","description":"Session ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Session details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestionSessionResponse"}}}},"404":{"description":"Session not found"},"500":{"description":"Internal server error"}},"security":[{"tenant_id":[]}]},"delete":{"tags":["ingestion"],"summary":"Delete an ingestion session","description":"DELETE /api/v1/ingest/sessions/{session_id}\n\nDeletes an ingestion session and all associated progress records.\nThis does NOT delete the ingested entities - only the session tracking data.\n\n# Path Parameters\n- `session_id`: UUID of the session to delete\n\n# Headers\n- `X-Tenant-Id`: Tenant ID for multi-tenancy isolation (required)\n\n# Response\n- 204 No Content on success","operationId":"delete_ingestion_session","parameters":[{"name":"session_id","in":"path","description":"Session ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Session deleted successfully"},"404":{"description":"Session not found"},"500":{"description":"Internal server error"}},"security":[{"tenant_id":[]}]}},"/api/v1/ingest/sessions/{session_id}/documents/{document_id}/cancel":{"post":{"tags":["ingestion"],"summary":"Cancel an in-progress or pending document ingestion.","operationId":"cancel_document_ingestion","parameters":[{"name":"session_id","in":"path","description":"Session ID","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"document_id","in":"path","description":"Document ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Document cancelled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelDocumentResponse"}}}},"400":{"description":"Cannot cancel completed/failed document"},"404":{"description":"Session or document not found"}},"security":[{"tenant_id":[]}]}},"/api/v1/ingest/sessions/{session_id}/documents/{document_id}/stats":{"get":{"tags":["ingestion"],"summary":"Get stats for a single document within a session","description":"GET /api/v1/ingest/sessions/{session_id}/documents/{document_id}/stats\n\nReturns ingestion stats for a specific document. Returns 204 No Content\nif the document exists but stats are not yet available (still processing).\n\n# Response Codes\n- 200: Document stats returned\n- 204: Document exists but stats not yet available\n- 404: Session or document not found","operationId":"get_ingestion_document_stats","parameters":[{"name":"session_id","in":"path","description":"Session ID","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"document_id","in":"path","description":"Document ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Document ingestion stats"},"204":{"description":"Document exists but stats not yet available"},"404":{"description":"Session not found"},"500":{"description":"Internal server error"}},"security":[{"tenant_id":[]}]}},"/api/v1/ingest/sessions/{session_id}/incomplete":{"get":{"tags":["ingestion"],"summary":"List incomplete documents in a session","description":"GET /api/v1/ingest/sessions/{session_id}/incomplete\n\nReturns documents that have not completed ingestion and can be resumed.\nFor each document, includes the chunk index to resume from.\n\n# Path Parameters\n- `session_id`: UUID of the session\n\n# Headers\n- `X-Tenant-Id`: Tenant ID for multi-tenancy isolation (required)\n\n# Response\n- List of incomplete documents with their resumption points","operationId":"list_incomplete_documents","parameters":[{"name":"session_id","in":"path","description":"Session ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"List of incomplete documents","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListIncompleteDocumentsResponse"}}}},"404":{"description":"Session not found"},"500":{"description":"Internal server error"}},"security":[{"tenant_id":[]}]}},"/api/v1/ingest/sessions/{session_id}/progress":{"get":{"tags":["ingestion"],"summary":"Get live pipeline progress for all documents in a session.","description":"Returns in-progress document snapshots with rich contextual data.","operationId":"get_ingestion_progress","parameters":[{"name":"session_id","in":"path","description":"Session ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Session progress","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionProgressResponse"}}}},"404":{"description":"Session not found"}},"security":[{"tenant_id":[]}]}},"/api/v1/ingest/sessions/{session_id}/resume":{"post":{"tags":["ingestion"],"summary":"Resume ingestion of a document in a session","description":"POST /api/v1/ingest/sessions/{session_id}/resume\n\nResumes ingestion of an incomplete document from the last successful chunk.\nThe document content must match the original content (verified via hash).\n\n# Path Parameters\n- `session_id`: UUID of the session\n\n# Headers\n- `X-Tenant-Id`: Tenant ID for multi-tenancy isolation (required)\n\n# Request Body\n- `document_id`: ID of the document to resume\n- `content`: Document content (must match original)\n- `owner_id`: User ID performing the ingestion\n- `config`: Optional configuration overrides\n\n# Response\n- Ingestion result including entities extracted and any pending reviews","operationId":"resume_document_ingestion","parameters":[{"name":"session_id","in":"path","description":"Session ID","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResumeDocumentIngestionRequest"}}},"required":true},"responses":{"200":{"description":"Document ingestion resumed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResumeDocumentIngestionResponse"}}}},"400":{"description":"Bad request (content hash mismatch)"},"404":{"description":"Session or document not found"},"500":{"description":"Internal server error"}},"security":[{"tenant_id":[]}]}},"/api/v1/ingest/sessions/{session_id}/stats":{"get":{"tags":["ingestion"],"summary":"Get stats for all completed documents in a session","description":"GET /api/v1/ingest/sessions/{session_id}/stats\n\nReturns per-document ingestion stats (term_ids, sort_names, processing_time_ms, etc.)\nfor all documents in the session that have completed processing.\n\n# Response Codes\n- 200: Stats returned (may be empty if no documents completed yet)\n- 404: Session not found","operationId":"get_ingestion_session_stats","parameters":[{"name":"session_id","in":"path","description":"Session ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Session stats for all completed documents","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionStatsResponse"}}}},"404":{"description":"Session not found"},"500":{"description":"Internal server error"}},"security":[{"tenant_id":[]}]}},"/api/v1/invocations":{"get":{"tags":["webhook-actions"],"summary":"List pending invocations for a tenant.","operationId":"list_pending_invocations","parameters":[{"name":"tenant_id","in":"query","description":"Tenant ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"List of pending invocations","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListPendingInvocationsResponse"}}}}}}},"/api/v1/invocations/{id}/complete":{"post":{"tags":["webhook-actions"],"summary":"Complete a pending invocation (receive webhook callback).","description":"Binds output values to the action Ψ-term's features and fires demons.","operationId":"complete_invocation","parameters":[{"name":"id","in":"path","description":"Invocation ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCallbackRequest"}}},"required":true},"responses":{"200":{"description":"Invocation completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookCallbackResponse"}}}},"404":{"description":"Invocation not found"},"409":{"description":"Invocation already completed"}}}},"/api/v1/modules":{"post":{"tags":["control"],"summary":"Create a module\nPOST /api/v1/modules","operationId":"create_module","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateModuleRequest"}}},"required":true},"responses":{"200":{"description":"Create a module","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateModuleResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/modules/import":{"post":{"tags":["control"],"summary":"Import a module\nPOST /api/v1/modules/import","operationId":"import_module","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportModuleRequest"}}},"required":true},"responses":{"200":{"description":"Import a module","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportModuleResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/modules/resolve":{"post":{"tags":["control"],"summary":"Resolve qualified symbol name\nPOST /api/v1/modules/resolve","operationId":"resolve_symbol","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveSymbolRequest"}}},"required":true},"responses":{"200":{"description":"Resolve qualified symbol","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveSymbolResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/modules/symbols":{"post":{"tags":["control"],"summary":"Add symbol to module\nPOST /api/v1/modules/:name/symbols","operationId":"add_symbol","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddSymbolRequest"}}},"required":true},"responses":{"200":{"description":"Add symbol to module","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddSymbolResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/modules/symbols/list":{"post":{"tags":["control"],"summary":"List module symbols\nPOST /api/v1/modules/:name/symbols/list","operationId":"list_symbols","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListSymbolsRequest"}}},"required":true},"responses":{"200":{"description":"List module symbols","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListSymbolsResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/namespaces":{"post":{"tags":["namespaces"],"summary":"Create a root namespace","description":"# Authorization\nRequires X-Tenant-Id header. The tenant_id field in the request body is ignored.","operationId":"create_root_namespace","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRootNamespaceRequest"}}},"required":true},"responses":{"201":{"description":"Create a root namespace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NamespaceResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/namespaces/child":{"post":{"tags":["namespaces"],"summary":"Create a child namespace","description":"# Authorization\nRequires X-Tenant-Id header. The tenant_id field in the request body is ignored.","operationId":"create_child_namespace","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateChildNamespaceRequest"}}},"required":true},"responses":{"201":{"description":"Create a child namespace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NamespaceResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/namespaces/path/{tenant_id}/{path}":{"get":{"tags":["namespaces"],"summary":"Get a namespace by path","operationId":"get_namespace_by_path","parameters":[{"name":"tenant_id","in":"path","description":"Tenant ID","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"path","in":"path","description":"Namespace path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Get namespace by path","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NamespaceResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/namespaces/tenant/{tenant_id}":{"get":{"tags":["namespaces"],"summary":"List all namespaces for a tenant","operationId":"list_namespaces","parameters":[{"name":"tenant_id","in":"path","description":"Tenant ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"List all namespaces","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NamespaceListResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/namespaces/{id}":{"get":{"tags":["namespaces"],"summary":"Get a namespace by ID","operationId":"get_namespace","parameters":[{"name":"id","in":"path","description":"Namespace ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Get a namespace by ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NamespaceResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]},"delete":{"tags":["namespaces"],"summary":"Delete a namespace","operationId":"delete_namespace","parameters":[{"name":"id","in":"path","description":"Namespace ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Delete a namespace"},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/namespaces/{id}/ancestors":{"get":{"tags":["namespaces"],"summary":"Get ancestors of a namespace (from root to parent)","operationId":"get_namespace_ancestors","parameters":[{"name":"id","in":"path","description":"Namespace ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Get ancestors of namespace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NamespaceListResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/namespaces/{id}/children":{"get":{"tags":["namespaces"],"summary":"Get children of a namespace","operationId":"get_namespace_children","parameters":[{"name":"id","in":"path","description":"Namespace ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Get children of namespace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NamespaceListResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/namespaces/{id}/exports":{"post":{"tags":["namespaces"],"summary":"Add an export to a namespace","operationId":"add_namespace_export","parameters":[{"name":"id","in":"path","description":"Namespace ID","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddExportRequest"}}},"required":true},"responses":{"200":{"description":"Add namespace export"},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/namespaces/{id}/imports":{"post":{"tags":["namespaces"],"summary":"Add an import to a namespace","operationId":"add_namespace_import","parameters":[{"name":"id","in":"path","description":"Namespace ID","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddImportRequest"}}},"required":true},"responses":{"200":{"description":"Add namespace import"},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/namespaces/{id}/metadata":{"put":{"tags":["namespaces"],"summary":"Update namespace metadata","operationId":"update_namespace_metadata","parameters":[{"name":"id","in":"path","description":"Namespace ID","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMetadataRequest"}}},"required":true},"responses":{"200":{"description":"Update namespace metadata"},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/namespaces/{id}/visibility":{"put":{"tags":["namespaces"],"summary":"Update namespace visibility","operationId":"update_namespace_visibility","parameters":[{"name":"id","in":"path","description":"Namespace ID","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateVisibilityRequest"}}},"required":true},"responses":{"200":{"description":"Update namespace visibility"},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/nl/query":{"post":{"tags":["query"],"summary":"Handle natural language query","description":"Supports two modes:\n- \"llm\" (default): Uses LLM prompt engineering (Anthropic/local)\n- \"constraint\": Uses fine-tuned FunctionGemma constraint model\n\nBoth modes translate NL → constraints → execution → results","operationId":"nl_query","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NlQueryRequest"}}},"required":true},"responses":{"200":{"description":"NL query result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NlQueryResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/ontology/bindings":{"get":{"tags":["ontology_bridge"],"summary":"List all sort-table bindings.","description":"Returns all active bindings between OSF sorts and SQL tables.","operationId":"list_bindings","responses":{"200":{"description":"List of bindings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListBindingsResponse"}}}}},"security":[{"tenant_id":[]}]},"post":{"tags":["ontology_bridge"],"summary":"Bind a sort to a SQL table with explicit column mappings.","description":"Creates a mapping between an OSF sort and a SQL table, enabling\nOSFQL-to-SQL transpilation for that sort.","operationId":"bind_sort","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BindSortRequest"}}},"required":true},"responses":{"201":{"description":"Sort bound to table","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BindSortResponse"}}}},"400":{"description":"Invalid binding configuration"},"404":{"description":"Sort not found"}},"security":[{"tenant_id":[]}]}},"/api/v1/ontology/bindings/{sort_name}":{"delete":{"tags":["ontology_bridge"],"summary":"Remove a sort-table binding.","description":"Unbinds a sort from its SQL table, disabling SQL transpilation for it.","operationId":"unbind_sort","parameters":[{"name":"sort_name","in":"path","description":"Sort name to unbind","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Binding removed"},"404":{"description":"Sort not found"}},"security":[{"tenant_id":[]}]}},"/api/v1/ontology/generate":{"post":{"tags":["ontology"],"summary":"Generate an OSFKB scenario from a natural language task description.","description":"# Errors\n- 503 if no LLM is configured\n- 422 if the LLM returns invalid JSON after retries\n- 502 if the LLM service fails","operationId":"generate","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateOntologyRequest"}}},"required":true},"responses":{"200":{"description":"Ontology generation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateOntologyResponse"}}}},"422":{"description":"LLM returned invalid JSON"},"502":{"description":"LLM service failure"},"503":{"description":"No LLM provider configured"}},"security":[{"tenant_id":[]}]}},"/api/v1/ontology/grounded-schema":{"get":{"tags":["ontology_bridge"],"summary":"Generate ontology-grounded NL tool schemas.","description":"Produces query tools, write tools, and inference tools from the\ncurrent sort hierarchy and SQL bindings, along with a system prompt\nsuitable for grounding an LLM.","operationId":"grounded_schema","responses":{"200":{"description":"Grounded schema generated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroundedSchemaResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/ontology/import":{"post":{"tags":["ontology_bridge"],"summary":"Import an OWL/RDF ontology into the sort hierarchy.","description":"Parses the OWL XML, converts classes to sorts, and registers them.\nReturns the created sort names and discovered relations.","operationId":"import_owl","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportOwlRequest"}}},"required":true},"responses":{"201":{"description":"OWL ontology imported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportOwlResponse"}}}},"400":{"description":"Invalid OWL content"}},"security":[{"tenant_id":[]}]}},"/api/v1/ontology/transpile":{"post":{"tags":["ontology_bridge"],"summary":"Transpile an OSFQL query to SQL.","description":"Parses the OSFQL query, compiles it, and transpiles the first\n`ScanBySort` operation to SQL using the current sort-table bindings.","operationId":"transpile","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranspileRequest"}}},"required":true},"responses":{"200":{"description":"SQL generated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TranspileResponse"}}}},"400":{"description":"Parse or compile error"},"422":{"description":"Query not transpilable"}},"security":[{"tenant_id":[]}]}},"/api/v1/osfql":{"post":{"tags":["osfql"],"summary":"Execute an OSFQL program.","description":"Parses, compiles, and executes an OSFQL program against the caller's\ntenant-isolated knowledge base. Supports all OSFQL statement types:\nMATCH, INSERT, RETRACT, DERIVE, UNIFY, AWAIT, COUNTERFACTUAL, CAUSES.\n\n# Examples\n\n```json\n{ \"query\": \"INSERT person(name: \\\"Alice\\\", age: 30);\" }\n```\n\n```json\n{ \"query\": \"MATCH person(name: ?N, age: ?A) WHERE ?A > 18;\" }\n```","operationId":"execute_osfql","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OsfqlRequest"}}},"required":true},"responses":{"200":{"description":"Execution succeeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OsfqlResponse"}}}},"400":{"description":"Parse or compile error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OsfqlErrorResponse"}}}},"422":{"description":"Execution error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OsfqlErrorResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/oversight/judge":{"post":{"tags":["oversight"],"summary":"POST /api/v1/oversight/judge","operationId":"judge_trajectory","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormalJudgeRequest"}}},"required":true},"responses":{"200":{"description":"Oversight verification result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormalJudgeResponse"}}}},"400":{"description":"Invalid request"},"500":{"description":"Internal server error"}}}},"/api/v1/oversight/judge/refine":{"post":{"tags":["oversight"],"summary":"POST /api/v1/oversight/judge/refine","description":"Iterative refinement pipeline (paper §4.5). Performs multiple rounds\nof judgment, feeding fix suggestions back as additional constraints.","operationId":"judge_with_refinement","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormalJudgeRequest"}}},"required":true},"responses":{"200":{"description":"Iterative refinement result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormalJudgeRefinementResponse"}}}},"400":{"description":"Invalid request"},"500":{"description":"Internal server error"}}}},"/api/v1/oversight/sessions":{"post":{"tags":["oversight"],"summary":"POST /api/v1/oversight/sessions","description":"Create a new live oversight session.","operationId":"create_session","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSessionRequest"}}},"required":true},"responses":{"201":{"description":"Session created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSessionResponse"}}}},"400":{"description":"Invalid request"},"500":{"description":"Internal server error"}}}},"/api/v1/oversight/sessions/{session_id}/finalize":{"post":{"tags":["oversight"],"summary":"POST /api/v1/oversight/sessions/:session_id/finalize","description":"Finalize a live oversight session, running full verification and returning the final verdict.","operationId":"finalize_session","parameters":[{"name":"session_id","in":"path","description":"Session ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinalizeSessionRequest"}}},"required":true},"responses":{"200":{"description":"Session finalized with full verdict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FormalJudgeResponse"}}}},"404":{"description":"Session not found"},"409":{"description":"Session not active"},"500":{"description":"Internal server error"}}}},"/api/v1/oversight/sessions/{session_id}/status":{"get":{"tags":["oversight"],"summary":"GET /api/v1/oversight/sessions/:session_id/status","description":"Get the current status of a live oversight session.","operationId":"get_session_status","parameters":[{"name":"session_id","in":"path","description":"Session ID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Session status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionStatusResponse"}}}},"404":{"description":"Session not found"}}}},"/api/v1/oversight/sessions/{session_id}/steps":{"post":{"tags":["oversight"],"summary":"POST /api/v1/oversight/sessions/:session_id/steps","description":"Ingest a single trajectory step and return incremental verification result.","operationId":"ingest_step","parameters":[{"name":"session_id","in":"path","description":"Session ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestStepRequest"}}},"required":true},"responses":{"200":{"description":"Step verified","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StepVerificationResponse"}}}},"404":{"description":"Session not found"},"409":{"description":"Session not active"},"500":{"description":"Internal server error"}}}},"/api/v1/preferences":{"get":{"tags":["preferences"],"summary":"GET /api/v1/preferences","description":"Get all learned UI preferences for the authenticated user.","operationId":"list_preferences","responses":{"200":{"description":"User preferences","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListPreferencesResponseDto"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/preferences/predict":{"post":{"tags":["preferences"],"summary":"Predict preference scores for candidate terms using Bayesian inference","description":"POST /api/v1/preferences/predict\n\nReturns candidates ranked by how well they match the user's learned preferences.\nUses Gaussian likelihood for numeric features and frequency for categorical features.","operationId":"predict_preferences","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PredictPreferencesRequest"}}},"required":true},"responses":{"200":{"description":"Preference predictions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PredictPreferencesResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/preferences/selection":{"post":{"tags":["preferences"],"summary":"Record a user selection for preference learning","description":"POST /api/v1/preferences/selection\n\nUpdates the user's preference profile by learning from the selected term.\nIf no profile exists for this (user, tenant, sort), creates a new one.","operationId":"record_selection","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordSelectionRequest"}}},"required":true},"responses":{"200":{"description":"Selection recorded successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordSelectionResponse"}}}},"404":{"description":"Term not found"}},"security":[{"tenant_id":[]}]}},"/api/v1/preferences/{key}":{"put":{"tags":["preferences"],"summary":"PUT /api/v1/preferences/:key","description":"Set or override a user preference.","operationId":"set_preference","parameters":[{"name":"key","in":"path","description":"Preference key","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetPreferenceRequestDto"}}},"required":true},"responses":{"200":{"description":"Preference set","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreferenceDto"}}}}},"security":[{"tenant_id":[]}]},"delete":{"tags":["preferences"],"summary":"DELETE /api/v1/preferences/:key","description":"Delete a user preference.","operationId":"delete_preference","parameters":[{"name":"key","in":"path","description":"Preference key","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Preference deleted"},"404":{"description":"Preference not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/proof-engine/eval":{"post":{"tags":["proof-engine"],"summary":"Evaluate a built-in function","operationId":"eval_builtin","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvalBuiltinRequest"}}},"required":true},"responses":{"200":{"description":"Evaluate a built-in function","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvalBuiltinResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/proof-engine/eval/functions":{"post":{"tags":["proof-engine"],"summary":"List available eval functions","operationId":"list_eval_functions","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListEvalFunctionsRequest"}}},"required":true},"responses":{"200":{"description":"List available eval functions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListEvalFunctionsResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/proof-engine/rule-store/sessions":{"post":{"tags":["proof-engine"],"summary":"Create a new rule store session","operationId":"create_rule_store_session","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRuleStoreRequest"}}},"required":true},"responses":{"200":{"description":"Create a new rule store session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RuleStoreResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/proof-engine/rule-store/sessions/{store_id}":{"get":{"tags":["proof-engine"],"summary":"Get rule store status","operationId":"get_rule_store_session","parameters":[{"name":"store_id","in":"path","description":"Rule store session ID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Get rule store status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RuleStoreResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/proof-engine/rule-store/sessions/{store_id}/assert":{"post":{"tags":["proof-engine"],"summary":"Assert a rule","operationId":"assert_rule","parameters":[{"name":"store_id","in":"path","description":"Rule store session ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssertRuleRequest"}}},"required":true},"responses":{"200":{"description":"Assert a rule","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssertRuleResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/proof-engine/rule-store/sessions/{store_id}/find":{"post":{"tags":["proof-engine"],"summary":"Find matching rules","operationId":"find_rules","parameters":[{"name":"store_id","in":"path","description":"Rule store session ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindRulesRequest"}}},"required":true},"responses":{"200":{"description":"Find matching rules","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindRulesResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/proof-engine/rule-store/sessions/{store_id}/mark":{"post":{"tags":["proof-engine"],"summary":"Mark a rule store checkpoint","operationId":"mark_rule_store","parameters":[{"name":"store_id","in":"path","description":"Rule store session ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkRuleStoreRequest"}}},"required":true},"responses":{"200":{"description":"Mark a rule store checkpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkRuleStoreResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/proof-engine/rule-store/sessions/{store_id}/retract":{"post":{"tags":["proof-engine"],"summary":"Retract rules by ID or pattern.","description":"TRUE HOMOICONICITY: Uses TermStore's RuleIndex with trail support for backtracking.","operationId":"retract_rule","parameters":[{"name":"store_id","in":"path","description":"Rule store session ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetractRuleRequest"}}},"required":true},"responses":{"200":{"description":"Retract rules","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetractRuleResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/proof-engine/rule-store/sessions/{store_id}/undo":{"post":{"tags":["proof-engine"],"summary":"Undo to a rule store checkpoint","operationId":"undo_rule_store","parameters":[{"name":"store_id","in":"path","description":"Rule store session ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UndoRuleStoreRequest"}}},"required":true},"responses":{"200":{"description":"Undo to a rule store checkpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UndoRuleStoreResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/proof-engine/term-store/sessions":{"post":{"tags":["proof-engine"],"summary":"Create a new term store session","operationId":"create_term_store_session","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTermStoreRequest"}}},"required":true},"responses":{"200":{"description":"Create a new term store session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TermStoreSessionResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/proof-engine/term-store/sessions/{session_id}":{"get":{"tags":["proof-engine"],"summary":"Get term store session status","operationId":"get_term_store_session","parameters":[{"name":"session_id","in":"path","description":"Term store session ID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Get term store session status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TermStoreSessionResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/proof-engine/term-store/sessions/{session_id}/backtrack":{"post":{"tags":["proof-engine"],"summary":"Backtrack to a marker","operationId":"backtrack_term_store","parameters":[{"name":"session_id","in":"path","description":"Term store session ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BacktrackTermStoreRequest"}}},"required":true},"responses":{"200":{"description":"Backtrack to a marker","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BacktrackTermStoreResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/proof-engine/term-store/sessions/{session_id}/bind":{"post":{"tags":["proof-engine"],"summary":"Bind a variable to a term","operationId":"bind_store_variable","parameters":[{"name":"session_id","in":"path","description":"Term store session ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BindVariableRequest"}}},"required":true},"responses":{"200":{"description":"Bind a variable to a term","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BindVariableResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/proof-engine/term-store/sessions/{session_id}/dereference":{"post":{"tags":["proof-engine"],"summary":"Dereference a term","operationId":"dereference_store_term","parameters":[{"name":"session_id","in":"path","description":"Term store session ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DereferenceRequest"}}},"required":true},"responses":{"200":{"description":"Dereference a term","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DereferenceResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/proof-engine/term-store/sessions/{session_id}/features":{"post":{"tags":["proof-engine"],"summary":"Set a feature on a term","operationId":"set_store_feature","parameters":[{"name":"session_id","in":"path","description":"Term store session ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetFeatureRequest"}}},"required":true},"responses":{"200":{"description":"Set a feature on a term","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetFeatureResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/proof-engine/term-store/sessions/{session_id}/mark":{"post":{"tags":["proof-engine"],"summary":"Mark a choice point","operationId":"mark_term_store","parameters":[{"name":"session_id","in":"path","description":"Term store session ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkTermStoreRequest"}}},"required":true},"responses":{"200":{"description":"Mark a choice point","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkTermStoreResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/proof-engine/term-store/sessions/{session_id}/terms":{"post":{"tags":["proof-engine"],"summary":"Create a term in the term store","operationId":"create_store_term","parameters":[{"name":"session_id","in":"path","description":"Term store session ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateStoreTermRequest"}}},"required":true},"responses":{"200":{"description":"Create a term in the store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTermResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/proof-engine/term-store/sessions/{session_id}/terms/get":{"post":{"tags":["proof-engine"],"summary":"Get term details","operationId":"get_store_term","parameters":[{"name":"session_id","in":"path","description":"Term store session ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetStoreTermRequest"}}},"required":true},"responses":{"200":{"description":"Get term details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetStoreTermResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/proof-engine/term-store/sessions/{session_id}/unify":{"post":{"tags":["proof-engine"],"summary":"Unify two terms","operationId":"unify_store_terms","parameters":[{"name":"session_id","in":"path","description":"Term store session ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnifyTermsRequest"}}},"required":true},"responses":{"200":{"description":"Unify two terms","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnifyTermsResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/proof-engine/term-store/sessions/{session_id}/variables":{"post":{"tags":["proof-engine"],"summary":"Create a variable in the term store","operationId":"create_store_variable","parameters":[{"name":"session_id","in":"path","description":"Term store session ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateVariableRequest"}}},"required":true},"responses":{"200":{"description":"Create a variable in the store","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTermResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/query/by-sort":{"post":{"tags":["query"],"summary":"Find terms by sort (polymorphic query)","description":"Returns all terms with the specified sort OR any of its subtypes.\nThis implements proper OSF polymorphic query semantics where querying\na parent sort returns all instances of that sort and its descendants.","operationId":"find_by_sort","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindBySortRequest"}}},"required":true},"responses":{"200":{"description":"Terms by sort","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TermListResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/query/osf-search":{"post":{"tags":["query"],"summary":"Pure OSF Search","description":"POST /api/v1/query/osf-search\n\nPerforms structured search using only OSF operations (no LLM).\nReturns matched entities with provenance, discovered relations,\nand any query incompleteness information.\n\n**Key differentiators from other search endpoints:**\n- `/api/v1/query/by-sort` - Returns terms, but no relation discovery\n- `/api/v1/fuzzy/similar` - Returns similarity scores, but no relation discovery\n- `/api/v1/communities/search` - Requires pre-detected communities\n\n**This endpoint provides:**\n- Automatic relation discovery between matched entities\n- Residuation for incomplete queries (tells you what's missing)\n- Structured results with full provenance\n- Namespace and collection filtering","operationId":"osf_search","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OsfSearchRequest"}}},"required":true},"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OsfSearchResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/query/unifiable":{"post":{"tags":["query"],"summary":"Find unifiable terms","operationId":"find_unifiable","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnificationQueryRequest"}}},"required":true},"responses":{"200":{"description":"Unifiable terms","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnificationQueryResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/query/validate-term":{"post":{"tags":["query"],"summary":"Validate a term against its sort's witnesses","description":"This endpoint implements Hassan Aït-Kaci's vision where \"types ARE constraints\".\nWhen you create a term of a sort, this validates that the term satisfies\nthe sort's existential witnesses (compiled from rules).\n\n## How It Differs from Regular Term Creation\n\n**Regular `/api/v1/terms` (POST)**:\n- Just stores the term\n- No validation against type constraints\n- Fast but permissive\n\n**This endpoint `/api/v1/query/validate-term` (POST)**:\n- Validates term against sort's witnesses\n- Returns proof that term is legitimate\n- Slower but type-safe\n\n## Example\n\nGiven rule: `grandparent(X,Z) :- parent(X,Y), parent(Y,Z)`\n\nCreating `grandparent(person => alice, grandchild => charlie)`:\n- Checks: ∃Y such that parent(alice, Y) ∧ parent(Y, charlie)\n- If found (e.g., Y=bob): Returns valid=true with witness proof\n- If not found: Returns valid=false with explanation\n\nUses HomoiconicWitnessFinder for pure homoiconic witness validation.","operationId":"validate_term","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidatedTermRequest"}}},"required":true},"responses":{"200":{"description":"Validation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidatedTermResponse"}}}},"400":{"description":"Invalid request"}},"security":[{"tenant_id":[]}]}},"/api/v1/query/validated-unify":{"post":{"tags":["query"],"summary":"Unify two terms with witness validation","description":"This performs unification AND validates the result against the GLB sort's witnesses.\n\n## How It Differs from Regular Unification\n\n**Regular `/api/v1/term-store/sessions/:id/unify` (POST)**:\n- Computes GLB and unifies terms\n- Validates sort constraints (required features, type hints)\n- Does NOT check witnesses\n\n**This endpoint `/api/v1/query/validated-unify` (POST)**:\n- Computes GLB and unifies terms\n- Validates sort constraints\n- ALSO checks witnesses on the result\n- Returns proof of validity\n\n## Example\n\nUnifying `person(name => \"Alice\")` with `grandparent(grandchild => \"Charlie\")`:\n1. Computes GLB of person and grandparent\n2. Creates unified term with both features\n3. Checks grandparent witnesses: ∃Y. parent(Alice,Y) ∧ parent(Y,Charlie)\n4. Returns unified term + witness proof\n\n","operationId":"validated_unify","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidatedUnifyRequest"}}},"required":true},"responses":{"200":{"description":"Unification result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidatedUnifyResponse"}}}},"400":{"description":"Invalid request"}},"security":[{"tenant_id":[]}]}},"/api/v1/rag/ontology":{"post":{"tags":["rag"],"summary":"Generic Ontology RAG endpoint","description":"POST /api/v1/rag/ontology\n\nPerforms True Ontology RAG combining embedding search with OSF/LIFE feature unification:\n1. Embedding search - find matching Ψ-terms via multilingual embeddings\n2. Feature unification - navigate prerequisites/dependents via Ψ-term features\n3. Emergent discovery - find relations via fuzzy feature unification\n\nThis is a domain-agnostic API. The caller provides:\n- Feature names via `feature_config` (e.g., \"requires\", \"depends_on\")\n- Optional concept values and threshold for flagging (e.g., mastery scores)\n\nThe caller is responsible for interpreting the results (coaching, medical, etc.)","operationId":"ontology_rag","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OntologyRagRequestDto"}}},"required":true},"responses":{"200":{"description":"Ontology RAG results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OntologyRagResponseDto"}}}},"400":{"description":"Invalid request"},"500":{"description":"Internal error"}},"security":[{"tenant_id":[]}]}},"/api/v1/reasoning/assess":{"post":{"tags":["reasoning"],"summary":"Generic evidence-based assessment","description":"POST /api/v1/reasoning/assess\n\nComputes truthfulness/validity of a subject based on related evidence.\nUses fuzzy T-norm aggregation and residuation for insufficient evidence.\n\nThis is GENERIC and works for any domain:\n- Health claims with medical evidence\n- News articles with fact-check sources\n- Scientific hypotheses with experimental data\n- Any subject-evidence relationship\n\n# Algorithm\n1. Query all evidence terms linked to the subject\n2. Separate into supporting vs contradicting evidence\n3. Check residuation: if max evidence quality < threshold, suspend judgment\n4. Compute T-norm aggregation of evidence contributions\n5. Apply optional penalty (e.g., manipulation signals)\n6. Return truthfulness score with label","operationId":"evidence_assessment","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvidenceAssessmentRequest"}}},"required":true},"responses":{"200":{"description":"Evidence assessed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvidenceAssessmentResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/reasoning/disentailment":{"post":{"tags":["reasoning"],"summary":"Check disentailment between two clauses","description":"POST /api/v1/reasoning/disentailment\n\nDisentailment A =/=> B means: \"if A holds, then B must NOT hold\"\nReturns whether the disentailment is violated (conflict: both A and B hold)","operationId":"disentailment","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisentailmentRequest"}}},"required":true},"responses":{"200":{"description":"Disentailment result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisentailmentResponse"}}}}}}},"/api/v1/reasoning/entailment":{"post":{"tags":["reasoning"],"summary":"Check entailment between clauses","description":"POST /api/v1/reasoning/entailment\n\nReturns whether antecedent entails consequent","operationId":"entailment","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntailmentRequest"}}},"required":true},"responses":{"200":{"description":"Entailment result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EntailmentResponse"}}}}}}},"/api/v1/reasoning/goal-residuation":{"post":{"tags":["reasoning"],"summary":"Compute goal-level residuation: which antecedent sorts are still needed?","description":"POST /api/v1/reasoning/goal-residuation\n\nGiven a goal sort name and the sorts already available as evidence,\nanalyses the rule base to find which antecedent sorts are missing.\nReturns entries sorted by information gain (most useful evidence first).","operationId":"goal_residuation","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoalResiduationRequest"}}},"required":true},"responses":{"200":{"description":"Goal residuation analysis","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GoalResiduationResponse"}}}},"400":{"description":"Invalid request"}},"security":[{"tenant_id":[]}]}},"/api/v1/reasoning/merge":{"post":{"tags":["reasoning"],"summary":"Merge two terms using fuzzy merging","description":"POST /api/v1/reasoning/merge\n\nCombines two terms by merging their features with fuzzy accumulation","operationId":"fuzzy_merge","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuzzyMergeRequest"}}},"required":true},"responses":{"200":{"description":"Merge result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuzzyMergeResponse"}}}}}}},"/api/v1/reasoning/residuate":{"post":{"tags":["reasoning"],"summary":"Check residuation status","description":"POST /api/v1/reasoning/residuate\n\nReturns suspended operations and resumption triggers","operationId":"residuation","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResiduationRequest"}}},"required":true},"responses":{"200":{"description":"Residuation status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResiduationResponse"}}}}}}},"/api/v1/reasoning/resource-coordination":{"post":{"tags":["reasoning"],"summary":"Resource coordination planning endpoint (generic multi-resource pairing)","description":"POST /api/v1/reasoning/resource-coordination\n\n**CURRENT STATUS**: This endpoint currently only supports 2-way pairwise coordination.\n**TODO**: Migrate to N-way coordination as defined in the updated DTOs.\n\nThis is a GENERIC endpoint that works for ANY pairing scenario:\n- Meals + Wines (food service)\n- Tasks + Tools (project management)\n- Outfits + Occasions (fashion)\n- etc.\n\nThe system knows nothing about wine or meals - it's purely generic.\n\n**Migration needed**:\n1. Update to accept `resources: Vec<ResourceSpec>` instead of primary/secondary\n2. Implement N-way compatibility algorithm in domain layer\n3. Update service layer to handle N resources\n4. Return `CoordinatedResourceSet` instead of `PairedResourceDto`\n5. See RESOURCE_COORDINATION_EXAMPLES.md for target API design","operationId":"resource_coordination","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResourceCoordinationRequest"}}},"required":true},"responses":{"200":{"description":"Resources coordinated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResourceCoordinationResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/reasoning/subsumption":{"post":{"tags":["reasoning"],"summary":"Check fuzzy subsumption between two terms","description":"POST /api/v1/reasoning/subsumption\n\nReturns a degree μ ∈ [0,1] indicating how well specific is subsumed by general","operationId":"fuzzy_subsumption","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuzzySubsumptionRequest"}}},"required":true},"responses":{"200":{"description":"Subsumption check result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FuzzySubsumptionResponse"}}}}}}},"/api/v1/reasoning/temporal-plan":{"post":{"tags":["reasoning"],"summary":"Plan selections with diversity constraints (Temporal Planning)","description":"POST /api/v1/reasoning/temporal-plan\n\nCreates a temporal plan by selecting N terms from a sort while ensuring\ndiversity according to specified constraints. This is useful for:\n- Weekly meal planning (7 recipes, no repeating cuisines)\n- Event scheduling (avoid conflicts)\n- Resource allocation with diversity requirements\n\n# Example Request\n```json\n{\n \"tenant_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"sort_id\": \"recipe-sort-uuid\",\n \"num_selections\": 7,\n \"no_repeat_fields\": [\"cuisine\"]\n}\n```\n\n# Example Response\n```json\n{\n \"selected_term_ids\": [\"term1-uuid\", \"term2-uuid\", ...],\n \"diversity_score\": 0.95,\n \"candidates_count\": 150,\n \"computation_time_ms\": 42\n}\n```","operationId":"temporal_plan","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemporalPlanRequest"}}},"required":true},"responses":{"200":{"description":"Temporal plan generated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemporalPlanResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/reviews/add":{"post":{"tags":["reviews"],"summary":"Add a new pending review (internal API, called from ingestion pipeline)","description":"POST /api/v1/reviews/add","operationId":"add_pending_review","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddPendingReviewRequest"}}},"required":true},"responses":{"201":{"description":"Add a pending review","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddPendingReviewResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/reviews/approve":{"post":{"tags":["reviews"],"summary":"Approve an entity as-is","description":"POST /api/v1/reviews/approve\n\nCreates a term from the approved entity.","operationId":"approve_entity","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApproveEntityRequest"}}},"required":true},"responses":{"200":{"description":"Approve an entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewActionResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/reviews/bulk-approve":{"post":{"tags":["reviews"],"summary":"Bulk approve multiple reviews","description":"POST /api/v1/reviews/bulk-approve\n\nApproves multiple reviews in a single transaction.","operationId":"bulk_approve","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkApproveRequest"}}},"required":true},"responses":{"200":{"description":"Bulk approve reviews","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkReviewResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/reviews/bulk-merge":{"post":{"tags":["reviews"],"summary":"Bulk merge multiple reviews into a single target term","description":"POST /api/v1/reviews/bulk-merge\n\nMerges multiple reviews into a single existing term.","operationId":"bulk_merge","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkMergeRequest"}}},"required":true},"responses":{"200":{"description":"Bulk merge reviews","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkReviewResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/reviews/bulk-reject":{"post":{"tags":["reviews"],"summary":"Bulk reject multiple reviews","description":"POST /api/v1/reviews/bulk-reject\n\nRejects multiple reviews in a single transaction.","operationId":"bulk_reject","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkRejectRequest"}}},"required":true},"responses":{"200":{"description":"Bulk reject reviews","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkReviewResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/reviews/correct":{"post":{"tags":["reviews"],"summary":"Correct an entity before approval","description":"POST /api/v1/reviews/correct\n\nAllows correcting the sort and/or features before creating the term.","operationId":"correct_entity","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CorrectEntityRequest"}}},"required":true},"responses":{"200":{"description":"Correct entity before approval","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewActionResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/reviews/merge":{"post":{"tags":["reviews"],"summary":"Merge entity with an existing term","description":"POST /api/v1/reviews/merge\n\nMerges the entity's features into an existing term.","operationId":"merge_entity","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MergeEntityRequest"}}},"required":true},"responses":{"200":{"description":"Merge entity with existing term","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewActionResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/reviews/pending":{"get":{"tags":["reviews"],"summary":"List pending reviews for a tenant","description":"GET /api/v1/reviews/pending\n\nReturns paginated list of entities requiring human review.","operationId":"list_pending_reviews","responses":{"200":{"description":"List pending reviews","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListPendingReviewsResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/reviews/re-extract":{"post":{"tags":["reviews"],"summary":"Re-extract entities from a document","description":"POST /api/v1/reviews/re-extract\n\nTriggers re-extraction with potentially different parameters.","operationId":"re_extract","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReExtractRequest"}}},"required":true},"responses":{"200":{"description":"Re-extract entities","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReExtractResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/reviews/reject":{"post":{"tags":["reviews"],"summary":"Reject an entity","description":"POST /api/v1/reviews/reject\n\nMarks the entity as rejected (will be discarded).","operationId":"reject_entity","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectEntityRequest"}}},"required":true},"responses":{"200":{"description":"Reject an entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewActionResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/reviews/summary/{tenant_id}":{"get":{"tags":["reviews"],"summary":"Get review summary statistics","description":"GET /api/v1/reviews/summary/:tenant_id","operationId":"get_review_summary","parameters":[{"name":"tenant_id","in":"path","description":"Tenant ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Get review summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewSummaryDto"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/rl/train":{"post":{"tags":["rl-training"],"summary":"Start an RL training run.","description":"## Modes\n\n- **Standalone** (`enable_cognitive_cycle: false`): Uses `environment_orchestrator::run()`\n for pure RL training (no cognitive cycle overhead).\n- **Cognitive** (`enable_cognitive_cycle: true`): Uses `rl_cognitive_bridge::run()`\n for unified cognitive-RL training where the cognitive engine influences exploration\n and the RL loop feeds back into cognitive learning.\n\n## Example\n\n```bash\ncurl -X POST http://localhost:3000/api/v1/rl/train \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"tenant_id\": \"...\",\n \"environment_name\": \"grid_world_5x5\",\n \"num_episodes\": 100,\n \"enable_cognitive_cycle\": true\n }'\n```","operationId":"train_rl","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RlTrainRequest"}}},"required":true},"responses":{"200":{"description":"Training completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RlTrainResponse"}}}},"400":{"description":"Invalid request (unknown environment, bounds exceeded)"},"500":{"description":"Internal error"}}}},"/api/v1/row/integrate":{"post":{"tags":["row-polymorphism"],"summary":"Feature-based data integration","description":"Find groups of entities that share common feature values (potential duplicates\nor related entities across different schemas/sources).\n\n## Example Use Case: Cross-Source Entity Matching\n\nFind entities that have the same \"email\" and \"name\" across different data sources:\n\n```json\n{\n \"match_features\": [\"email\", \"name\"],\n \"min_similarity\": 0.9,\n \"source_namespaces\": [\"crm_data\", \"marketing_data\", \"support_data\"]\n}\n```","operationId":"row_integrate","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RowIntegrateRequest"}}},"required":true},"responses":{"200":{"description":"Integration groups","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RowIntegrateResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/row/query":{"post":{"tags":["row-polymorphism"],"summary":"Dynamic query building","description":"Execute pattern-based queries with support for exact matching, type checking,\ncomparisons, regex, and variable bindings.\n\n## Example Use Case: Complex Filtered Queries\n\nFind all products where price > 100 and category contains \"electronics\":\n\n```json\n{\n \"clauses\": [\n {\"feature\": \"price\", \"pattern\": {\"type\": \"greater_than\", \"value\": 100}},\n {\"feature\": \"category\", \"pattern\": {\"type\": \"contains\", \"substring\": \"electronics\"}}\n ],\n \"project\": [\"name\", \"price\", \"category\"],\n \"sort_by\": \"price\",\n \"descending\": true\n}\n```","operationId":"dynamic_query","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DynamicQueryRequest"}}},"required":true},"responses":{"200":{"description":"Query results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DynamicQueryResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/row/search":{"post":{"tags":["row-polymorphism"],"summary":"Schema-flexible entity search","description":"Find all entities matching a row pattern (feature requirements) regardless of sort.\nThis is \"structural typing\" for knowledge bases - query by structure, not by type.\n\n## Example Use Case: Multi-Domain Entity Discovery\n\nFind all entities with a \"name\" and \"location\" feature, whether they're\nPerson, Company, Building, Event, or any other sort:\n\n```json\n{\n \"pattern\": {\n \"features\": [\n {\"name\": \"name\", \"feature_type\": \"string\"},\n {\"name\": \"location\", \"feature_type\": \"string\"}\n ],\n \"open\": true\n }\n}\n```","operationId":"row_search","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RowSearchRequest"}}},"required":true},"responses":{"200":{"description":"Matching entities","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RowSearchResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/row/similarity":{"post":{"tags":["row-polymorphism"],"summary":"Compute row type similarity","description":"Calculate the similarity between two row types based on feature overlap.","operationId":"row_similarity","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RowSimilarityRequest"}}},"required":true},"responses":{"200":{"description":"Similarity result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RowSimilarityResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/row/unify":{"post":{"tags":["row-polymorphism"],"summary":"Compute row type unification","description":"Try to unify two row types and return the result.","operationId":"row_unify","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RowUnifyRequest"}}},"required":true},"responses":{"200":{"description":"Unification result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RowUnifyResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/scenarios":{"get":{"tags":["scenarios"],"summary":"List all scenarios for the current tenant","description":"Returns scenario summaries sorted by most recent first, including counts of materialized sorts, beliefs, and rules.","operationId":"list_scenarios","responses":{"200":{"description":"List of scenarios","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListScenariosResponse"}}}}},"security":[{"tenant_id":[]}]},"post":{"tags":["scenarios"],"summary":"Generate and materialize a scenario from natural language","description":"Generates an OSFKB scenario from a natural language task description using an LLM, then materializes it into the knowledge base (sorts, beliefs, rules, goals, webhook actions, tools, curriculum, groundings). Supports multi-turn clarification.","operationId":"create_scenario","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateScenarioRequest"}}},"required":true},"responses":{"200":{"description":"Scenario created or clarification needed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateScenarioResponse"}}}},"422":{"description":"Validation failed"},"500":{"description":"Materialization failed"},"503":{"description":"No LLM provider configured"}},"security":[{"tenant_id":[]}]}},"/api/v1/scenarios/{scenario_id}":{"get":{"tags":["scenarios"],"summary":"Retrieve a scenario by ID","description":"Returns the full scenario definition and materialization metadata for a previously created scenario, looked up from the tenant's Psi-term store.","operationId":"get_scenario","parameters":[{"name":"scenario_id","in":"path","description":"Scenario ID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Scenario found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetScenarioResponse"}}}},"404":{"description":"Scenario not found"}},"security":[{"tenant_id":[]}]},"patch":{"tags":["scenarios"],"summary":"Incrementally update a scenario","description":"Adds new sorts, beliefs, rules, constraints, guard constraints, temporal constraints, and/or webhook actions to an existing scenario without re-creating everything from scratch.","operationId":"update_scenario","parameters":[{"name":"scenario_id","in":"path","description":"Scenario ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateScenarioRequest"}}},"required":true},"responses":{"200":{"description":"Scenario updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateScenarioResponse"}}}},"404":{"description":"Scenario not found"},"500":{"description":"Materialization of new items failed"}},"security":[{"tenant_id":[]}]}},"/api/v1/scenarios/{scenario_id}/verify":{"post":{"tags":["scenarios"],"summary":"Verify a scenario with FormalJudge analysis","description":"Performs structural verification of materialization steps, then attempts FormalJudge semantic verification if an LLM is configured. Falls back gracefully to structural-only verification when the LLM is unavailable.","operationId":"verify_scenario","parameters":[{"name":"scenario_id","in":"path","description":"Scenario ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyScenarioRequest"}}},"required":true},"responses":{"200":{"description":"Verification result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyScenarioResponse"}}}},"404":{"description":"Scenario not found"},"500":{"description":"Verification failed internally"}},"security":[{"tenant_id":[]}]}},"/api/v1/scheduling/feasibility":{"post":{"tags":["scheduling"],"summary":"`POST /api/v1/scheduling/feasibility`","description":"Classify every `(agent, day, shift)` cell in the input grid as\nconfirmed-true, confirmed-false, or free, and list the role(s)\neach cell could cover.\n\nInput validation errors (duplicate agent IDs, out-of-range pins,\nrole minima exceeding total demand, pin role the agent doesn't\nhave, pin on a multi-role agent where the role is ambiguous, etc.)\nreturn HTTP 400.\n\nInfeasibility of a well-formed problem is a valid answer and\nreturns HTTP 200 with `status = \"infeasible\"` and an empty\n`assignments` list.","operationId":"feasibility","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingFeasibilityRequest"}}},"required":true},"responses":{"200":{"description":"Feasibility analysis succeeded (feasible or infeasible)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingFeasibilityResponse"}}}},"400":{"description":"Invalid input (duplicate IDs, out-of-range references, contradictory demand, ambiguous pin role, unknown pin role, etc.)"}}}},"/api/v1/scheduling/optimize":{"post":{"tags":["scheduling"],"summary":"`POST /api/v1/scheduling/optimize`","description":"Same hard constraints as `/scheduling/feasibility` plus a list of\nsoft `preferences` (each a per-cell score added to the\noptimizer's objective). Returns the per-cell trichotomy across\nthe space of **optimal** schedules, plus `total_score` (sum of\npreference scores at chosen cells in the optimum).\n\n`confirmed_true` / `confirmed_false` here are stronger than in\n`/feasibility`: they hold across every optimum, not every\nfeasible schedule. Cells with status `free` indicate ties —\nmultiple optima exist and the cell varies between them.\n\nPreferences targeting cells that are already pinned, blocked by\na day-off, restricted-to-shift, or otherwise structurally fixed\nare silently ignored — those cells are not the optimizer's\nchoice to make.","operationId":"optimize","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingOptimizeRequest"}}},"required":true},"responses":{"200":{"description":"Optimization succeeded (feasible or infeasible)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingOptimizeResponse"}}}},"400":{"description":"Invalid input (duplicate IDs, out-of-range references, contradictory demand, ambiguous pin role, unknown pin or preference agent ID, etc.)"}}}},"/api/v1/sorts":{"post":{"tags":["sorts"],"summary":"Add a new sort","description":"# Authorization\nRequires X-Tenant-Id header. The tenant_id field in the request body is ignored.","operationId":"add_sort","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSortRequest"}}},"required":true},"responses":{"201":{"description":"Sort created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SortResponse"}}}},"400":{"description":"Invalid request"}},"security":[{"tenant_id":[]}]}},"/api/v1/sorts/bulk":{"post":{"tags":["sorts"],"summary":"Create multiple sorts in bulk","description":"POST /api/v1/sorts/bulk\n\nCreates multiple sorts in a single request, automatically resolving\nparent references by name. Sorts are topologically sorted to ensure\nparents are created before children.\n\nThis is much faster than individual requests for large hierarchies.\n\n# Authorization\nRequires X-Tenant-Id header. The tenant_id field in the request body is ignored.","operationId":"bulk_create_sorts","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkCreateSortsRequest"}}},"required":true},"responses":{"200":{"description":"Sorts created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkCreateSortsResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/sorts/compare":{"post":{"tags":["types"],"summary":"Compare two sorts\nPOST /api/v1/sorts/compare","operationId":"compare_sorts","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SortCompareRequest"}}},"required":true},"responses":{"200":{"description":"Compare two sorts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SortCompareResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/sorts/compare/batch":{"post":{"tags":["types"],"summary":"Batch compare sorts\nPOST /api/v1/sorts/compare/batch","operationId":"batch_compare_sorts","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchSortCompareRequest"}}},"required":true},"responses":{"200":{"description":"Batch compare sorts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchSortCompareResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/sorts/equivalence-classes":{"get":{"tags":["sorts"],"summary":"Get equivalence classes based on the combined preorder","description":"Per Definition IV.9 (Milanese & Pasi 2024):\ns₁ ≈ s₂ ⇔ ≾̇(s₁, s₂) > 0 AND ≾̇(s₂, s₁) > 0","operationId":"get_equivalence_classes","responses":{"200":{"description":"Equivalence classes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetEquivalenceClassesResponse"}}}}}}},"/api/v1/sorts/glb":{"post":{"tags":["sorts"],"summary":"Compute GLB (Greatest Lower Bound) of two sorts","operationId":"compute_glb","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeGlbRequest"}}},"required":true},"responses":{"200":{"description":"GLB computed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeGlbResponse"}}}}}}},"/api/v1/sorts/glb/decode":{"post":{"tags":["sorts"],"summary":"Decode GLB (Greatest Lower Bound) of two sorts as type disjunction","description":"Computes the bit-vector intersection (GLB) and decodes it into\na human-readable type disjunction. This is Life1.0's decode() function.\n\n# Returns\n- `sort_ids`: List of sort IDs in the disjunction\n- `sort_names`: List of sort names in the disjunction\n- `formatted`: Human-readable format (e.g., \"int | real\")\n- `is_bottom`: True if the GLB is empty (incompatible sorts)","operationId":"decode_glb","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecodeGlbRequest"}}},"required":true},"responses":{"200":{"description":"GLB decoded as type disjunction","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecodeGlbResponse"}}}}}}},"/api/v1/sorts/greatest/{tenant_id}":{"get":{"tags":["types"],"summary":"Get greatest (most general) sorts\nGET /api/v1/sorts/greatest/:tenant_id","operationId":"get_greatest_sorts","parameters":[{"name":"tenant_id","in":"path","description":"Tenant ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Get most general sorts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GreatestSortsResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/sorts/index":{"post":{"tags":["sorts"],"operationId":"index_sorts","responses":{"200":{"description":"Sorts indexed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndexSortsResponse"}}}},"500":{"description":"Indexing failed"}},"security":[{"tenant_id":[]}]}},"/api/v1/sorts/learn-similarities":{"post":{"tags":["sorts"],"summary":"Learn sort similarities from behavioral data","description":"POST /api/v1/sorts/learn-similarities\n\nAnalyzes terms in the knowledge base to discover which sorts have similar\neffect distributions. This enables reasoning by analogy: if CF3 compounds\nand CHF2 compounds show similar potency distributions, they are likely\nbioisosteres that can be used interchangeably.\n\n# Request Body\n- `effect_feature`: Name of the numeric feature to analyze (e.g., \"potency\", \"ic50\")\n- `min_samples`: Minimum samples required per sort (default: 5)\n- `min_similarity`: Minimum similarity threshold (default: 0.5)\n\n# Response\n- `learned_count`: Number of sort pairs with learned similarity\n- `message`: Success message\n\n# Authorization\nRequires X-Tenant-Id header. The tenant_id field in the request body is ignored.","operationId":"learn_sort_similarities","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LearnSortSimilaritiesRequest"}}},"required":true},"responses":{"200":{"description":"Similarities learned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LearnSortSimilaritiesResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/sorts/learned-similarities":{"get":{"tags":["sorts"],"summary":"List learned similarities pending review","description":"GET /api/v1/sorts/learned-similarities\n\nReturns all learned similarities that need human review, including:\n- Proposed: New similarities learned from data\n- Conflicted: Learned values that differ from expert-defined values","operationId":"list_learned_similarities","responses":{"200":{"description":"List of learned similarities","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LearnedSimilarityListResponse"}}}}}}},"/api/v1/sorts/learned-similarities/approve":{"post":{"tags":["sorts"],"summary":"Approve a learned similarity","description":"POST /api/v1/sorts/learned-similarities/approve\n\nApproves a proposed or conflicted learned similarity. Once approved,\nthe similarity is added to the active similarity relation and will\nbe used in reasoning.","operationId":"approve_learned_similarity","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApproveLearnedSimilarityRequest"}}},"required":true},"responses":{"200":{"description":"Similarity approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApproveLearnedSimilarityResponse"}}}}}}},"/api/v1/sorts/learned-similarities/reject":{"post":{"tags":["sorts"],"summary":"Reject a learned similarity","description":"POST /api/v1/sorts/learned-similarities/reject\n\nRejects a proposed or conflicted learned similarity with a reason.\nRejected similarities are not used in reasoning.","operationId":"reject_learned_similarity","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectLearnedSimilarityRequest"}}},"required":true},"responses":{"200":{"description":"Similarity rejected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectLearnedSimilarityResponse"}}}}}}},"/api/v1/sorts/least/{tenant_id}":{"get":{"tags":["types"],"summary":"Get least (most specific) sorts\nGET /api/v1/sorts/least/:tenant_id","operationId":"get_least_sorts","parameters":[{"name":"tenant_id","in":"path","description":"Tenant ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Get least specific sorts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeastSortsResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/sorts/lub":{"post":{"tags":["sorts"],"summary":"Compute LUB (Least Upper Bound) of two sorts","operationId":"compute_lub","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeLubRequest"}}},"required":true},"responses":{"200":{"description":"LUB computed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComputeLubResponse"}}}}}}},"/api/v1/sorts/preorder-degree":{"post":{"tags":["sorts"],"summary":"Get preorder degree ≾̇(s₁, s₂) between two sorts","description":"Per Definition IV.5 (Milanese & Pasi 2024):\n≾̇ = ((≾̃ .− ∼) ⊍ ≤)⁺","operationId":"get_preorder_degree","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetPreorderDegreeRequest"}}},"required":true},"responses":{"200":{"description":"Preorder degree","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetPreorderDegreeResponse"}}}}}}},"/api/v1/sorts/similarity":{"post":{"tags":["sorts"],"summary":"Set similarity degree between two sorts","description":"Similarity is symmetric: ∼(s₁, s₂) = ∼(s₂, s₁)\nDegree must be in [0, 1] range.","operationId":"set_sort_similarity","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetSortSimilarityRequest"}}},"required":true},"responses":{"200":{"description":"Similarity set","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetSortSimilarityResponse"}}}}}}},"/api/v1/sorts/similarity/bulk":{"post":{"tags":["sorts"],"summary":"Set multiple sort similarities in bulk","description":"POST /api/v1/sorts/similarity/bulk\n\nSets multiple similarity relations in a single request using sort IDs.\nUses a single database persist for much faster performance.","operationId":"bulk_set_similarities","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkSetSimilaritiesRequest"}}},"required":true},"responses":{"200":{"description":"Similarities set","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkSetSimilaritiesResponse"}}}}}}},"/api/v1/sorts/similarity/get":{"post":{"tags":["sorts"],"summary":"Get direct similarity degree ∼(s₁, s₂) between two sorts","operationId":"get_sort_similarity","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetSortSimilarityRequest"}}},"required":true},"responses":{"200":{"description":"Sort similarity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetSortSimilarityResponse"}}}}}}},"/api/v1/sorts/tenant/{tenant_id}":{"get":{"tags":["sorts"],"summary":"List all sorts for a tenant with optional filtering","description":"By default, system-defined sorts (built-in types like Thing, Person, etc.)\nare excluded from the response. Use `include_system=true` to include them.","operationId":"list_sorts","parameters":[{"name":"tenant_id","in":"path","description":"Tenant ID","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"needs_review","in":"query","description":"Filter to only show sorts needing review","required":false,"schema":{"type":["boolean","null"]}},{"name":"llm_extracted","in":"query","description":"Filter to only show LLM-extracted sorts","required":false,"schema":{"type":["boolean","null"]}},{"name":"include_system","in":"query","description":"Include system-defined sorts in the response.\nSystem sorts are built-in types like Thing, Person, etc.\nDefaults to false (system sorts are excluded by default).","required":false,"schema":{"type":"boolean"}},{"name":"name_prefix","in":"query","description":"Filter to sorts whose name starts with this prefix.\nSupports comma-separated multiple prefixes (e.g. \"drug_,target_,pathway_,disease_\").\nServer-side filtering avoids transferring millions of irrelevant sorts.","required":false,"schema":{"type":["string","null"]}},{"name":"offset","in":"query","description":"Zero-indexed pagination offset. Combined with ``limit`` this\nlets clients stream a production tenant (1 M+ sorts, ~500 MB\nuncompressed) as a sequence of small responses, avoiding the\n``IncompleteRead`` a single-response transfer reliably hits\nabove ~30 MB.","required":false,"schema":{"type":["integer","null"],"minimum":0}},{"name":"limit","in":"query","description":"Maximum number of sorts to return. When omitted, no cap is\napplied (legacy behaviour). Recommended page size for\nproduction tenants: 50_000.","required":false,"schema":{"type":["integer","null"],"minimum":0}}],"responses":{"200":{"description":"List of sorts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SortListResponse"}}}}}}},"/api/v1/sorts/{child_id}/subtype/{parent_id}":{"get":{"tags":["sorts"],"summary":"Check if one sort is a subtype of another","operationId":"is_subtype","parameters":[{"name":"child_id","in":"path","description":"Child sort ID","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"parent_id","in":"path","description":"Parent sort ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Subtype check result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IsSubtypeResponse"}}}}}}},"/api/v1/sorts/{id}":{"get":{"tags":["sorts"],"summary":"Get a sort by ID","operationId":"get_sort","parameters":[{"name":"id","in":"path","description":"Sort ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Sort found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SortResponse"}}}},"404":{"description":"Sort not found"}}},"delete":{"tags":["sorts"],"summary":"Delete a sort by ID","description":"# Authorization\nRequires X-Tenant-Id header. The sort must belong to the tenant.\n\n# Errors\n- 404 Not Found: Sort doesn't exist\n- 400 Bad Request: Sort has children (would orphan them)","operationId":"delete_sort","parameters":[{"name":"id","in":"path","description":"Sort ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Sort deleted"},"400":{"description":"Cannot delete sort with children"},"404":{"description":"Sort not found"}},"security":[{"tenant_id":[]}]}},"/api/v1/sorts/{id}/ancestors":{"get":{"tags":["types"],"summary":"Get ancestors of a sort\nGET /api/v1/sorts/:id/ancestors","operationId":"get_sort_ancestors","parameters":[{"name":"id","in":"path","description":"Sort ID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Get ancestors of a sort","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SortAncestorsResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/sorts/{id}/children":{"get":{"tags":["types"],"summary":"Get children of a sort\nGET /api/v1/sorts/:id/children","operationId":"get_sort_children","parameters":[{"name":"id","in":"path","description":"Sort ID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Get children of a sort","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SortChildrenResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/sorts/{id}/compatible":{"get":{"tags":["sorts"],"summary":"Get compatible sorts for a given sort","operationId":"get_compatible_sorts","parameters":[{"name":"id","in":"path","description":"Sort ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Compatible sorts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SortListResponse"}}}}}}},"/api/v1/sorts/{id}/descendants":{"get":{"tags":["types"],"summary":"Get descendants of a sort\nGET /api/v1/sorts/:id/descendants","operationId":"get_sort_descendants","parameters":[{"name":"id","in":"path","description":"Sort ID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Get descendants of a sort","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SortDescendantsResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/sorts/{id}/parents":{"get":{"tags":["types"],"summary":"Get parents of a sort\nGET /api/v1/sorts/:id/parents","operationId":"get_sort_parents","parameters":[{"name":"id","in":"path","description":"Sort ID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Get parents of a sort","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SortParentsResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/sorts/{id}/review":{"post":{"tags":["sorts"],"summary":"Update the review status of a sort (approve or mark for review)","operationId":"update_sort_review","parameters":[{"name":"id","in":"path","description":"Sort ID","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSortReviewRequest"}}},"required":true},"responses":{"200":{"description":"Sort review updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SortResponse"}}}}}}},"/api/v1/sources":{"get":{"tags":["structured_ingestion"],"summary":"List all registered data sources.","operationId":"list_sources","responses":{"200":{"description":"List of registered sources","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListSourcesResponse"}}}}},"security":[{"tenant_id":[]}]},"post":{"tags":["structured_ingestion"],"summary":"Register a new data source.","description":"Creates a connector instance from the provided configuration and registers it\nwith the structured ingestion service for subsequent schema discovery and\ndata ingestion.","operationId":"register_source","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterSourceRequest"}}},"required":true},"responses":{"201":{"description":"Source registered successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterSourceResponse"}}}},"400":{"description":"Invalid source configuration"}},"security":[{"tenant_id":[]}]}},"/api/v1/sources/{source_id}":{"get":{"tags":["structured_ingestion"],"summary":"Get details and health check for a registered source.","operationId":"get_source","parameters":[{"name":"source_id","in":"path","description":"Source identifier","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Source details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceDetailResponse"}}}},"404":{"description":"Source not found"}},"security":[{"tenant_id":[]}]},"delete":{"tags":["structured_ingestion"],"summary":"Unregister a data source.","operationId":"delete_source","parameters":[{"name":"source_id","in":"path","description":"Source identifier","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Source unregistered"},"404":{"description":"Source not found"}},"security":[{"tenant_id":[]}]}},"/api/v1/sources/{source_id}/discover":{"post":{"tags":["structured_ingestion"],"summary":"Discover schema from a registered source.","description":"Performs schema introspection on the source to discover types (sorts),\nfeatures (fields), and relations. This is a preview operation - no data\nis ingested.","operationId":"discover_schema","parameters":[{"name":"source_id","in":"path","description":"Source identifier","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscoverSchemaRequest"}}},"required":true},"responses":{"200":{"description":"Schema discovered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscoverSchemaResponse"}}}},"400":{"description":"Discovery failed"},"404":{"description":"Source not found"}},"security":[{"tenant_id":[]}]}},"/api/v1/sources/{source_id}/ingest":{"post":{"tags":["structured_ingestion"],"summary":"Ingest data from a registered source.","description":"Executes the full pipeline:\n1. Schema discovery from connector\n2. Paginated data fetch from connector\n3. Render structured data to markdown with schema context\n4. Feed through existing NER + LLM + OSFKB pipeline","operationId":"ingest_from_source","parameters":[{"name":"source_id","in":"path","description":"Source identifier","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestFromSourceRequest"}}},"required":true},"responses":{"201":{"description":"Data ingested successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestFromSourceResponse"}}}},"400":{"description":"Ingestion failed"},"404":{"description":"Source not found"}},"security":[{"tenant_id":[]}]}},"/api/v1/spaces":{"post":{"tags":["spaces"],"summary":"Create a new computation space","operationId":"create_space","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSpaceRequest"}}},"required":true},"responses":{"200":{"description":"Create a computation space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpaceResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/spaces/{space_id}":{"get":{"tags":["spaces"],"summary":"Get the status of a computation space","operationId":"get_space","parameters":[{"name":"space_id","in":"path","description":"Space ID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Get space status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpaceResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/spaces/{space_id}/clone":{"post":{"tags":["spaces"],"summary":"Clone a computation space for parallel exploration","operationId":"clone_space","parameters":[{"name":"space_id","in":"path","description":"Space ID to clone","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Clone a computation space","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpaceResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/spaces/{space_id}/commit":{"post":{"tags":["spaces"],"summary":"Commit to an alternative in a space","operationId":"commit_space","parameters":[{"name":"space_id","in":"path","description":"Space ID to commit","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommitRequest"}}},"required":true},"responses":{"200":{"description":"Commit to an alternative","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpaceResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/spaces/{space_id}/search":{"post":{"tags":["spaces"],"summary":"Search for solutions in a space","operationId":"search_space","parameters":[{"name":"space_id","in":"path","description":"Space ID to search","required":true,"schema":{"type":"string"}},{"name":"value_ordering","in":"query","description":"Value ordering strategy (e.g., \"min\", \"max\", \"median\")","required":false,"schema":{"type":["string","null"]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}},"required":true},"responses":{"200":{"description":"Search result — discriminated by the `kind` field. `kind = \"solutions\"` when `mode` is omitted or `\"solutions\"` (default); `kind = \"feasibility\"` when `mode = \"feasibility\"`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/statistical/clear-data":{"post":{"tags":["statistical"],"summary":"Clear all statistical data","description":"This endpoint clears all observed data from the statistical store,\nallowing tests or workflows to start with fresh data.","operationId":"clear_statistical_data","responses":{"200":{"description":"Statistical data cleared","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatisticalSuccessResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/statistical/correlation":{"post":{"tags":["statistical"],"summary":"Get correlation between two variables","operationId":"get_correlation","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CorrelationRequest"}}},"required":true},"responses":{"200":{"description":"Correlation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CorrelationResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/statistical/discover-causal":{"post":{"tags":["statistical"],"summary":"Run causal discovery using DynamicDiscoveryEngine","operationId":"discover_causal","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscoverCausalRequest"}}},"required":true},"responses":{"200":{"description":"Discovery result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscoverCausalResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/statistical/discovery-status":{"get":{"tags":["statistical"],"summary":"Get current discovery status","operationId":"get_discovery_status","responses":{"200":{"description":"Discovery status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscoveryStatusResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/statistical/dynamic-discovery":{"post":{"tags":["statistical"],"summary":"Run dynamic causal discovery with full proof tree and recommendations","operationId":"dynamic_discovery","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DynamicDiscoveryRequest"}}},"required":true},"responses":{"200":{"description":"Dynamic discovery result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DynamicDiscoveryResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/statistical/intervention-observation":{"post":{"tags":["statistical"],"summary":"Record an intervention observation to resolve uncertain edges","operationId":"record_intervention_observation","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InterventionObservationRequest"}}},"required":true},"responses":{"200":{"description":"Intervention observation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InterventionObservationResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/statistical/observe":{"post":{"tags":["statistical"],"summary":"Observe a single variable value","operationId":"observe_single","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObserveSingleRequest"}}},"required":true},"responses":{"200":{"description":"Observation recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObserveSingleResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/statistical/observe-multi":{"post":{"tags":["statistical"],"summary":"Observe multiple variables at once","operationId":"observe_multi","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObserveMultiRequest"}}},"required":true},"responses":{"200":{"description":"Multi observation recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObserveMultiResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/statistical/observe-pair":{"post":{"tags":["statistical"],"summary":"Observe a pair of variables","operationId":"observe_pair","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObservePairRequest"}}},"required":true},"responses":{"200":{"description":"Paired observation recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ObservePairResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/statistical/partial-correlation":{"post":{"tags":["statistical"],"summary":"Get partial correlation controlling for a set of variables","operationId":"get_partial_correlation","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartialCorrelationRequest"}}},"required":true},"responses":{"200":{"description":"Partial correlation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartialCorrelationResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/statistical/reset-discovery":{"post":{"tags":["statistical"],"summary":"Reset the discovery engine","operationId":"reset_discovery","responses":{"200":{"description":"Discovery engine reset","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatisticalSuccessResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/statistical/test-independence":{"post":{"tags":["statistical"],"summary":"Test conditional independence","operationId":"test_conditional_independence","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConditionalIndependenceRequest"}}},"required":true},"responses":{"200":{"description":"Independence test result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConditionalIndependenceResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/strings/asc":{"post":{"tags":["strings"],"summary":"Get ASCII code of character\nPOST /api/v1/strings/asc","operationId":"string_asc","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AscRequest"}}},"required":true},"responses":{"200":{"description":"Get ASCII code of character","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AscResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/strings/chr":{"post":{"tags":["strings"],"summary":"Get character from ASCII code\nPOST /api/v1/strings/chr","operationId":"string_chr","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChrRequest"}}},"required":true},"responses":{"200":{"description":"Get character from ASCII code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChrResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/strings/compare":{"post":{"tags":["strings"],"summary":"Compare two strings\nPOST /api/v1/strings/compare","operationId":"string_compare","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StringCompareRequest"}}},"required":true},"responses":{"200":{"description":"Compare two strings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StringCompareResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/strings/compare-batch":{"post":{"tags":["strings"],"summary":"Batch string comparison for multiple predicates\nPOST /api/v1/strings/compare-batch","description":"Useful for checking multiple string constraints at once.","operationId":"string_compare_batch","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchStringCompareRequest"}}},"required":true},"responses":{"200":{"description":"Batch string comparison","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchStringCompareResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/strings/compare-predicate":{"post":{"tags":["strings"],"summary":"Wild_Life-style string comparison predicate\nPOST /api/v1/strings/compare-predicate","description":"Returns success/failure semantics like Wild_LIFE predicates.\nUses lexicographic ordering for comparisons.","operationId":"string_compare_predicate","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StringComparePredicateRequest"}}},"required":true},"responses":{"200":{"description":"String comparison predicate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StringComparePredicateResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/strings/concat":{"post":{"tags":["strings"],"summary":"Concatenate two strings\nPOST /api/v1/strings/concat","operationId":"string_concat","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StringConcatRequest"}}},"required":true},"responses":{"200":{"description":"Concatenate two strings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StringConcatResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/strings/from-number":{"post":{"tags":["strings"],"summary":"Convert number to string\nPOST /api/v1/strings/from-number","operationId":"number_to_string","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NumberToStringRequest"}}},"required":true},"responses":{"200":{"description":"Convert number to string","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NumberToStringResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/strings/length":{"post":{"tags":["strings"],"summary":"Get string length\nPOST /api/v1/strings/length","operationId":"string_length","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StringLengthRequest"}}},"required":true},"responses":{"200":{"description":"Get string length","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StringLengthResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/strings/op":{"post":{"tags":["strings"],"summary":"General string operation\nPOST /api/v1/strings/op","operationId":"string_op","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StringOpRequest"}}},"required":true},"responses":{"200":{"description":"General string operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StringOpResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/strings/substr":{"post":{"tags":["strings"],"summary":"Get substring\nPOST /api/v1/strings/substr","operationId":"string_substr","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubstringRequest"}}},"required":true},"responses":{"200":{"description":"Get substring","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubstringResponse"}}}},"400":{"description":"Bad request"},"500":{"description":"Internal server error"}},"security":[{"tenant_auth":[]}]}},"/api/v1/synthetic/calibrate":{"post":{"tags":["synthetic"],"summary":"Run ECE calibration on extraction predictions.","description":"Computes per-sort and per-feature Expected Calibration Error,\nidentifies augmentation targets, and allocates exponential budgets\nfor targeted synthetic data generation.","operationId":"calibrate","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalibrateRequest"}}},"required":true},"responses":{"200":{"description":"Calibration report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalibrationReportDto"}}}},"400":{"description":"Invalid request"}},"security":[{"tenant_id":[]}]}},"/api/v1/synthetic/check-diversity":{"post":{"tags":["synthetic"],"summary":"Check diversity of a candidate term against existing terms in the knowledge base.","description":"Computes structural similarity using Wu-Palmer sort distance and\nJaccard feature overlap. Returns novelty score and closest match.\n\n# Authorization\nRequires X-Tenant-Id header for tenant-scoped operations.","operationId":"check_diversity","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckDiversityRequest"}}},"required":true},"responses":{"200":{"description":"Diversity check complete","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckDiversityResponse"}}}},"400":{"description":"Invalid request"}},"security":[{"tenant_id":[]}]}},"/api/v1/synthetic/export-jsonl":{"post":{"tags":["synthetic"],"summary":"Export synthetic training data as JSONL format.","description":"Generates synthetic data and returns it directly as JSONL (one JSON object per line),\nsuitable for HuggingFace-compatible fine-tuning pipelines.\n\n# Authorization\nRequires X-Tenant-Id header for tenant-scoped generation.","operationId":"export_jsonl","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateSyntheticDataRequest"}}},"required":true},"responses":{"200":{"description":"JSONL exported","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportJsonlResponse"}}}},"400":{"description":"Invalid request"}},"security":[{"tenant_id":[]}]}},"/api/v1/synthetic/generate":{"post":{"tags":["synthetic"],"summary":"Generate synthetic training data from the knowledge base.","description":"Uses constraint solving (backward chaining, CLP(FD), MCMC, forward chaining)\nto generate valid Ψ-terms, then converts them into multi-format training pairs\nfor SLM fine-tuning. Supports 5 training pair formats: Extraction, QuestionAnswer,\nFillBlank, Negative, and MultiHop.\n\n# Authorization\nRequires X-Tenant-Id header for tenant-scoped generation.","operationId":"generate_synthetic","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateSyntheticDataRequest"}}},"required":true},"responses":{"200":{"description":"Synthetic data generated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateSyntheticDataResponse"}}}},"400":{"description":"Invalid request"}},"security":[{"tenant_id":[]}]}},"/api/v1/synthetic/generation-prompt":{"post":{"tags":["synthetic"],"summary":"Build a generation prompt for LLM-based verbalization.","description":"Creates a structured prompt with a stable prefix (cacheable across batch calls)\nand dynamic content for a specific term. Mirrors the extraction pipeline's\nprompt architecture for KV-cache reuse.\n\n# Authorization\nRequires X-Tenant-Id header for tenant-scoped operations.","operationId":"build_generation_prompt","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationPromptRequest"}}},"required":true},"responses":{"200":{"description":"Generation prompt built","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerationPromptResponse"}}}},"400":{"description":"Invalid request"},"404":{"description":"Term not found"}},"security":[{"tenant_id":[]}]}},"/api/v1/synthetic/negatives":{"post":{"tags":["synthetic"],"summary":"Generate enhanced negative examples for target sorts.","description":"Uses principled strategies to create training examples that are negative\n(invalid) for specific, documented reasons: sort incompatibility,\nfeature perturbation, cross-sort confusion, missing required features,\nand feature type mismatch.\n\n# Authorization\nRequires X-Tenant-Id header for tenant-scoped operations.","operationId":"generate_negatives","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateNegativesRequest"}}},"required":true},"responses":{"200":{"description":"Negatives generated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateNegativesResponse"}}}},"400":{"description":"Invalid request"}},"security":[{"tenant_id":[]}]}},"/api/v1/synthetic/verbalize":{"post":{"tags":["synthetic"],"summary":"Verbalize a single term from the knowledge base.","description":"Converts a PsiTerm into natural language text using the specified strategy.\nUseful for on-demand text generation from existing terms.\n\n# Authorization\nRequires X-Tenant-Id header for tenant-scoped operations.","operationId":"verbalize_term","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerbalizeTermRequest"}}},"required":true},"responses":{"200":{"description":"Term verbalized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerbalizeTermResponse"}}}},"400":{"description":"Invalid request"},"404":{"description":"Term not found"}},"security":[{"tenant_id":[]}]}},"/api/v1/synthetic/verify-faithfulness":{"post":{"tags":["synthetic"],"summary":"Verify faithfulness of generated text against source entities.","description":"Compares original entity features against extracted features to determine\nif the generated text faithfully represents the source Ψ-term. Uses\nexact string matching with configurable thresholds for score and recovery rate.\n\n# Authorization\nRequires X-Tenant-Id header for tenant-scoped operations.","operationId":"verify_faithfulness","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyFaithfulnessRequest"}}},"required":true},"responses":{"200":{"description":"Faithfulness verified","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyFaithfulnessResponse"}}}},"400":{"description":"Invalid request"}},"security":[{"tenant_id":[]}]}},"/api/v1/synthetic/verify-round-trip":{"post":{"tags":["synthetic"],"summary":"Verify round-trip faithfulness of extracted entities against ground truth.","description":"Uses OSF-aware verification with Wu-Palmer sort similarity,\nfeature-level comparison with type-aware value similarity,\nand Hungarian algorithm for optimal entity matching.\n\n# Authorization\nRequires X-Tenant-Id header for tenant-scoped operations.","operationId":"verify_round_trip","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyRoundTripRequest"}}},"required":true},"responses":{"200":{"description":"Round-trip verification complete","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyRoundTripResponse"}}}},"400":{"description":"Invalid request"}},"security":[{"tenant_id":[]}]}},"/api/v1/templates":{"get":{"tags":["templates"],"summary":"GET /api/v1/templates","description":"List all query templates for the authenticated user's tenant.","operationId":"list_templates_handler","responses":{"200":{"description":"Template list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListTemplatesResponseDto"}}}}},"security":[{"tenant_id":[]}]},"post":{"tags":["templates"],"summary":"POST /api/v1/templates","description":"Create a new user-defined query template.","operationId":"create_template","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTemplateRequestDto"}}},"required":true},"responses":{"201":{"description":"Template created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryTemplateDto"}}}},"400":{"description":"Invalid request"}},"security":[{"tenant_id":[]}]}},"/api/v1/templates/{id}":{"put":{"tags":["templates"],"summary":"PUT /api/v1/templates/{id}","description":"Update an existing query template.","operationId":"update_template_handler","parameters":[{"name":"id","in":"path","description":"Template ID","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTemplateRequestDto"}}},"required":true},"responses":{"200":{"description":"Template updated"},"404":{"description":"Template not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"tenant_id":[]}]},"delete":{"tags":["templates"],"summary":"DELETE /api/v1/templates/{id}","description":"Delete a query template.","operationId":"delete_template_handler","parameters":[{"name":"id","in":"path","description":"Template ID","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Template deleted"},"404":{"description":"Template not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/terms":{"get":{"tags":["terms"],"summary":"List all terms for the authenticated tenant","description":"Returns all terms belonging to the tenant identified by the X-Tenant-Id header.\nTerms are enriched with sort names, display names, and referenced term summaries.\n\n# Authorization\nRequires X-Tenant-Id header.","operationId":"list_terms","responses":{"200":{"description":"List of terms","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TermListResponse"}}}}},"security":[{"tenant_id":[]}]},"post":{"tags":["terms"],"summary":"Add a new term","description":"Creates a term and validates it against its sort's existential witnesses.\nThis implements Hassan Aït-Kaci's LIFE semantics where \"types ARE constraints\".\n\n## Witness Validation\n\nWhen a term is created:\n1. If the sort has no witnesses → state = `no_witnesses` (trivially complete)\n2. If all witnesses are satisfied → state = `complete` with proofs\n3. If witnesses can't be satisfied yet → state = `residuated` (waiting for info)\n\nResiduated terms are stored and will be re-evaluated when new facts arrive\nthat might satisfy their pending witnesses.\n\n# Authorization\nRequires X-Tenant-Id header. The tenant_id field in the request body is ignored.","operationId":"add_term","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTermRequest"}}},"required":true},"responses":{"201":{"description":"Term created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TermResponse"}}}},"400":{"description":"Invalid request"}},"security":[{"tenant_id":[]}]},"delete":{"tags":["terms"],"summary":"Clear all terms for the authenticated tenant","description":"Removes all terms (facts and rules) belonging to the tenant identified by\nthe X-Tenant-Id header. This clears both PostgreSQL persistence and in-memory\nstores, including the residuation store.\n\n# Authorization\nRequires X-Tenant-Id header.","operationId":"clear_terms","responses":{"200":{"description":"Terms cleared","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClearTermsResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/terms/bulk":{"post":{"tags":["terms"],"summary":"Bulk add multiple terms","description":"Creates multiple terms in a single operation for efficiency.\nThis is optimized for high-volume data loading scenarios and skips\nindividual witness validation (constraint propagation runs once at the end).\n\n# Performance\n- Terms are added to the domain store in a single lock acquisition\n- Constraint propagation runs once after all terms are added\n- Much faster than calling add_term N times\n\n# Authorization\nRequires X-Tenant-Id header. The tenant_id is taken from the header.","operationId":"bulk_add_terms","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkAddTermsRequest"}}},"required":true},"responses":{"201":{"description":"Terms created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkAddTermsResponse"}}}},"400":{"description":"Invalid request"}},"security":[{"tenant_id":[]}]}},"/api/v1/terms/{id}":{"get":{"tags":["terms"],"summary":"Get a term by ID","operationId":"get_term","parameters":[{"name":"id","in":"path","description":"Term ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Term found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TermResponse"}}}},"404":{"description":"Term not found"}}},"put":{"tags":["terms"],"summary":"Update a term","operationId":"update_term","parameters":[{"name":"id","in":"path","description":"Term ID","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTermRequest"}}},"required":true},"responses":{"200":{"description":"Term updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TermResponse"}}}},"404":{"description":"Term not found"}}},"delete":{"tags":["terms"],"summary":"Delete a term","operationId":"delete_term","parameters":[{"name":"id","in":"path","description":"Term ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Term deleted"},"404":{"description":"Term not found"}}}},"/api/v1/terms/{id}/exists":{"get":{"tags":["terms"],"summary":"Check if a term exists","operationId":"term_exists","parameters":[{"name":"id","in":"path","description":"Term ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Existence check result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TermExistsResponse"}}}}}}},"/api/v1/triz/invent":{"post":{"tags":["query"],"summary":"Handle `POST /api/v1/triz/invent` — deterministic TRIZ invention.","description":"Skips the NL → structured-problem LLM hop entirely. Caller must have\nseeded the tenant KB with ≥ 3 successful + ≥ 2 limited Ψ-terms per\ndomain (`/api/v1/terms/bulk` or `/api/v1/inference/facts/bulk`).\nReturns the same `NlQueryResponse` shape as the NL route so the UI\ncan render either output uniformly.","operationId":"triz_invent","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrizInventRequest"}}},"required":true},"responses":{"200":{"description":"TRIZ inventive proposals","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NlQueryResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/triz/record-outcome":{"post":{"tags":["query"],"summary":"Handle `POST /api/v1/triz/record-outcome` — persist a measured outcome\nfor a previously-emitted TRIZ proposal and learn from it.","operationId":"triz_record_outcome","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrizRecordOutcomeRequest"}}},"required":true},"responses":{"200":{"description":"Outcome recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrizRecordOutcomeResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/ui/action":{"post":{"tags":["ui"],"summary":"Execute a UI action via OSFQL.","description":"Translates structured action requests into OSFQL statements and\nexecutes them against the tenant's knowledge base.\n\nPOST /api/v1/ui/action","operationId":"execute_ui_action","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UIActionRequest"}}},"required":true},"responses":{"200":{"description":"Action executed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UIActionResponse"}}}},"400":{"description":"Invalid action"},"422":{"description":"Execution error"},"500":{"description":"Internal error"}},"security":[{"tenant_id":[]}]}},"/api/v1/ui/catalog":{"get":{"tags":["ui"],"summary":"Get the UI component catalog","description":"GET /api/v1/ui/catalog","operationId":"ui_catalog","responses":{"200":{"description":"UI component catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UICatalogResponse"}}}}}}},"/api/v1/ui/describe":{"post":{"tags":["ui"],"summary":"Assemble a UI descriptor tree for a sort.","description":"If `load_data` is true (default), Table/Detail views will execute OSFQL\nto load data and populate the response's `data` field.\n\nPOST /api/v1/ui/describe","operationId":"describe_ui","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UIDescribeRequest"}}},"required":true},"responses":{"200":{"description":"UI descriptor assembled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UIDescribeResponse"}}}},"400":{"description":"Invalid request"},"404":{"description":"Sort not found"},"500":{"description":"Internal error"}},"security":[{"tenant_id":[]}]}},"/api/v1/ui/describe/stream":{"post":{"tags":["ui"],"summary":"Stream a UI descriptor tree via SSE.","description":"Events:\n- `layout_ready` — LayoutSurface JSON\n- `component_ready` — {slot_id, descriptor} JSON\n- `data_chunk` — {slot_id, data} JSON (if data was loaded)\n- `complete` — {}\n\nPOST /api/v1/ui/describe/stream","operationId":"describe_ui_stream","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UIDescribeRequest"}}},"required":true},"responses":{"200":{"description":"SSE stream of UI descriptor events"},"404":{"description":"Sort not found"},"500":{"description":"Internal error"}},"security":[{"tenant_id":[]}]}},"/api/v1/visualization/constraints":{"post":{"tags":["visualization"],"summary":"Get constraint dependency graph","operationId":"get_constraint_graph","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConstraintGraphRequest"}}},"required":true},"responses":{"200":{"description":"Constraint dependency graph","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConstraintGraphResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/visualization/hypergraph":{"post":{"tags":["visualization"],"summary":"Get OSF term hypergraph visualization","operationId":"get_hypergraph","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HypergraphRequest"}}},"required":true},"responses":{"200":{"description":"Term hypergraph","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HypergraphResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/visualization/hypergraph/term/{term_id}":{"get":{"tags":["visualization"],"summary":"Get subgraph rooted at a specific term","operationId":"get_term_subgraph","parameters":[{"name":"term_id","in":"path","description":"Term ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Term subgraph","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HypergraphResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/visualization/lattice":{"post":{"tags":["visualization"],"summary":"Get the sort hierarchy lattice visualization","description":"Returns a graph representation of the sort hierarchy with nodes for each sort\nand edges for subtype relationships. Supports filtering by root sort and depth.","operationId":"get_lattice_visualization","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LatticeVisualizationRequest"}}},"required":true},"responses":{"200":{"description":"Lattice visualization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LatticeVisualizationResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/visualization/lattice/dot":{"get":{"tags":["visualization"],"summary":"Get the lattice visualization as DOT format","operationId":"get_lattice_dot","responses":{"200":{"description":"DOT format output"}},"security":[{"tenant_id":[]}]}},"/api/v1/visualization/lattice/glb-lub-trace":{"post":{"tags":["visualization"],"summary":"Compute GLB or LUB with trace","operationId":"glb_lub_trace","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlbLubTraceRequest"}}},"required":true},"responses":{"200":{"description":"GLB/LUB computation trace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GlbLubComputationTrace"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/visualization/residuation":{"post":{"tags":["visualization"],"summary":"Get residuation state diagram","operationId":"get_residuation_state","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResiduationStateRequest"}}},"required":true},"responses":{"200":{"description":"Residuation state diagram","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResiduationStateResponse"}}}}},"security":[{"tenant_id":[]}]}},"/api/v1/visualization/residuation/triggers":{"post":{"tags":["visualization"],"summary":"Get trigger dependency graph","operationId":"get_trigger_dependencies","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TriggerDependencyRequest"}}},"required":true},"responses":{"200":{"description":"Trigger dependency graph","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TriggerDependencyResponse"}}}}},"security":[{"tenant_id":[]}]}},"/health":{"get":{"tags":["health"],"summary":"Enriched health check endpoint","description":"Returns overall status, individual component statuses, and build information.\nThis replaces the legacy static `/health` with a comprehensive view.","operationId":"health_check","responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichedHealthResponse"}}}},"503":{"description":"Service is unhealthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichedHealthResponse"}}}}}}}},"components":{"schemas":{"ActionReviewReasonDto":{"oneOf":[{"type":"string","description":"Action is configured to always require approval","enum":["requires_approval"]},{"type":"string","description":"Action is high-risk (file write, delete, etc.)","enum":["high_risk"]},{"type":"string","description":"Action has external side effects","enum":["external_side_effect"]},{"type":"string","description":"Action confidence is below threshold","enum":["low_confidence"]},{"type":"string","description":"First time using this action type","enum":["first_use"]},{"type":"object","description":"Custom reason","required":["custom"],"properties":{"custom":{"type":"string","description":"Custom reason"}}}],"description":"Reason why an action requires review"},"ActionReviewResponse":{"type":"object","description":"Response from an action review decision","required":["success","status","action_term_id","will_execute","executed","message"],"properties":{"action_term_id":{"type":"string","format":"uuid","description":"Action term ID (for tracking execution)"},"executed":{"type":"boolean","description":"Whether execution was triggered (bridged to AGENT_STORE)"},"message":{"type":"string","description":"Message describing what happened"},"status":{"$ref":"#/components/schemas/ActionReviewStatusDto","description":"The final status of the review"},"success":{"type":"boolean","description":"Whether the decision was applied successfully"},"will_execute":{"type":"boolean","description":"Whether the action will be executed"}}},"ActionReviewStatusDto":{"type":"string","description":"Status of an action review","enum":["pending","approved","rejected","modified","timed_out"]},"ActionReviewSummaryDto":{"type":"object","description":"Summary statistics for pending action reviews","required":["total_pending","by_action_sort","by_reason","high_priority_count","expiring_soon_count"],"properties":{"by_action_sort":{"type":"object","description":"Breakdown by action sort","additionalProperties":{"type":"integer","minimum":0},"propertyNames":{"type":"string"}},"by_reason":{"type":"object","description":"Breakdown by review reason","additionalProperties":{"type":"integer","minimum":0},"propertyNames":{"type":"string"}},"expiring_soon_count":{"type":"integer","description":"Reviews expiring soon (< 15 minutes)","minimum":0},"high_priority_count":{"type":"integer","description":"Reviews with high priority (> 0.7)","minimum":0},"total_pending":{"type":"integer","description":"Total pending reviews","minimum":0}}},"ActivationDto":{"type":"object","description":"Activation level DTO.","required":["term_id","base_level","spread_level","total"],"properties":{"base_level":{"type":"number","format":"double","description":"Base-level activation"},"label":{"type":["string","null"],"description":"First meaningful string feature value as label"},"sort_name":{"type":["string","null"],"description":"Sort name of the referenced term"},"spread_level":{"type":"number","format":"double","description":"Spreading activation"},"term_id":{"type":"string","format":"uuid","description":"Term ID"},"total":{"type":"number","format":"double","description":"Total activation"}}},"AdaptiveModifyRequest":{"type":"object","description":"Request for adaptive rule modification.","required":["agent_id","tenant_id","action","term"],"properties":{"action":{"type":"string","description":"Action: \"assert\" or \"retract\""},"agent_id":{"type":"string","format":"uuid","description":"Agent ID"},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"},"term":{"$ref":"#/components/schemas/GoalDto","description":"Rule/fact to modify"}}},"AdaptiveModifyResponse":{"type":"object","description":"Response from adaptive modification.","required":["success","message"],"properties":{"message":{"type":"string","description":"Message"},"success":{"type":"boolean","description":"Whether modification succeeded"},"term_id":{"type":["string","null"],"format":"uuid","description":"Term ID of modified term"}}},"AddBeliefRequest":{"type":"object","description":"Request to add a belief to an agent.","required":["agent_id","tenant_id","belief","confidence"],"properties":{"agent_id":{"type":"string","format":"uuid","description":"Agent ID"},"belief":{"$ref":"#/components/schemas/BeliefDto","description":"Belief term"},"confidence":{"type":"number","format":"double","description":"Confidence in the belief (0.0 to 1.0)"},"source":{"type":"string","description":"Source of the belief","default":"api"},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"}}},"AddBeliefResponse":{"type":"object","description":"Response after adding a belief.","required":["belief_id","message"],"properties":{"belief_id":{"type":"string","format":"uuid","description":"Belief term ID"},"message":{"type":"string","description":"Message"}}},"AddCausalRelationRequest":{"type":"object","description":"Request to add a causal relationship to the model","required":["cause","effect"],"properties":{"cause":{"type":"string","description":"The cause variable"},"certainty":{"type":"number","format":"double","description":"Certainty of the causal relationship (0.0 to 1.0)"},"effect":{"type":"string","description":"The effect variable"},"mechanism":{"type":["string","null"],"description":"Optional mechanism description"}}},"AddCausalRelationResponse":{"type":"object","description":"Response for adding a causal relation","required":["success","rule_id","message"],"properties":{"message":{"type":"string","description":"Message"},"rule_id":{"type":"string","format":"uuid","description":"ID of the created rule"},"success":{"type":"boolean","description":"Whether the relation was added successfully"}}},"AddCognitiveRuleRequest":{"type":"object","description":"Request to add a rule to the cognitive agent's ruleset.","required":["tenant_id","head"],"properties":{"antecedents":{"type":"array","items":{"$ref":"#/components/schemas/CognitiveTermInput"},"description":"Rule antecedents (conditions) - empty for facts"},"certainty":{"type":"number","format":"double","description":"Rule certainty (0.0 to 1.0)","default":1.0},"head":{"$ref":"#/components/schemas/CognitiveTermInput","description":"Rule head (conclusion)"},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"}}},"AddCognitiveRuleResponse":{"type":"object","description":"Response after adding a cognitive rule.","required":["rule_id","message"],"properties":{"message":{"type":"string","description":"Message"},"rule_id":{"type":"string","format":"uuid","description":"Rule term ID"}}},"AddConnectorRequest":{"type":"object","required":["type","name"],"properties":{"name":{"type":"string"},"type":{"type":"string"}}},"AddConnectorResponse":{"type":"object","description":"Response body for `POST /api/v1/connectors/manage` — created instance.","required":["id","name","status"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"}}},"AddConstraintsRequest":{"type":"object","description":"Request to add constraints to an existing session","required":["constraints"],"properties":{"bindings":{"type":["object","null"],"additionalProperties":{"type":"integer","format":"int64"},"propertyNames":{"type":"string"}},"constraints":{"type":"array","items":{"$ref":"#/components/schemas/GeneralConstraintDto"}}}},"AddConstraintsResponse":{"type":"object","description":"Response from adding constraints","required":["success","added_count","satisfied_count","suspended_count","current_bindings"],"properties":{"added_count":{"type":"integer","minimum":0},"current_bindings":{"type":"object","additionalProperties":{"type":"integer","format":"int64"},"propertyNames":{"type":"string"}},"message":{"type":["string","null"]},"satisfied_count":{"type":"integer","minimum":0},"success":{"type":"boolean"},"suspended_count":{"type":"integer","minimum":0}}},"AddExportRequest":{"type":"object","description":"Request to add an export","required":["symbol"],"properties":{"symbol":{"type":"string","description":"Symbol name to export"}}},"AddFactRequest":{"type":"object","description":"Request to add a fact (a term with no antecedents).","required":["term"],"properties":{"term":{"$ref":"#/components/schemas/TermInputDto","description":"The term to add as a fact"}}},"AddFactResponse":{"type":"object","description":"Response after adding a fact.","required":["term"],"properties":{"term":{"$ref":"#/components/schemas/PsiTermDto","description":"The created term"}}},"AddGoalRequest":{"type":"object","description":"Request to add a goal to an agent.","required":["agent_id","tenant_id","goal"],"properties":{"agent_id":{"type":"string","format":"uuid","description":"Agent ID"},"goal":{"$ref":"#/components/schemas/GoalDto","description":"Goal term as a clause (will be converted to TermId)"},"priority":{"type":"integer","format":"int32","description":"Priority (higher = more important)"},"status":{"type":"string","description":"Initial status (default: \"pending\")","default":"pending"},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"}}},"AddGoalResponse":{"type":"object","description":"Response after adding a goal.","required":["goal_id","message"],"properties":{"goal_id":{"type":"string","format":"uuid","description":"Goal term ID"},"message":{"type":"string","description":"Message"}}},"AddHtnMethodRequest":{"type":"object","description":"Request to add an HTN decomposition method.","required":["tenant_id","agent_id","task_pattern","subtasks"],"properties":{"agent_id":{"type":"string","format":"uuid","description":"Agent ID"},"preconditions":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Optional preconditions"},"subtasks":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Subtask sequence"},"task_pattern":{"type":"string","format":"uuid","description":"Task pattern this method handles"},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"}}},"AddHtnMethodResponse":{"type":"object","description":"Response after adding an HTN method.","required":["method_id","message"],"properties":{"message":{"type":"string","description":"Success message"},"method_id":{"type":"string","format":"uuid","description":"Created method ID"}}},"AddImportRequest":{"type":"object","description":"Request to add an import","required":["source_id"],"properties":{"source_id":{"type":"string","format":"uuid","description":"Source namespace ID to import from"}}},"AddPendingReviewRequest":{"type":"object","description":"Request to add a pending review","required":["entity_id","sort","features","confidence","reason","candidates","sort_suggestions","tenant_id","owner_id"],"properties":{"candidates":{"type":"array","items":{"$ref":"#/components/schemas/ReviewCandidateMatchDto"}},"confidence":{"type":"number","format":"double"},"entity_id":{"type":"string"},"features":{"type":"object","additionalProperties":{},"propertyNames":{"type":"string"}},"owner_id":{"type":"string","format":"uuid"},"reason":{"$ref":"#/components/schemas/ReviewReason"},"sort":{"type":"string"},"sort_suggestions":{"type":"array","items":{"$ref":"#/components/schemas/SortSuggestionDto"}},"source_document":{"type":["string","null"]},"source_text":{"type":["string","null"]},"tenant_id":{"type":"string","format":"uuid"}}},"AddPendingReviewResponse":{"type":"object","description":"Response from adding a pending review","required":["review_id"],"properties":{"review_id":{"type":"string","format":"uuid"}}},"AddRuleRequest":{"type":"object","description":"Request to add a rule (a term with antecedents).","required":["term"],"properties":{"antecedents":{"type":"array","items":{"$ref":"#/components/schemas/TermInputDto"},"description":"Antecedent terms (body of the rule)\nThese go into the `when` feature"},"certainty":{"type":"number","format":"double","description":"Certainty factor (default: 1.0)","default":1.0},"term":{"$ref":"#/components/schemas/TermInputDto","description":"The conclusion term (head of the rule)"}}},"AddRuleResponse":{"type":"object","description":"Response after adding a rule.","required":["term"],"properties":{"term":{"$ref":"#/components/schemas/PsiTermDto","description":"The created rule term"}}},"AddSymbolRequest":{"type":"object","description":"Request to add a symbol to a module","required":["session_id","module_name","symbol"],"properties":{"module_name":{"type":"string"},"session_id":{"type":"string"},"symbol":{"$ref":"#/components/schemas/SymbolDto"}}},"AddSymbolResponse":{"type":"object","description":"Response after adding a symbol","required":["module_name","symbol_name","success"],"properties":{"module_name":{"type":"string"},"success":{"type":"boolean"},"symbol_name":{"type":"string"}}},"AgentBeliefDto":{"type":"object","description":"Belief state DTO.","required":["term_id","sort_name","confidence","source"],"properties":{"confidence":{"type":"number","format":"double","description":"Confidence (0.0 to 1.0)"},"features":{"type":"object","description":"Features as key-value pairs (excluding confidence and source)","additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"propertyNames":{"type":"string"}},"sort_name":{"type":"string","description":"Sort name of the belief"},"source":{"type":"string","description":"Source"},"term_id":{"type":"string","format":"uuid","description":"Belief term ID"}}},"AgentConfigDto":{"type":"object","description":"Agent configuration DTO.","properties":{"belief_confidence_threshold":{"type":"number","format":"double","description":"Minimum confidence threshold for beliefs","default":0.5},"enable_learning":{"type":"boolean","description":"Enable learning from outcomes","default":true},"max_belief_history":{"type":"integer","description":"Maximum belief history to retain","default":100,"minimum":0},"max_goals_per_cycle":{"type":"integer","description":"Maximum number of goals to pursue per cycle","default":3,"minimum":0}}},"AgentEvent":{"oneOf":[{"type":"object","description":"KB change notification","required":["term_id","change_type","sort","type"],"properties":{"change_type":{"$ref":"#/components/schemas/KbChangeType","description":"Type of change"},"sort":{"type":"string","description":"Sort of the term"},"term_id":{"type":"string","format":"uuid","description":"Term ID that changed"},"type":{"type":"string","enum":["kb_change"]}}},{"type":"object","description":"HITL review request","required":["review_id","action_sort","confidence","type"],"properties":{"action_sort":{"type":"string","description":"Action sort"},"confidence":{"type":"number","format":"double","description":"Confidence level"},"deadline":{"type":["string","null"],"description":"Optional deadline"},"review_id":{"type":"string","format":"uuid","description":"Review ID"},"type":{"type":"string","enum":["hitl_request"]}}},{"type":"object","description":"Cognitive cycle complete","required":["agent_id","actions_executed","beliefs_updated","pending_reviews","type"],"properties":{"actions_executed":{"type":"integer","description":"Number of actions executed","minimum":0},"agent_id":{"type":"string","format":"uuid","description":"Agent ID"},"beliefs_updated":{"type":"integer","description":"Number of beliefs updated","minimum":0},"pending_reviews":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Any pending reviews from this cycle"},"type":{"type":"string","enum":["cycle_complete"]}}},{"type":"object","description":"Attention shift notification","required":["to","priority","type"],"properties":{"from":{"type":["string","null"],"format":"uuid","description":"Previous focus (if any)"},"priority":{"type":"number","format":"double","description":"Priority of new focus"},"to":{"type":"string","format":"uuid","description":"New focus"},"type":{"type":"string","enum":["attention_shift"]}}},{"type":"object","description":"Goal completed notification","required":["goal_id","success","type"],"properties":{"goal_id":{"type":"string","format":"uuid","description":"Goal ID"},"result":{"type":["string","null"],"description":"Optional result message"},"success":{"type":"boolean","description":"Success or failure"},"type":{"type":"string","enum":["goal_completed"]}}},{"type":"object","description":"Impasse detected notification","required":["impasse_type","blocked_goal","recovery_suggestions","type"],"properties":{"blocked_goal":{"type":"string","format":"uuid","description":"Blocked goal ID"},"impasse_type":{"type":"string","description":"Type of impasse"},"recovery_suggestions":{"type":"array","items":{"type":"string"},"description":"Suggested recovery actions"},"type":{"type":"string","enum":["impasse_detected"]}}},{"type":"object","description":"Connection established confirmation","required":["agent_id","timestamp","type"],"properties":{"agent_id":{"type":"string","format":"uuid","description":"Agent ID connected to"},"timestamp":{"type":"string","description":"Server timestamp"},"type":{"type":"string","enum":["connected"]}}},{"type":"object","description":"Heartbeat for connection keep-alive","required":["timestamp","type"],"properties":{"timestamp":{"type":"string","description":"Server timestamp"},"type":{"type":"string","enum":["heartbeat"]}}},{"type":"object","description":"Error notification","required":["code","message","type"],"properties":{"code":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Error message"},"type":{"type":"string","enum":["error"]}}}],"description":"Real-time agent event pushed via WebSocket."},"AgentGoalDto":{"type":"object","description":"Goal state DTO.","required":["term_id","status","priority","attempts"],"properties":{"attempts":{"type":"integer","description":"Number of attempts","minimum":0},"features":{"type":"object","description":"User-facing features (excluding internal: agent_id, status, priority, attempts, goal_sort, confidence, source, when)","additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"propertyNames":{"type":"string"}},"goal_sort":{"type":["string","null"],"description":"Sort name of the goal (e.g. \"tech_conference_plan\")"},"priority":{"type":"integer","format":"int32","description":"Priority"},"status":{"type":"string","description":"Goal status"},"term_id":{"type":"string","format":"uuid","description":"Goal term ID"}}},"AgentInput":{"type":"object","description":"A single agent's static properties.","required":["id","max_assignments"],"properties":{"id":{"type":"string","description":"Caller-chosen identifier. Must be unique within the request."},"max_assignments":{"type":"integer","format":"int32","description":"Maximum number of slots this agent may be assigned across the\nfull horizon.","minimum":0},"restricted_to_shift":{"type":["integer","null"],"description":"When present, the agent may only be assigned to this shift\nindex (all other shifts become unavailable).","minimum":0},"roles":{"type":"array","items":{"type":"string"},"description":"Role tags this agent carries (e.g. `\"icu\"`, `\"senior\"`). Used\nto satisfy per-role minimum-demand constraints."},"unavailable_days":{"type":"array","items":{"type":"integer","minimum":0},"description":"Day indices on which the agent is unavailable for any shift."}}},"AgentStateDto":{"type":"object","description":"Agent state DTO.","required":["agent_id","name","goals","beliefs","has_pending_goals"],"properties":{"agent_id":{"type":"string","format":"uuid","description":"Agent ID"},"beliefs":{"type":"array","items":{"$ref":"#/components/schemas/AgentBeliefDto"},"description":"Current beliefs"},"goals":{"type":"array","items":{"$ref":"#/components/schemas/AgentGoalDto"},"description":"Current goals"},"has_pending_goals":{"type":"boolean","description":"Whether agent has pending goals"},"name":{"type":"string","description":"Agent name"}}},"AgentSubVerdictDto":{"type":"object","description":"Per-agent sub-verdict for multi-agent systems (Gap 4).\n\nAttributes verification results to specific agents in multi-agent trajectories\n(CrewAI, AutoGen, OpenAI Agents SDK).","required":["agent_id","step_indices","verdict","score"],"properties":{"agent_id":{"type":"string","description":"Agent identifier"},"agent_name":{"type":["string","null"],"description":"Human-readable agent name (if available)"},"score":{"type":"number","format":"double","description":"Per-agent aggregated score (0.0-1.0)"},"step_indices":{"type":"array","items":{"type":"integer","minimum":0},"description":"Indices of trajectory steps attributed to this agent"},"verdict":{"type":"string","description":"Per-agent verdict: \"safe\", \"unsafe\", \"partial\", or \"residuated\""}}},"AlignmentStatsDto":{"type":"object","description":"Statistics for source text alignment quality","required":["entities_aligned_exact","entities_aligned_fuzzy","entities_aligned_lesser","entities_unaligned","entities_filtered_by_alignment","avg_fuzzy_ratio"],"properties":{"avg_fuzzy_ratio":{"type":"number","format":"double","description":"Average fuzzy match ratio for fuzzy-aligned entities"},"entities_aligned_exact":{"type":"integer","description":"Number of entities with exact source text match","minimum":0},"entities_aligned_fuzzy":{"type":"integer","description":"Number of entities with fuzzy source text match","minimum":0},"entities_aligned_lesser":{"type":"integer","description":"Number of entities with lesser (partial) source text match","minimum":0},"entities_filtered_by_alignment":{"type":"integer","description":"Number of entities filtered out by alignment quality gate","minimum":0},"entities_unaligned":{"type":"integer","description":"Number of entities that could not be aligned to source text","minimum":0}}},"AnalyzeDocumentsRequestDto":{"type":"object","required":["documents"],"properties":{"documents":{"type":"array","items":{"$ref":"#/components/schemas/DocumentInputDto"}},"include_fix_suggestions":{"type":"boolean"},"include_proof_traces":{"type":"boolean"},"max_rules":{"type":"integer","minimum":0},"rule_sort_filter":{"type":"array","items":{"type":"string"}}}},"AppendAuditEntryRequest":{"type":"object","required":["event_type","action","detail"],"properties":{"action":{"type":"string"},"conversation_id":{"type":["string","null"]},"detail":{"type":"string"},"event_type":{"type":"string"},"message_id":{"type":["string","null"]},"metadata":{}}},"AppendResiduationsRequest":{"type":"object","description":"Request to append residuations during unification","required":["session_id","target_term_id","source_term_id"],"properties":{"session_id":{"type":"string"},"source_term_id":{"type":"string"},"target_term_id":{"type":"string"}}},"AppendResiduationsResponse":{"type":"object","description":"Response after appending","required":["target_term_id","appended_count","total_residuations"],"properties":{"appended_count":{"type":"integer","minimum":0},"target_term_id":{"type":"string"},"total_residuations":{"type":"integer","minimum":0}}},"ApplyCurriedRequest":{"type":"object","description":"Request to apply arguments to a curried function","required":["curried_id","arguments"],"properties":{"arguments":{"type":"array","items":{"$ref":"#/components/schemas/PositionalArgumentDto"}},"curried_id":{"type":"string"}}},"ApplyCurriedResponse":{"oneOf":[{"type":"object","required":["status","result","all_arguments"],"properties":{"all_arguments":{"type":"array","items":{"$ref":"#/components/schemas/PositionalArgumentDto"}},"result":{"$ref":"#/components/schemas/ExecutionValueDto"},"status":{"type":"string","enum":["fully_applied"]}}},{"type":"object","required":["status","curried_id","remaining_count","missing_positions"],"properties":{"curried_id":{"type":"string"},"missing_positions":{"type":"array","items":{"type":"integer","minimum":0}},"remaining_count":{"type":"integer","minimum":0},"status":{"type":"string","enum":["still_curried"]}}},{"type":"object","required":["status","reason"],"properties":{"reason":{"type":"string"},"status":{"type":"string","enum":["cannot_curry"]}}}],"title":"ApplyCurriedResponse","description":"Response after applying arguments to a curried function. Discriminated by the 'status' field. Variants: fully_applied, still_curried, cannot_curry.","discriminator":{"propertyName":"status"}},"ApplySnapshotResponse":{"type":"object","description":"Response for the apply (restore) snapshot endpoint.","required":["message","snapshot_id","snapshot_name","source_tenant_id","target_tenant_id","tables_restored","rows_restored","inference_state_rebuilt","sorts_restored"],"properties":{"inference_state_rebuilt":{"type":"boolean","description":"Whether the in-memory inference state was rebuilt."},"message":{"type":"string","description":"Confirmation message."},"rows_restored":{"type":"integer","description":"Total number of rows inserted across all tables.","minimum":0},"snapshot_id":{"type":"string","description":"ID of the applied snapshot."},"snapshot_name":{"type":"string","description":"Name of the applied snapshot."},"sorts_restored":{"type":"integer","description":"Number of sorts restored to the global hierarchy.","minimum":0},"source_tenant_id":{"type":"string","description":"The original tenant ID the snapshot was captured from."},"tables_restored":{"type":"integer","description":"Number of tables that had data restored.","minimum":0},"target_tenant_id":{"type":"string","description":"The target tenant whose data was restored."}}},"ApproveActionRequest":{"type":"object","description":"Request to approve an action for execution","required":["review_id"],"properties":{"notes":{"type":["string","null"],"description":"Optional notes about the approval"},"review_id":{"type":"string","format":"uuid","description":"The review ID to approve"}}},"ApproveEntityRequest":{"type":"object","description":"Request to approve an entity as-is","required":["review_id"],"properties":{"notes":{"type":["string","null"],"description":"Optional notes about the approval"},"review_id":{"type":"string","format":"uuid","description":"The review ID to approve"}}},"ApproveLearnedSimilarityRequest":{"type":"object","description":"Request to approve a learned similarity","required":["sort1_id","sort2_id"],"properties":{"sort1_id":{"type":"string","format":"uuid","description":"ID of the first sort"},"sort2_id":{"type":"string","format":"uuid","description":"ID of the second sort"}}},"ApproveLearnedSimilarityResponse":{"type":"object","description":"Response for approve operation","required":["success","message","degree"],"properties":{"degree":{"type":"number","format":"double","description":"The approved degree"},"message":{"type":"string"},"success":{"type":"boolean"}}},"ArchitectureInfoDto":{"type":"object","description":"Architecture information for the derived layer.","required":["parameters","sort_count","embedding_dim","constraint_satisfied"],"properties":{"constraint_satisfied":{"type":"boolean"},"embedding_dim":{"type":"integer","minimum":0},"parameters":{"type":"integer","minimum":0},"sort_count":{"type":"integer","minimum":0}}},"ArithValueDto":{"oneOf":[{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["integer"]},"value":{"type":"integer","format":"int64"}}},{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["real"]},"value":{"type":"number","format":"double"}}},{"type":"object","description":"Reference to an uninstantiated term","required":["term_id","type"],"properties":{"term_id":{"type":"string"},"type":{"type":"string","enum":["term_ref"]}}}],"description":"Arithmetic value (integer or real)"},"ArithmeticConstraintDto":{"oneOf":[{"type":"object","required":["op","left","right","constraint_type"],"properties":{"constraint_type":{"type":"string","enum":["relation"]},"left":{"$ref":"#/components/schemas/ArithmeticExprDto"},"op":{"$ref":"#/components/schemas/RelOpDto"},"right":{"$ref":"#/components/schemas/ArithmeticExprDto"}}},{"type":"object","required":["variable","domain","constraint_type"],"properties":{"constraint_type":{"type":"string","enum":["domain"]},"domain":{"type":"array","items":{"type":"integer","format":"int64"}},"variable":{"type":"string"}}}],"description":"DTO for arithmetic constraints"},"ArithmeticExprDto":{"type":"object","title":"ArithmeticExprDto","description":"Arithmetic expression: Constant {value}, Variable {name}, or BinaryOp {op, left, right}"},"ArithmeticRecursionOpDto":{"type":"string","description":"DTO for arithmetic recursion operation.","enum":["multiplication","addition","accumulation","subtraction","power"]},"ArtifactDto":{"type":"object","description":"A generated artifact in the response.","required":["modality","label","content","provenance"],"properties":{"content":{"type":"string","description":"The generated content (text for text modality)."},"label":{"type":"string","description":"The artifact label (e.g., \"Generated text document\")."},"modality":{"type":"string","description":"The modality of the generated artifact."},"provenance":{"type":"array","items":{"$ref":"#/components/schemas/ProvenanceDto"},"description":"Provenance map tracing each citation back to a source fact."}}},"AscRequest":{"type":"object","description":"Request for asc (character to ASCII code)","required":["character"],"properties":{"character":{"type":"string"}}},"AscResponse":{"type":"object","description":"Response from asc","required":["code"],"properties":{"code":{"type":"integer","format":"int64"}}},"AssembleContextRequestDto":{"type":"object","description":"Request DTO for context assembly","required":["query","concept_sort_id"],"properties":{"concept_sort_id":{"type":"string","format":"uuid","description":"Sort ID for concept terms to search within"},"feature_config":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/FeatureConfigDto","description":"Feature configuration for the domain (optional, uses defaults)"}]},"include_dependents":{"type":"boolean","description":"Include dependent concepts in graph traversal (default: true)"},"include_hierarchy":{"type":"boolean","description":"Include hierarchy summary (default: true)"},"include_prerequisites":{"type":"boolean","description":"Include prerequisite concepts in graph traversal (default: true)"},"include_related":{"type":"boolean","description":"Include related concepts via lateral exploration (default: true)"},"include_sources":{"type":"boolean","description":"Include source text excerpts from provenance (default: true)"},"max_concepts":{"type":"integer","description":"Maximum number of primary concepts to retrieve (default: 10)","minimum":0},"max_tokens":{"type":"integer","description":"Maximum tokens for the assembled context (default: 4000)","minimum":0},"min_similarity":{"type":"number","format":"double","description":"Minimum similarity score for fuzzy search (0.0-1.0, default: 0.7)"},"output_format":{"$ref":"#/components/schemas/OutputFormatDto","description":"Output format for the rendered context (default: \"yaml\")"},"query":{"type":"string","description":"Query text to search for relevant concepts"}}},"AssembleContextResponseDto":{"type":"object","description":"Response DTO for context assembly","required":["concepts","relations","source_excerpts","token_counts","rendered","stats","citations"],"properties":{"citations":{"type":"array","items":{"$ref":"#/components/schemas/CitationMarkerDto"},"description":"Citation markers generated from source provenance"},"concepts":{"type":"array","items":{"$ref":"#/components/schemas/AssembledConceptDto"},"description":"Assembled concepts with features and relevance scores"},"hierarchy_summary":{"type":["string","null"],"description":"Hierarchy summary (if included and within budget)"},"relations":{"type":"array","items":{"$ref":"#/components/schemas/AssembledRelationDto"},"description":"Relations between included concepts"},"rendered":{"type":"string","description":"Pre-rendered context in the requested format"},"source_excerpts":{"type":"array","items":{"$ref":"#/components/schemas/SourceExcerptDto"},"description":"Source text excerpts with provenance"},"stats":{"$ref":"#/components/schemas/RetrievalStatsDto","description":"Retrieval and assembly statistics"},"token_counts":{"$ref":"#/components/schemas/AssemblyTokenCountsDto","description":"Token counts for each section"}}},"AssembledConceptDto":{"type":"object","description":"Assembled concept DTO","required":["name","sort_name","features","relevance"],"properties":{"features":{"type":"object","additionalProperties":{"type":"string"},"propertyNames":{"type":"string"}},"name":{"type":"string"},"relevance":{"type":"number","format":"double"},"sort_name":{"type":"string"}}},"AssembledRelationDto":{"type":"object","description":"Assembled relation DTO","required":["source","relation","target","confidence"],"properties":{"confidence":{"type":"number","format":"double"},"relation":{"type":"string"},"source":{"type":"string"},"target":{"type":"string"}}},"AssemblyTokenCountsDto":{"type":"object","description":"Token counts DTO","required":["concepts","relations","sources","hierarchy","total","remaining"],"properties":{"concepts":{"type":"integer","minimum":0},"hierarchy":{"type":"integer","minimum":0},"relations":{"type":"integer","minimum":0},"remaining":{"type":"integer","minimum":0},"sources":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0}}},"AssertRuleRequest":{"type":"object","description":"Request to assert a rule (add to knowledge base)","required":["head"],"properties":{"assert_first":{"type":"boolean","description":"If true, add at beginning (high priority); if false, add at end"},"body":{"type":"array","items":{"$ref":"#/components/schemas/RuleClauseDto"},"description":"The rule body (conditions) - empty for facts"},"head":{"$ref":"#/components/schemas/RuleClauseDto","description":"The rule head (conclusion)"}}},"AssertRuleResponse":{"type":"object","description":"Response after asserting a rule","required":["rule_id","rule_count"],"properties":{"rule_count":{"type":"integer","minimum":0},"rule_id":{"type":"string"}}},"AssignValueDto":{"oneOf":[{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["integer"]},"value":{"type":"integer","format":"int64"}}},{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["real"]},"value":{"type":"number","format":"double"}}},{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["string"]},"value":{"type":"string"}}},{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["boolean"]},"value":{"type":"boolean"}}},{"type":"object","required":["term_id","type"],"properties":{"term_id":{"type":"string"},"type":{"type":"string","enum":["term_ref"]}}}],"description":"Value for assignment"},"AssignmentDto":{"type":"object","description":"One entry per `(agent_id, day, shift)` in the input grid.","required":["agent_id","day","shift","status","roles"],"properties":{"agent_id":{"type":"string","description":"Echoes the `id` from [`AgentInput`]."},"day":{"type":"integer","minimum":0},"roles":{"type":"array","items":{"type":"string"},"description":"Roles the agent can or must fill at this cell.\n\n- When `status = confirmed_true`: the role(s) the agent\n must fill at this cell. Usually a single entry.\n- When `status = free`: the set of roles the agent could\n fill across valid schedules that place them here.\n- When `status = confirmed_false`: always empty.\n\nThe reserved string `\"any\"` denotes routing through the\nunroled sub-slot pool (i.e. the agent is \"just there\",\nnot counting toward any role minimum at this slot)."},"shift":{"type":"integer","minimum":0},"status":{"$ref":"#/components/schemas/AssignmentStatusDto"}}},"AssignmentStatusDto":{"type":"string","description":"Per-cell feasibility classification.\n\nEvery cell in the input grid is classified as exactly one of these.","enum":["confirmed_true","confirmed_false","free"]},"AsyncIngestRdfResponse":{"type":"object","description":"Response from RDF ingestion (async mode, HTTP 202).\n\nThe work runs in a background tokio task. Poll the `status_url` to track\nprogress and discover the final result.","required":["session_id","document_id","status","status_url"],"properties":{"document_id":{"type":"string","format":"uuid"},"session_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"status_url":{"type":"string"}}},"AttentionTargetDto":{"oneOf":[{"type":"object","description":"Focus on a goal","required":["term_id","type"],"properties":{"term_id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["Goal"]}}},{"type":"object","description":"Focus on a belief","required":["term_id","type"],"properties":{"term_id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["Belief"]}}},{"type":"object","description":"Focus on a perception (KB change)","required":["change_type","details","type"],"properties":{"change_type":{"type":"string"},"details":{"type":"string"},"type":{"type":"string","enum":["Perception"]}}}],"description":"Attention target DTO."},"AttestationDto":{"type":"object","description":"Individual constraint attestation within a certificate.","required":["constraint_id","constraint_type","satisfied","verification_details","constraint_hash"],"properties":{"constraint_hash":{"type":"string","description":"Hash of the constraint definition (for verification)"},"constraint_id":{"type":"string","description":"Constraint identifier (e.g., layer name)"},"constraint_type":{"type":"string","description":"Constraint type (e.g., \"temporal\", \"resource\", \"tool_contract\")"},"satisfied":{"type":"boolean","description":"Whether the constraint is satisfied"},"verification_details":{"type":"string","description":"Human-readable verification description"}}},"AuditEntryDto":{"type":"object","required":["id","timestamp","event_type","action","detail","metadata","hash_previous","hash_current"],"properties":{"action":{"type":"string"},"conversation_id":{"type":["string","null"]},"detail":{"type":"string"},"event_type":{"type":"string"},"hash_current":{"type":"string"},"hash_previous":{"type":"string"},"id":{"type":"string"},"message_id":{"type":["string","null"]},"metadata":{},"tenant_id":{"type":"string"},"timestamp":{"type":"string"},"user_id":{"type":["string","null"]}}},"AugmentationTargetDto":{"type":"object","description":"An augmentation target identified by calibration.","required":["sort_id","sort_name","priority","reason","recommended_examples"],"properties":{"feature_name":{"type":["string","null"],"description":"Specific feature (if feature-level target)."},"priority":{"type":"number","format":"double","description":"Priority score (higher = more urgent)."},"reason":{"type":"string","description":"Reason for augmentation need."},"recommended_examples":{"type":"integer","description":"Recommended number of additional examples.","minimum":0},"sort_id":{"type":"string","format":"uuid","description":"Sort UUID."},"sort_name":{"type":"string","description":"Sort name."}}},"BacktrackRequest":{"type":"object","description":"Request to backtrack to a marker or most recent choice point","properties":{"marker_index":{"type":["integer","null"],"description":"If provided, backtrack to this marker; otherwise backtrack to most recent","minimum":0}}},"BacktrackResponse":{"type":"object","description":"Response with undone operations","required":["undone_count","undone_entries","remaining_trail_length","remaining_choice_points"],"properties":{"remaining_choice_points":{"type":"integer","minimum":0},"remaining_trail_length":{"type":"integer","minimum":0},"undone_count":{"type":"integer","minimum":0},"undone_entries":{"type":"array","items":{"$ref":"#/components/schemas/TrailEntryDto"}}}},"BacktrackTermStoreRequest":{"type":"object","description":"Request to backtrack to a marker","required":["marker_index"],"properties":{"marker_index":{"type":"integer","minimum":0}}},"BacktrackTermStoreResponse":{"type":"object","description":"Response after backtracking","required":["success","undone_entries","current_trail_length"],"properties":{"current_trail_length":{"type":"integer","minimum":0},"success":{"type":"boolean"},"undone_entries":{"type":"integer","minimum":0}}},"BacktrackableAssignRequest":{"type":"object","description":"Request for backtrackable assignment","required":["session_id","term_id","feature_name","new_value"],"properties":{"feature_name":{"type":"string"},"new_value":{"$ref":"#/components/schemas/AssignValueDto"},"session_id":{"type":"string"},"term_id":{"type":"string"}}},"BacktrackableAssignResponse":{"type":"object","description":"Response from backtrackable assignment","required":["term_id","feature_name","trail_entry_added"],"properties":{"feature_name":{"type":"string"},"previous_value":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/AssignValueDto"}]},"term_id":{"type":"string"},"trail_entry_added":{"type":"boolean"}}},"BackwardChainRequest":{"type":"object","description":"Request for backward chaining.\n\n# TRUE HOMOICONICITY (Aït-Kaci's OSF/LIFE Vision)\n\nPrefer embedding constraints directly in the goal term using `ConstrainedVariable`:\n\n```json\n{\n \"goal\": {\n \"sort_id\": \"employment_sort_id\",\n \"features\": {\n \"person\": {\"Variable\": {\"name\": \"?Person\"}},\n \"valid_from\": {\n \"ConstrainedVariable\": {\n \"name\": \"?StartTime\",\n \"constraint\": {\n \"sort_id\": \"guard_constraint_sort_id\",\n \"features\": {\"op\": \"lt\", \"right\": 1583020800000}\n }\n }\n }\n }\n }\n}\n```\n\nThis is the TRUE HOMOICONIC way: constraints ARE Ψ-terms embedded in the structure.","properties":{"constraints":{"type":"array","items":{"$ref":"#/components/schemas/ConstraintInputDto"},"description":"**DEPRECATED**: Use embedded constraints via `ConstrainedVariable` instead.\n\nThis array is kept for backward compatibility and Allen constraints.\nFor guard constraints (lt, gt, etc.), prefer `ConstrainedVariable` in the goal.\nFor Allen constraints, use this array until embedded Allen support is added.\n\nInternally converted to Ψ-term constraints for TRUE HOMOICONICITY."},"goal":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/TermInputDto","description":"The goal to prove (as a term).\nEither `goal` or `goal_id` must be provided, but not both.\n\nUse `ConstrainedVariable` in features for TRUE HOMOICONICITY."}]},"goal_id":{"type":["string","null"],"format":"uuid","description":"Load a previously saved goal by ID (TRUE HOMOICONICITY).\nEither `goal` or `goal_id` must be provided, but not both."},"max_depth":{"type":"integer","description":"Maximum proof depth to prevent infinite recursion in complex knowledge bases.\nLower values improve performance but may miss deeper proofs.\nDefault: 100","default":100,"minimum":0},"max_solutions":{"type":"integer","description":"Maximum number of solutions","default":10,"minimum":0},"min_certainty":{"type":"number","format":"double","description":"Minimum certainty threshold","default":0.0},"open_world":{"type":"boolean","description":"Use open-world semantics (default: false = closed-world backward chaining).\n\nWhen true, missing evidence is treated as unknown (residuated) rather than\nfalse. Rules are evaluated by checking which body antecedents have matching\nfacts, producing partial solutions ranked by evidence ratio.","default":false},"save_goal":{"type":"boolean","description":"Persist the goal after creation for later reuse (TRUE HOMOICONICITY)."},"timeout_ms":{"type":["integer","null"],"format":"int64","description":"Wall-clock timeout in milliseconds. The proof search stops after this\nduration and returns whatever solutions have been found so far.\nDefault: 30000 (30 seconds). Set to 0 or null to disable.","default":30000,"minimum":0}}},"BackwardChainResponse":{"type":"object","description":"Response for backward chaining.","required":["solutions","query_time_ms"],"properties":{"goal_id":{"type":["string","null"],"format":"uuid","description":"TRUE HOMOICONICITY: Goal ID if the goal was saved (when save_goal=true)"},"query_time_ms":{"type":"integer","description":"Query time in milliseconds","minimum":0},"solutions":{"type":"array","items":{"$ref":"#/components/schemas/SolutionDto"},"description":"Solutions found"}}},"BatchCopyRequest":{"type":"object","description":"Request for batch copy","required":["session_id","copies"],"properties":{"copies":{"type":"array","items":{"$ref":"#/components/schemas/SingleCopyRequest"}},"session_id":{"type":"string"}}},"BatchCopyResponse":{"type":"object","description":"Response from batch copy","required":["copies"],"properties":{"copies":{"type":"array","items":{"$ref":"#/components/schemas/CopyResultDto"}}}},"BatchSortCompareRequest":{"type":"object","description":"Request for batch sort comparison","required":["tenant_id","comparisons"],"properties":{"comparisons":{"type":"array","items":{"$ref":"#/components/schemas/SortComparisonDto"}},"tenant_id":{"type":"string","format":"uuid"}}},"BatchSortCompareResponse":{"type":"object","description":"Response from batch sort comparison","required":["results"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/SortCompareResultDto"}}}},"BatchStringCompareRequest":{"type":"object","description":"Request for batch string comparison (multiple comparisons at once)","required":["comparisons"],"properties":{"comparisons":{"type":"array","items":{"$ref":"#/components/schemas/StringComparePredicateRequest"},"description":"List of comparisons to perform"}}},"BatchStringCompareResponse":{"type":"object","description":"Response from batch string comparison","required":["results","all_succeeded"],"properties":{"all_succeeded":{"type":"boolean","description":"True if all comparisons succeeded"},"results":{"type":"array","items":{"$ref":"#/components/schemas/StringComparePredicateResponse"},"description":"Results for each comparison"}}},"BayesianEffectDto":{"oneOf":[{"type":"object","required":["mean","std_dev","shape"],"properties":{"mean":{"type":"number","format":"double"},"shape":{"type":"string","enum":["gaussian"]},"std_dev":{"type":"number","format":"double"}}},{"type":"object","required":["a","b","c","shape"],"properties":{"a":{"type":"number","format":"double"},"b":{"type":"number","format":"double"},"c":{"type":"number","format":"double"},"shape":{"type":"string","enum":["triangular"]}}},{"type":"object","required":["a","b","c","d","shape"],"properties":{"a":{"type":"number","format":"double"},"b":{"type":"number","format":"double"},"c":{"type":"number","format":"double"},"d":{"type":"number","format":"double"},"shape":{"type":"string","enum":["trapezoidal"]}}},{"type":"object","required":["midpoint","steepness","shape"],"properties":{"midpoint":{"type":"number","format":"double"},"shape":{"type":"string","enum":["sigmoid"]},"steepness":{"type":"number","format":"double"}}},{"type":"object","required":["center","width","slope","shape"],"properties":{"center":{"type":"number","format":"double"},"shape":{"type":"string","enum":["bell"]},"slope":{"type":"number","format":"double"},"width":{"type":"number","format":"double"}}},{"type":"object","required":["midpoint1","steepness1","midpoint2","steepness2","shape"],"properties":{"midpoint1":{"type":"number","format":"double"},"midpoint2":{"type":"number","format":"double"},"shape":{"type":"string","enum":["sigmoid_difference"]},"steepness1":{"type":"number","format":"double"},"steepness2":{"type":"number","format":"double"}}},{"type":"object","required":["mean1","std_dev1","mean2","std_dev2","shape"],"properties":{"mean1":{"type":"number","format":"double"},"mean2":{"type":"number","format":"double"},"shape":{"type":"string","enum":["gaussian_product"]},"std_dev1":{"type":"number","format":"double"},"std_dev2":{"type":"number","format":"double"}}},{"type":"object","required":["midpoint1","steepness1","midpoint2","steepness2","shape"],"properties":{"midpoint1":{"type":"number","format":"double"},"midpoint2":{"type":"number","format":"double"},"shape":{"type":"string","enum":["sigmoid_product"]},"steepness1":{"type":"number","format":"double"},"steepness2":{"type":"number","format":"double"}}},{"type":"object","required":["center","width","shape"],"properties":{"center":{"type":"number","format":"double"},"shape":{"type":"string","enum":["cosine"]},"width":{"type":"number","format":"double"}}},{"type":"object","required":["center","width","shape"],"properties":{"center":{"type":"number","format":"double"},"shape":{"type":"string","enum":["spike"]},"width":{"type":"number","format":"double"}}},{"type":"object","required":["center","gamma","shape"],"properties":{"center":{"type":"number","format":"double"},"gamma":{"type":"number","format":"double"},"shape":{"type":"string","enum":["cauchy"]}}},{"type":"object","required":["a","b","shape"],"properties":{"a":{"type":"number","format":"double"},"b":{"type":"number","format":"double"},"shape":{"type":"string","enum":["s_shape"]}}},{"type":"object","required":["a","b","shape"],"properties":{"a":{"type":"number","format":"double"},"b":{"type":"number","format":"double"},"shape":{"type":"string","enum":["z_shape"]}}},{"type":"object","required":["a","b","c","d","shape"],"properties":{"a":{"type":"number","format":"double"},"b":{"type":"number","format":"double"},"c":{"type":"number","format":"double"},"d":{"type":"number","format":"double"},"shape":{"type":"string","enum":["pi_shape"]}}},{"type":"object","required":["points","shape"],"properties":{"points":{"type":"array","items":{"type":"array","items":false,"prefixItems":[{"type":"number","format":"double"},{"type":"number","format":"double"}]}},"shape":{"type":"string","enum":["piecewise_linear"]}}}],"description":"FuzzyNumber shape for Bayesian prediction response."},"BayesianPredictRequest":{"type":"object","description":"Request for Bayesian prediction (merges priors + data).\n\nThis endpoint:\n1. Runs fuzzy_prove to find all matching facts (priors + learned data)\n2. Extracts FuzzyNumber values from the specified variable binding\n3. Merges them using Bayesian conjugate update (for Gaussians)\n4. Returns the merged posterior distribution","required":["effect_var"],"properties":{"conformal":{"type":["number","null"],"format":"double","description":"Optional conformal coverage (e.g., 0.9 for 90% coverage)\nIf set, std_dev is inflated by the empirical quantile"},"effect_var":{"type":"string","description":"Name of the variable that holds the FuzzyNumber effect"},"goal":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/TermInputDto","description":"Goal to prove (should bind a FuzzyNumber variable).\nEither `goal` or `goal_id` must be provided, but not both."}]},"goal_id":{"type":["string","null"],"format":"uuid","description":"Load a previously saved goal by ID.\nEither `goal` or `goal_id` must be provided, but not both."},"max_depth":{"type":"integer","description":"Maximum proof depth","default":100,"minimum":0},"min_degree":{"type":"number","format":"double","description":"Minimum degree threshold"},"robust":{"type":"boolean","description":"Use robust aggregation (Student-t/Huber) to downweight outliers","default":false},"save_goal":{"type":"boolean","description":"If true, save the goal for later reuse (returns goal_id in response).\nOnly applies when `goal` is provided (not when loading via goal_id)."}}},"BayesianPredictResponse":{"type":"object","description":"Response from Bayesian prediction.","required":["success","degree","sources_merged","proof_trace","query_time_ms"],"properties":{"degree":{"type":"number","format":"double","description":"Combined confidence/degree"},"effect":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/BayesianEffectDto","description":"Merged FuzzyNumber (posterior)"}]},"goal_id":{"type":["string","null"],"format":"uuid","description":"TRUE HOMOICONICITY: Goal ID if the goal was saved (when save_goal=true)"},"proof_trace":{"type":"array","items":{"type":"string"},"description":"Proof trace explaining the prediction"},"query_time_ms":{"type":"integer","description":"Query time in milliseconds","minimum":0},"sources_merged":{"type":"integer","description":"Number of sources merged","minimum":0},"success":{"type":"boolean","description":"Whether prediction was successful"}}},"BeliefDto":{"type":"object","description":"Belief DTO representation.\n\nSupports both `sort_name` (human-friendly) and `sort_id` (efficient).\nIf both are provided, `sort_id` takes precedence.","required":["sort"],"properties":{"features":{"type":"object","description":"Features as key-value pairs (raw JSON values)","additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"propertyNames":{"type":"string"}},"sort":{"type":"string","description":"Sort name for the belief (for human-friendly input)\nKept as \"sort\" for backward compatibility with existing clients"},"sort_id":{"type":["string","null"],"format":"uuid","description":"Sort ID (optional, takes precedence over sort name if provided)"}}},"BinaryOperatorDto":{"type":"string","description":"Binary operator for expressions","enum":["Add","Subtract","Multiply","Divide"]},"BindSortRequest":{"type":"object","description":"Request to bind a sort to a SQL table.","required":["sort_name","table_name","source_id","columns"],"properties":{"columns":{"type":"array","items":{"$ref":"#/components/schemas/ColumnMappingDto"},"description":"Column mappings: feature name to column spec."},"key_columns":{"type":"array","items":{"type":"string"},"description":"Primary key column names."},"sort_name":{"type":"string","description":"Sort name to bind."},"source_id":{"type":"string","description":"External source identifier."},"table_name":{"type":"string","description":"SQL table name."}}},"BindSortResponse":{"type":"object","description":"Response from binding a sort to a SQL table.","required":["sort_name","table_name","bound"],"properties":{"bound":{"type":"boolean","description":"Whether the binding was successful."},"sort_name":{"type":"string","description":"Sort name that was bound."},"table_name":{"type":"string","description":"SQL table the sort is bound to."}}},"BindTermRequest":{"type":"object","description":"Request to bind a term in the session","required":["term_id","sort_id"],"properties":{"features":{"type":"array","items":{"$ref":"#/components/schemas/FeatureBindingDto"}},"sort_id":{"type":"string"},"term_id":{"type":"string"}}},"BindTermResponse":{"type":"object","description":"Response after binding a term - includes evaluation results","required":["session_id","tenant_id","trail_length","choice_point_count","bindings_count"],"properties":{"bindings_count":{"type":"integer","minimum":0},"choice_point_count":{"type":"integer","minimum":0},"evaluation_results":{"type":"array","items":{"$ref":"#/components/schemas/GoalEvaluationResultDto"},"description":"Evaluation results for all active goals after this binding"},"session_id":{"type":"string"},"tenant_id":{"type":"string","format":"uuid"},"trail_length":{"type":"integer","minimum":0}}},"BindVariableRequest":{"type":"object","description":"Request to bind a variable to a term","required":["variable_id","target_id"],"properties":{"target_id":{"type":"string"},"variable_id":{"type":"string"}}},"BindVariableResponse":{"type":"object","description":"Response after binding","required":["success","variable_id","bound_to","trail_length"],"properties":{"bound_to":{"type":"string"},"success":{"type":"boolean"},"trail_length":{"type":"integer","minimum":0},"variable_id":{"type":"string"}}},"BindVariablesRequest":{"type":"object","description":"Request to bind variables in a session","required":["bindings"],"properties":{"bindings":{"type":"object","additionalProperties":{"type":"integer","format":"int64"},"propertyNames":{"type":"string"}}}},"BindVariablesResponse":{"type":"object","description":"Response from binding variables","required":["session_id","success","newly_satisfied","satisfied_count","suspended_count","current_bindings","all_satisfied"],"properties":{"all_satisfied":{"type":"boolean"},"current_bindings":{"type":"object","additionalProperties":{"type":"integer","format":"int64"},"propertyNames":{"type":"string"}},"message":{"type":["string","null"]},"newly_satisfied":{"type":"integer","minimum":0},"satisfied_count":{"type":"integer","minimum":0},"session_id":{"type":"string","format":"uuid"},"success":{"type":"boolean"},"suspended_count":{"type":"integer","minimum":0}}},"BindingDto":{"type":"object","description":"A single variable binding in a substitution.\n\nMaps a variable term to its bound value, both represented as UUIDs.","required":["variable_term_id","bound_to_term_id","bound_to_display"],"properties":{"bound_to_display":{"type":"string","description":"Human-readable display of the bound value"},"bound_to_term_id":{"type":"string","format":"uuid","description":"TermId of the bound value"},"variable_name":{"type":["string","null"],"description":"Human-readable variable name (e.g., \"?X\")"},"variable_term_id":{"type":"string","format":"uuid","description":"TermId of the variable"}}},"BindingSummaryDto":{"type":"object","description":"Summary of a single sort-table binding.","required":["sort_id","source_id","table_name","feature_count","key_columns"],"properties":{"feature_count":{"type":"integer","description":"Number of bound features/columns.","minimum":0},"key_columns":{"type":"array","items":{"type":"string"},"description":"Primary key column names."},"sort_id":{"type":"string","description":"Sort ID (UUID string)."},"source_id":{"type":"string","description":"External source identifier."},"table_name":{"type":"string","description":"SQL table name."}}},"BindingsResponse":{"type":"object","description":"Response with current bindings","required":["bindings"],"properties":{"bindings":{"type":"array","items":{"$ref":"#/components/schemas/TermBindingDto"}}}},"BitwiseOperationType":{"type":"string","description":"Bitwise operation types","enum":["and","or","xor","not","left_shift","right_shift"]},"BitwiseRequest":{"type":"object","description":"Request for bitwise operation","required":["session_id","operation","args"],"properties":{"args":{"type":"array","items":{"type":["integer","null"],"format":"int64"},"description":"Arguments (integers, some may be uninstantiated)"},"operation":{"$ref":"#/components/schemas/BitwiseOperationType"},"session_id":{"type":"string"}}},"BitwiseResponse":{"oneOf":[{"type":"object","required":["result","status"],"properties":{"result":{"type":"integer","format":"int64"},"status":{"type":"string","enum":["success"]}}},{"type":"object","required":["term_ids","status"],"properties":{"status":{"type":"string","enum":["residuate"]},"term_ids":{"type":"array","items":{"type":"string"}}}},{"type":"object","required":["reason","status"],"properties":{"reason":{"type":"string"},"status":{"type":"string","enum":["fail"]}}}],"description":"Response from bitwise operation"},"BoundConstraintDto":{"type":"object","description":"API representation of an OSF Bound Constraint\n\nBound constraints enforce relationships between feature values,\nsupporting upper bounds (<=), lower bounds (>=), strict ordering (<),\nand equality (==). They work with path references through nested entities.","required":["constraint_type","target","source_path"],"properties":{"constraint_type":{"type":"string","description":"Constraint type: \"upper\", \"lower\", \"less_than\", \"equal\""},"on_violation":{"type":"string","description":"Action on violation: \"update\" (default), \"fail\", \"warn\", \"residuate\""},"source_path":{"type":"string","description":"Source path (dot-separated) to the value that provides the bound\nExamples: \"termination_date\", \"person.death_date\", \"company.dissolution_date\""},"target":{"type":"string","description":"Target feature name that will be constrained"}}},"BroadcastMessageRequest":{"type":"object","description":"Request to broadcast a message to all agents.","required":["tenant_id","from_agent_id","content"],"properties":{"content":{"$ref":"#/components/schemas/JsonValue","description":"Message content (arbitrary JSON)"},"from_agent_id":{"type":"string","format":"uuid","description":"Sender agent ID"},"priority":{"type":"integer","format":"int64","description":"Priority","default":5},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"}}},"BroadcastMessageResponse":{"type":"object","description":"Response after broadcasting a message.","required":["recipients_count","message_ids","message"],"properties":{"message":{"type":"string","description":"Message"},"message_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Message IDs created"},"recipients_count":{"type":"integer","description":"Number of agents the message was sent to","minimum":0}}},"BuildInfoDto":{"type":"object","description":"Build info DTO","required":["version"],"properties":{"build_timestamp":{"type":["string","null"]},"git_hash":{"type":["string","null"]},"version":{"type":"string"}}},"BuildTaxonomyRequest":{"type":"object","description":"Request: filter an ontology-derived sort set by relevance scores.","required":["target_description","sort_names"],"properties":{"close_ancestors":{"type":"boolean","description":"Whether to close upward through ancestors."},"max_seeds":{"type":"integer","description":"Cap on the number of seeds retained (0 = unbounded).","minimum":0},"scores_by_name":{"type":"object","description":"Per-sort relevance score keyed by sort name (typically produced\nupstream by `SoftRetrievalService`). Absent names default to 0.","additionalProperties":{"type":"number","format":"double"},"propertyNames":{"type":"string"}},"sort_names":{"type":"array","items":{"type":"string"},"description":"The sort names to be treated as the raw ontology projection. Each\nname is resolved against the live `SortHierarchy` of the requesting\ntenant; missing names produce a `NotFound` error response."},"target_description":{"type":"string","description":"Free-text target-dataset description (logged on the response for audit)."},"threshold":{"type":"number","format":"double","description":"Threshold above which a sort becomes a filter seed."}}},"BuildTaxonomyResponse":{"type":"object","description":"Response: a topologically-closed, relevance-filtered taxonomy.","required":["target_description","input_node_count","included_names","seed_names","ancestor_closure_names","retention_ratio","threshold"],"properties":{"ancestor_closure_names":{"type":"array","items":{"type":"string"},"description":"Sort names admitted by ancestor closure (subset of `included_names`)."},"included_names":{"type":"array","items":{"type":"string"},"description":"Sort names retained after filtering."},"input_node_count":{"type":"integer","description":"Total sort names in the input.","minimum":0},"retention_ratio":{"type":"number","format":"double","description":"Ratio |included| / |input|, in [0, 1]."},"seed_names":{"type":"array","items":{"type":"string"},"description":"Sort names whose relevance score crossed the threshold (subset of\n`included_names`)."},"target_description":{"type":"string","description":"Echoes `target_description` for audit."},"threshold":{"type":"number","format":"double","description":"Effective threshold used."}}},"BulkActionReviewResponse":{"type":"object","description":"Response from bulk review actions","required":["success_count","failure_count","succeeded_ids","failed_ids"],"properties":{"failed_ids":{"type":"array","items":{"$ref":"#/components/schemas/FailedReviewDto"},"description":"Review IDs that failed with reasons"},"failure_count":{"type":"integer","description":"Number of reviews that failed","minimum":0},"succeeded_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Review IDs that succeeded"},"success_count":{"type":"integer","description":"Number of reviews successfully processed","minimum":0}}},"BulkAddFactsRequest":{"type":"object","description":"Request to add multiple facts.","required":["facts"],"properties":{"facts":{"type":"array","items":{"$ref":"#/components/schemas/TermInputDto"},"description":"Facts to add"}}},"BulkAddFactsResponse":{"type":"object","description":"Response from bulk fact addition.","required":["facts_added","term_ids"],"properties":{"facts_added":{"type":"integer","description":"Number of facts added","minimum":0},"term_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Created term IDs"}}},"BulkAddRulesRequest":{"type":"object","description":"Request to add multiple rules in bulk.\n\nOptimized for high-throughput insertion when loading game rules,\nknowledge bases, or other scenarios requiring many rules at once.","required":["rules"],"properties":{"rules":{"type":"array","items":{"$ref":"#/components/schemas/AddRuleRequest"},"description":"Rules to add (each rule has head term + antecedents)"}}},"BulkAddRulesResponse":{"type":"object","description":"Response from bulk rule addition.","required":["rules_added","rule_term_ids"],"properties":{"rule_term_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Created rule term IDs"},"rules_added":{"type":"integer","description":"Number of rules added","minimum":0}}},"BulkAddTermsRequest":{"type":"object","description":"Request to bulk add terms\n\nCreates multiple terms in a single operation for efficiency.\nThis is much faster than creating terms one by one when you have many terms.\n\n# Tenant Context\nThe tenant is determined from the `X-Tenant-Id` header.","required":["terms"],"properties":{"terms":{"type":"array","items":{"$ref":"#/components/schemas/CreateTermRequest"},"description":"List of terms to create"}}},"BulkAddTermsResponse":{"type":"object","description":"Response from bulk term addition","required":["terms_added","term_ids","processing_time_ms"],"properties":{"processing_time_ms":{"type":"integer","description":"Processing time in milliseconds","minimum":0},"term_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Created term IDs (in same order as request)"},"terms_added":{"type":"integer","description":"Number of terms created","minimum":0}}},"BulkApproveActionsRequest":{"type":"object","description":"Request to bulk approve multiple reviews","required":["review_ids","reviewed_by"],"properties":{"notes":{"type":["string","null"],"description":"Optional notes for all approvals"},"review_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Review IDs to approve"},"reviewed_by":{"type":"string","format":"uuid","description":"User performing the bulk action"}}},"BulkApproveRequest":{"type":"object","description":"Request to bulk approve multiple reviews","required":["review_ids","reviewed_by"],"properties":{"review_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Review IDs to approve"},"reviewed_by":{"type":"string","format":"uuid","description":"User performing the bulk action"}}},"BulkCreateSortsRequest":{"type":"object","description":"Request to create multiple sorts in bulk\n\n# Tenant Context\nThe tenant is determined from the `X-Tenant-Id` header.","required":["sorts"],"properties":{"sorts":{"type":"array","items":{"$ref":"#/components/schemas/BulkSortDefinition"},"description":"List of sort definitions (will be topologically sorted)"}}},"BulkCreateSortsResponse":{"type":"object","description":"Response for bulk sort creation","required":["created_count","sort_ids"],"properties":{"created_count":{"type":"integer","description":"Number of sorts created","minimum":0},"errors":{"type":"array","items":{"$ref":"#/components/schemas/BulkSortError"},"description":"Any errors encountered (sort name -> error message)"},"sort_ids":{"type":"object","description":"Mapping of sort name -> sort ID","additionalProperties":{"type":"string","format":"uuid"},"propertyNames":{"type":"string"}}}},"BulkFuzzyProveRequest":{"type":"object","description":"Request for bulk fuzzy inference - multiple goals in one HTTP request.\n\nThis dramatically reduces latency by:\n1. Single HTTP round-trip for multiple queries\n2. Shared hierarchy, term store overlay, and rules across all goals","properties":{"goal_ids":{"type":["array","null"],"items":{"type":"string","format":"uuid"},"description":"Array of saved goal IDs to load and prove.\nEither `goals` or `goal_ids` must be provided, but not both."},"goals":{"type":"array","items":{"$ref":"#/components/schemas/TermInputDto"},"description":"Array of goals to prove (each goal is a TermInputDto).\nEither `goals` or `goal_ids` must be provided, but not both."},"max_depth":{"type":"integer","description":"Maximum proof depth (default: 10)","default":100,"minimum":0},"max_solutions":{"type":"integer","description":"Maximum solutions per goal (default: 100)","default":10,"minimum":0},"min_degree":{"type":"number","format":"double","description":"Minimum truth degree for results (default: 0.0)","default":0.0},"save_goals":{"type":"boolean","description":"If true, save all goals for later reuse (returns goal_ids in response).\nOnly applies when `goals` is provided (not when loading via goal_ids)."},"tnorm":{"type":"string","description":"T-norm strategy: \"Min\", \"Product\", or \"Lukasiewicz\" (default: \"Min\")","default":"min"}}},"BulkFuzzyProveResponse":{"type":"object","description":"Response for bulk fuzzy inference.","required":["results","total_time_ms"],"properties":{"goal_ids":{"type":["array","null"],"items":{"type":"string","format":"uuid"},"description":"TRUE HOMOICONICITY: Goal IDs if goals were saved (when save_goals=true).\nIn the same order as the request goals."},"results":{"type":"array","items":{"$ref":"#/components/schemas/FuzzyProveResponse"},"description":"Results for each goal, in the same order as the request"},"total_time_ms":{"type":"integer","description":"Total query time across all goals in milliseconds","minimum":0}}},"BulkMergeRequest":{"type":"object","description":"Request to bulk merge multiple reviews","required":["review_ids","target_term_id","reviewed_by"],"properties":{"review_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Review IDs to merge"},"reviewed_by":{"type":"string","format":"uuid","description":"User performing the bulk action"},"target_term_id":{"type":"string","format":"uuid","description":"Target term ID to merge into"}}},"BulkRejectActionsRequest":{"type":"object","description":"Request to bulk reject multiple reviews","required":["review_ids","reviewed_by","reason"],"properties":{"reason":{"type":"string","description":"Reason for rejection"},"review_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Review IDs to reject"},"reviewed_by":{"type":"string","format":"uuid","description":"User performing the bulk action"}}},"BulkRejectRequest":{"type":"object","description":"Request to bulk reject multiple reviews","required":["review_ids","reviewed_by","reason"],"properties":{"reason":{"type":"string","description":"Reason for rejection"},"review_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Review IDs to reject"},"reviewed_by":{"type":"string","format":"uuid","description":"User performing the bulk action"}}},"BulkReviewResponse":{"type":"object","description":"Response from bulk review actions","required":["success_count","failure_count","succeeded_ids","failed_ids"],"properties":{"failed_ids":{"type":"array","items":{"type":"array","items":false,"prefixItems":[{"type":"string","format":"uuid"},{"type":"string"}]},"description":"Review IDs that failed with reasons"},"failure_count":{"type":"integer","description":"Number of reviews that failed","minimum":0},"succeeded_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Review IDs that succeeded"},"success_count":{"type":"integer","description":"Number of reviews successfully processed","minimum":0}}},"BulkSetSimilaritiesRequest":{"type":"object","description":"Request to set multiple sort similarities in bulk","required":["similarities"],"properties":{"similarities":{"type":"array","items":{"$ref":"#/components/schemas/SimilarityEntry"},"description":"List of similarity relations to set"}}},"BulkSetSimilaritiesResponse":{"type":"object","description":"Response for bulk similarity setting","required":["set_count"],"properties":{"errors":{"type":"array","items":{"type":"string"},"description":"Any errors encountered"},"set_count":{"type":"integer","description":"Number of similarities set","minimum":0}}},"BulkSortDefinition":{"type":"object","description":"A sort definition for bulk creation (uses name-based parent references)","required":["name"],"properties":{"alt_labels":{"type":"array","items":{"type":"string"},"description":"Alternative labels / synonyms (e.g., HPO synonyms for semantic matching)"},"description":{"type":["string","null"],"description":"Optional description"},"features":{"type":"array","items":{"$ref":"#/components/schemas/FeatureDescriptorDto"},"description":"Optional feature declarations"},"name":{"type":"string","description":"Unique name for this sort (used as reference by children)"},"parents":{"type":"array","items":{"type":"string"},"description":"Parent sort names (resolved to IDs during processing)"}}},"BulkSortError":{"type":"object","description":"Error for a single sort in bulk operation","required":["name","error"],"properties":{"error":{"type":"string"},"name":{"type":"string"}}},"CalibrateRequest":{"type":"object","description":"Request to run ECE calibration.","required":["predictions","sort_names"],"properties":{"predictions":{"type":"array","items":{"$ref":"#/components/schemas/ExtractionPredictionDto"},"description":"Extraction predictions with confidence and correctness."},"sort_names":{"type":"object","description":"Sort ID to name mapping.","additionalProperties":{"type":"string"},"propertyNames":{"type":"string","format":"uuid"}}}},"CalibrationReportDto":{"type":"object","description":"ECE calibration report.","required":["sort_calibrations","global_ece","global_accuracy","total_predictions","augmentation_targets"],"properties":{"augmentation_targets":{"type":"array","items":{"$ref":"#/components/schemas/AugmentationTargetDto"},"description":"Sorts needing augmentation (sorted by priority)."},"global_accuracy":{"type":"number","format":"double","description":"Global accuracy."},"global_ece":{"type":"number","format":"double","description":"Global ECE (weighted average across sorts)."},"sort_calibrations":{"type":"array","items":{"$ref":"#/components/schemas/SortCalibrationDto"},"description":"Per-sort calibration results."},"total_predictions":{"type":"integer","description":"Total predictions analyzed.","minimum":0}}},"CallOnceRequest":{"type":"object","description":"Request for call_once (execute with cut)","required":["session_id","goal"],"properties":{"goal":{"type":"object"},"session_id":{"type":"string"}}},"CallOnceResponse":{"type":"object","description":"Response from call_once","required":["success","choice_points_cut"],"properties":{"choice_points_cut":{"type":"integer","description":"Number of choice points cut","minimum":0},"success":{"type":"boolean"}}},"CancelDocumentResponse":{"type":"object","description":"Response from cancelling a document's ingestion.","required":["cancelled","message"],"properties":{"cancelled":{"type":"boolean","description":"Whether the cancellation was applied (true = was in-flight or pending)"},"message":{"type":"string","description":"Human-readable message describing what happened"}}},"CandidateMatchDto":{"type":"object","description":"A candidate match for entity deduplication","required":["term_id","similarity"],"properties":{"similarity":{"type":"number","format":"double","description":"Similarity score (0.0 - 1.0)"},"term_id":{"type":"string","format":"uuid","description":"Term ID of the candidate"}}},"CausalAncestorRequest":{"type":"object","description":"Request to check if one variable is a causal ancestor of another","required":["ancestor","descendant"],"properties":{"ancestor":{"type":"string","description":"The potential ancestor variable"},"descendant":{"type":"string","description":"The potential descendant variable"}}},"CausalAncestorResponse":{"type":"object","description":"Response for causal ancestry check","required":["is_ancestor","path","explanation"],"properties":{"chain_certainty":{"type":["number","null"],"format":"double","description":"Combined certainty through the causal chain"},"explanation":{"type":"string","description":"Explanation of the result"},"is_ancestor":{"type":"boolean","description":"Whether the ancestor is a causal ancestor of the descendant"},"path":{"type":"array","items":{"type":"string"},"description":"The causal path from ancestor to descendant (if found)"}}},"CausalChainDto":{"type":"object","description":"A complete causal chain","required":["chain","certainty","length"],"properties":{"certainty":{"type":"number","format":"double","description":"Combined certainty through the chain"},"chain":{"type":"array","items":{"type":"string"},"description":"Variables in order from cause to effect"},"length":{"type":"integer","description":"Length of the chain","minimum":0}}},"CausalEdgeDto":{"type":"object","description":"A causal edge in the model","required":["cause","effect","certainty"],"properties":{"cause":{"type":"string","description":"The cause variable"},"certainty":{"type":"number","format":"double","description":"Certainty of the relationship"},"effect":{"type":"string","description":"The effect variable"},"mechanism":{"type":["string","null"],"description":"Optional mechanism"}}},"CausalProofTreeDto":{"type":"object","description":"Complete proof tree for a causal query","required":["nodes","statistics"],"properties":{"dot_format":{"type":["string","null"],"description":"DOT format for visualization"},"nodes":{"type":"array","items":{"$ref":"#/components/schemas/ProofNodeDto"},"description":"All nodes in the tree"},"root_id":{"type":["string","null"],"description":"Root node ID"},"statistics":{"$ref":"#/components/schemas/ProofStatisticsDto","description":"Summary statistics"}}},"CausalRelationshipDto":{"type":"object","required":["cause","effect"],"properties":{"cause":{"type":"string","description":"Cause variable"},"effect":{"type":"string","description":"Effect variable"}}},"CausesRequest":{"type":"object","description":"Request to check if one variable directly causes another","required":["cause","effect"],"properties":{"cause":{"type":"string","description":"The potential cause variable"},"effect":{"type":"string","description":"The potential effect variable"}}},"CausesResponse":{"type":"object","description":"Response for direct causation check","required":["causes","explanation"],"properties":{"causes":{"type":"boolean","description":"Whether the cause directly causes the effect"},"certainty":{"type":["number","null"],"format":"double","description":"The certainty of the causal relationship (if found)"},"explanation":{"type":"string","description":"Explanation of the result"}}},"CdlComponentStatus":{"type":"object","description":"Status of a CDL component.","required":["active","parameters"],"properties":{"active":{"type":"boolean"},"parameters":{"type":"integer","minimum":0}}},"CdlStatusResponse":{"type":"object","description":"Response for CDL status.","required":["enabled"],"properties":{"derived_layer":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/CdlComponentStatus","description":"Phase 4 (derived layer) status."}]},"dynamic_architecture":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/CdlComponentStatus","description":"Phase 6 (dynamic architecture) status."}]},"enabled":{"type":"boolean","description":"Whether CDL subsystem is enabled."},"fact_grounding":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/CdlComponentStatus","description":"Phase 5 (fact grounding) status."}]}}},"CdlVerificationDto":{"type":"object","description":"Post-adaptation verification result.","required":["constraint_satisfied","max_violation","sort_count"],"properties":{"constraint_satisfied":{"type":"boolean"},"max_violation":{"type":"number","format":"double"},"sort_count":{"type":"integer","minimum":0}}},"CertificateDto":{"type":"object","description":"Full validity certificate with per-layer cryptographic attestations.\nAllows clients to verify individual layer proofs.","required":["id","issued_at","problem_name","constraints_verified","all_satisfied","inference_steps","attestations"],"properties":{"all_satisfied":{"type":"boolean","description":"Whether all constraints are satisfied"},"attestations":{"type":"array","items":{"$ref":"#/components/schemas/AttestationDto"},"description":"Per-layer constraint attestations (individual proofs)"},"constraints_verified":{"type":"integer","description":"Number of constraints verified","minimum":0},"id":{"type":"string","description":"Certificate ID"},"inference_steps":{"type":"integer","description":"Number of inference steps in the proof","minimum":0},"issued_at":{"type":"integer","format":"int64","description":"When the certificate was issued (unix ms)","minimum":0},"problem_name":{"type":"string","description":"Problem name (e.g., \"Oversight Verification\")"},"proof_root":{"type":["string","null"],"description":"Merkle root hash for quick verification"},"solve_time_ms":{"type":["integer","null"],"format":"int64","description":"Solving time in milliseconds","minimum":0}}},"CheckDiversityRequest":{"type":"object","description":"Request to check diversity of a candidate term against existing terms.","required":["candidate","existing_term_ids"],"properties":{"candidate":{"$ref":"#/components/schemas/EntityDto","description":"Candidate entity to check."},"existing_term_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Existing entity IDs to compare against (uses terms from KB)."},"min_diversity_score":{"type":["number","null"],"format":"double","description":"Minimum diversity score to pass (default: 0.3)."}}},"CheckDiversityResponse":{"type":"object","description":"Response from diversity checking.","required":["novelty_score","is_diverse","max_similarity","terms_compared"],"properties":{"is_diverse":{"type":"boolean","description":"Whether the candidate passed the diversity threshold."},"max_similarity":{"type":"number","format":"double","description":"Maximum similarity found with any existing term."},"most_similar_id":{"type":["string","null"],"format":"uuid","description":"ID of the most similar existing term (if any)."},"novelty_score":{"type":"number","format":"double","description":"Novelty score (0.0 = identical duplicate, 1.0 = completely novel)."},"terms_compared":{"type":"integer","description":"Number of existing terms compared against.","minimum":0}}},"ChildCandidateDto":{"type":"object","description":"One ranked child with its vote count.","required":["name","support"],"properties":{"name":{"type":"string","description":"Canonical child name."},"support":{"type":"integer","description":"Number of best-of-N rounds in which this name appeared.","minimum":0}}},"ChoicePointDto":{"type":"object","description":"A choice point with alternatives","required":["description","alternative_count"],"properties":{"alternative_count":{"type":"integer","description":"Number of alternatives","minimum":0},"description":{"type":"string","description":"Description of what this choice represents"},"variable_name":{"type":["string","null"],"description":"Optional variable name for arithmetic constraints"}}},"ChoicePointMarkerResponse":{"type":"object","description":"Response with choice point marker","required":["marker_index","timestamp","choice_point_count"],"properties":{"choice_point_count":{"type":"integer","minimum":0},"marker_index":{"type":"integer","minimum":0},"timestamp":{"type":"integer","format":"int64","minimum":0}}},"ChoiceSelection":{"type":"object","description":"A choice made at a choice point","required":["description"],"properties":{"description":{"type":"string","description":"Description of the choice point"},"selected_index":{"type":["integer","null"],"description":"Selected alternative index (None if not yet selected)","minimum":0}}},"ChrRequest":{"type":"object","description":"Request for chr (ASCII code to character)","required":["code"],"properties":{"code":{"type":"integer","format":"int64"}}},"ChrResponse":{"oneOf":[{"type":"object","required":["character","status"],"properties":{"character":{"type":"string"},"status":{"type":"string","enum":["success"]}}},{"type":"object","required":["code","status"],"properties":{"code":{"type":"integer","format":"int64"},"status":{"type":"string","enum":["invalid_code"]}}}],"description":"Response from chr"},"ChunkFailureDto":{"type":"object","description":"Details of a failed chunk extraction","required":["chunk_index","error_message"],"properties":{"chunk_index":{"type":"integer","description":"Index of the failed chunk","minimum":0},"error_message":{"type":"string","description":"Error message"}}},"CitationMarkerDto":{"type":"object","description":"Citation marker DTO linking an inline reference to its source","required":["index","label","source_type","excerpt","relevance"],"properties":{"document":{"type":["string","null"],"description":"Source document or origin"},"excerpt":{"type":"string","description":"Relevant text excerpt"},"index":{"type":"integer","description":"Citation index (1-based, used as [^N] in text)","minimum":0},"label":{"type":"string","description":"Display label for the source"},"relevance":{"type":"number","format":"double","description":"Relevance score (0.0-1.0)"},"source_type":{"type":"string","description":"Source type (document, database, inference, etc.)"},"term_id":{"type":["string","null"],"description":"Term ID if sourced from a specific term"}}},"ClaimAnnotationDto":{"type":"object","description":"Per-claim provenance annotation attached to a response.","required":["text","span","claim_type","confidence"],"properties":{"claim_type":{"type":"string","description":"Claim classification: \"kb_grounded\"|\"derived\"|\"llm_framing\"|\"proven\"|\"contradicted\"."},"confidence":{"type":"number","format":"double","description":"Confidence score (0.0–1.0)."},"derivation_summary":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/DerivationSummaryDto","description":"Derivation chain summary."}]},"osfql_query":{"type":["string","null"],"description":"OSFQL query that produced the grounding data."},"source_excerpts":{"type":"array","items":{"$ref":"#/components/schemas/SourceExcerptDto"},"description":"Source data excerpts from the KB."},"source_term_ids":{"type":"array","items":{"type":"string"},"description":"TermIds that ground this claim."},"span":{"type":"array","items":false,"prefixItems":[{"type":"integer","minimum":0},{"type":"integer","minimum":0}],"description":"Character offsets (start, end) in the assistant_message."},"text":{"type":"string","description":"The sentence/phrase text."}}},"ClarificationQuestionDto":{"type":"object","description":"Clarification question DTO (reused from ontology_generate pattern).","required":["id","question","field","type"],"properties":{"choices":{"type":["array","null"],"items":{"type":"string"}},"default":{"type":["string","null"]},"field":{"type":"string"},"id":{"type":"string"},"question":{"type":"string"},"type":{"type":"string"}}},"ClassifySafetyRequest":{"type":"object","description":"Request for safety classification (Phase 5).","required":["text"],"properties":{"text":{"type":"string","description":"Text to classify for safety violations."},"threshold":{"type":["number","null"],"format":"double","description":"Classification threshold override (default: spec threshold)."}}},"ClassifySafetyResponse":{"type":"object","description":"Response for safety classification.","required":["question_decisions","question_probabilities","category_activations","model_info","elapsed_ms"],"properties":{"category_activations":{"type":"object","description":"Per-category activations.","additionalProperties":{"type":"number","format":"double"},"propertyNames":{"type":"string"}},"elapsed_ms":{"type":"integer","format":"int64","description":"Elapsed time in milliseconds.","minimum":0},"model_info":{"$ref":"#/components/schemas/SafetyModelInfoDto","description":"Model architecture info."},"question_decisions":{"type":"object","description":"Per-question binary decisions.","additionalProperties":{"type":"boolean"},"propertyNames":{"type":"string"}},"question_probabilities":{"type":"object","description":"Per-question probabilities.","additionalProperties":{"type":"number","format":"double"},"propertyNames":{"type":"string"}}}},"CleanupResponse":{"type":"object","description":"Response for cleanup operations","required":["cleaned_memory_sessions","cleaned_db_sessions","cleaned_curried_functions"],"properties":{"cleaned_curried_functions":{"type":"integer","minimum":0},"cleaned_db_sessions":{"type":"integer","minimum":0},"cleaned_memory_sessions":{"type":"integer","minimum":0}}},"CleanupSessionsResponse":{"type":"object","description":"Response from cleaning up old sessions","required":["success","removed","message"],"properties":{"message":{"type":"string"},"removed":{"type":"integer","minimum":0},"success":{"type":"boolean"}}},"ClearFactsResponse":{"type":"object","description":"Response for clearing facts.","required":["facts_cleared","message"],"properties":{"facts_cleared":{"type":"integer","description":"Number of facts cleared","minimum":0},"message":{"type":"string","description":"Message"}}},"ClearTenantResponse":{"type":"object","description":"Response for a tenant-scoped data reset operation.\n\nReports what was wiped for the specific tenant so operators can verify\nthe operation succeeded without affecting other tenants.","required":["message","tenant_id","terms_deleted","sorts_deleted","meta_records_deleted","reviews_deleted","sessions_deleted","residuations_deleted","fingerprints_deleted","cache_invalidated","inference_state_cleared"],"properties":{"cache_invalidated":{"type":"boolean","description":"Whether the cache was invalidated"},"fingerprints_deleted":{"type":"integer","description":"Number of document fingerprints deleted","minimum":0},"inference_state_cleared":{"type":"boolean","description":"Whether the in-memory inference state was cleared"},"message":{"type":"string","description":"Human-readable summary message"},"meta_records_deleted":{"type":"integer","description":"Number of meta records deleted (rules, named queries, etc.)","minimum":0},"residuations_deleted":{"type":"integer","description":"Number of residuation records deleted","minimum":0},"reviews_deleted":{"type":"integer","description":"Number of review-related records deleted","minimum":0},"sessions_deleted":{"type":"integer","description":"Number of ingestion sessions deleted","minimum":0},"sorts_deleted":{"type":"boolean","description":"Whether the sort hierarchy snapshot was deleted"},"tenant_id":{"type":"string","description":"The tenant whose data was cleared"},"terms_deleted":{"type":"integer","description":"Number of terms deleted from persistent storage","minimum":0}}},"ClearTermsResponse":{"type":"object","description":"Response for clearing all terms for a tenant","required":["terms_cleared","message"],"properties":{"message":{"type":"string","description":"Human-readable message"},"terms_cleared":{"type":"integer","description":"Number of terms cleared","minimum":0}}},"CognitiveStrategyDto":{"type":"object","description":"Cognitive strategy that influenced how this response was generated.\n\nWhen a cognitive agent exists for the tenant with RL-trained policies,\nthe integrated cognitive engine runs a lightweight cycle before\nclassification to select a strategy (Explore/Exploit/Observe/Consolidate).\nThis strategy guides the LLM's intent classification and response generation.","required":["mode","strategy","rl_active"],"properties":{"mode":{"type":"string","description":"Cognitive mode selected by System M (Explore/Exploit/Observe/Consolidate)."},"rl_active":{"type":"boolean","description":"Whether RL-trained Q-values influenced this decision."},"strategy":{"type":"string","description":"Human-readable strategy description."}}},"CognitiveTermInput":{"type":"object","description":"Term input for cognitive rules (simplified version).\n\nSupports both `sort_name` (human-friendly) and `sort_id` (efficient).\nIf both are provided, `sort_id` takes precedence.","required":["sort"],"properties":{"features":{"type":"object","description":"Features as key-value pairs (raw JSON values)","additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"propertyNames":{"type":"string"}},"sort":{"type":"string","description":"Sort name (for human-friendly input)\nKept as \"sort\" for backward compatibility with existing clients"},"sort_id":{"type":["string","null"],"format":"uuid","description":"Sort ID (optional, takes precedence over sort name if provided)"}}},"CollectionDto":{"type":"object","description":"Collection DTO","required":["id","namespace_id","path","depth","tags"],"properties":{"depth":{"type":"integer","description":"Depth in the hierarchy (0 for root)","minimum":0},"description":{"type":["string","null"],"description":"Optional description"},"id":{"type":"string","format":"uuid","description":"Unique identifier"},"name":{"type":["string","null"],"description":"Name (last segment of path, or None for root)"},"namespace_id":{"type":"string","format":"uuid","description":"Namespace this collection belongs to"},"path":{"type":"string","description":"Full path (e.g., \"/documents/reports/2024\")"},"tags":{"type":"array","items":{"type":"string"},"description":"Tags"}}},"CollectionListResponse":{"type":"object","description":"List of collections response","required":["collections","count"],"properties":{"collections":{"type":"array","items":{"$ref":"#/components/schemas/CollectionDto"}},"count":{"type":"integer","minimum":0}}},"CollectionResponse":{"type":"object","description":"Single collection response","required":["collection"],"properties":{"collection":{"$ref":"#/components/schemas/CollectionDto"}}},"ColumnMappingDto":{"type":"object","description":"Mapping between an OSF feature and a SQL column.","required":["feature","column","sql_type"],"properties":{"column":{"type":"string","description":"SQL column name."},"feature":{"type":"string","description":"OSF feature name."},"nullable":{"type":"boolean","description":"Whether the column is nullable."},"sql_type":{"type":"string","description":"SQL type (e.g., \"VARCHAR(255)\", \"INTEGER\")."}}},"CommitRequest":{"type":"object","description":"Request to commit to an alternative","required":["alternative_index"],"properties":{"alternative_index":{"type":"integer","description":"Index of the alternative to commit to","minimum":0}}},"CommunityDetectionConfigDto":{"type":"object","description":"Configuration for community detection","properties":{"generate_reports":{"type":"boolean","description":"Whether to generate LLM reports for communities"},"max_report_members":{"type":"integer","description":"Maximum number of members to include in report context","minimum":0},"min_community_size":{"type":"integer","description":"Minimum community size (default: 2)","minimum":0},"resolution":{"type":"number","format":"double","description":"Resolution parameter for Leiden algorithm (higher = more communities)\nDefault: 1.0"}}},"CommunityDetectionStatsDto":{"type":"object","description":"Statistics from community detection","required":["terms_processed","edges_in_graph","communities_detected","terms_in_communities","singleton_terms","avg_community_size","max_community_size","processing_time_ms","reports_generated"],"properties":{"avg_community_size":{"type":"number","format":"double","description":"Average community size"},"communities_detected":{"type":"integer","description":"Number of communities detected","minimum":0},"edges_in_graph":{"type":"integer","description":"Number of edges in reference graph","minimum":0},"max_community_size":{"type":"integer","description":"Largest community size","minimum":0},"processing_time_ms":{"type":"integer","format":"int64","description":"Processing time in milliseconds","minimum":0},"reports_generated":{"type":"integer","description":"Number of community reports generated","minimum":0},"singleton_terms":{"type":"integer","description":"Number of singleton terms (not in any community)","minimum":0},"terms_in_communities":{"type":"integer","description":"Number of terms assigned to communities","minimum":0},"terms_processed":{"type":"integer","description":"Number of input terms processed","minimum":0}}},"CommunityDto":{"type":"object","description":"A detected community","required":["id","level","member_ids","member_count"],"properties":{"id":{"type":"string","format":"uuid","description":"Community term ID"},"level":{"type":"integer","description":"Community level (0 = leaf, higher = more aggregated)","minimum":0},"member_count":{"type":"integer","description":"Number of members","minimum":0},"member_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Member term IDs"},"report":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/CommunityReportDto","description":"LLM-generated report (if requested)"}]}}},"CommunityMatchDto":{"type":"object","description":"A community match from search","required":["community_id","level","member_count","relevance_score","sample_member_ids"],"properties":{"community_id":{"type":"string","format":"uuid","description":"Community ID"},"level":{"type":"integer","description":"Community level","minimum":0},"member_count":{"type":"integer","description":"Member count","minimum":0},"relevance_score":{"type":"number","format":"double","description":"Relevance score (depends on search mode)"},"report_summary":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/CommunityReportSummaryDto","description":"Report summary (if available)"}]},"sample_member_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Sample member IDs"}}},"CommunityReportDto":{"type":"object","description":"LLM-generated community report","required":["id","title","summary","key_findings","impact_score"],"properties":{"id":{"type":"string","format":"uuid","description":"Report term ID"},"impact_score":{"type":"number","format":"double","description":"Impact score (0.0 - 1.0)"},"key_findings":{"type":"array","items":{"type":"string"},"description":"Key findings about the community"},"summary":{"type":"string","description":"Summary of what the community represents"},"title":{"type":"string","description":"Short title for the community"}}},"CommunityReportSummaryDto":{"type":"object","description":"Summarized community report for search results","required":["title","summary","impact_score"],"properties":{"impact_score":{"type":"number","format":"double","description":"Impact score"},"summary":{"type":"string","description":"Brief summary"},"title":{"type":"string","description":"Report title"}}},"CommunitySearchModeDto":{"oneOf":[{"type":"object","description":"Find communities containing specific entities","required":["entity_ids","type"],"properties":{"entity_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Term IDs to search for"},"type":{"type":"string","enum":["by_entities"]}}},{"type":"object","description":"Find communities by impact score (highest first)","required":["type"],"properties":{"type":{"type":"string","enum":["by_impact"]}}},{"type":"object","description":"Find communities at a specific level","required":["level","type"],"properties":{"level":{"type":"integer","description":"Community level (0 = leaf)","minimum":0},"type":{"type":"string","enum":["by_level"]}}},{"type":"object","description":"Find communities by keyword in report","required":["keyword","type"],"properties":{"keyword":{"type":"string","description":"Keyword to search for"},"type":{"type":"string","enum":["by_keyword"]}}}],"description":"Search mode for community queries"},"CommunitySearchStatsDto":{"type":"object","description":"Statistics from community search","required":["communities_searched","matches_found","search_time_ms"],"properties":{"communities_searched":{"type":"integer","description":"Number of communities searched","minimum":0},"matches_found":{"type":"integer","description":"Number of matches found","minimum":0},"search_time_ms":{"type":"integer","format":"int64","description":"Search time in milliseconds","minimum":0}}},"CommunityStatsDto":{"type":"object","description":"Statistics for community detection (GraphRAG-style clustering)","required":["communities_detected","terms_in_communities","singleton_terms","edges_in_graph","avg_community_size","max_community_size","community_detection_time_ms"],"properties":{"avg_community_size":{"type":"number","format":"double","description":"Average community size"},"communities_detected":{"type":"integer","description":"Number of communities detected","minimum":0},"community_detection_time_ms":{"type":"integer","format":"int64","description":"Community detection processing time (ms)","minimum":0},"edges_in_graph":{"type":"integer","description":"Number of edges in reference graph","minimum":0},"max_community_size":{"type":"integer","description":"Maximum community size","minimum":0},"singleton_terms":{"type":"integer","description":"Number of singleton terms (not in any community)","minimum":0},"terms_in_communities":{"type":"integer","description":"Number of terms assigned to communities","minimum":0}}},"ComponentDto":{"type":"object","description":"An s-connected component","required":["id","nodes","s_value"],"properties":{"id":{"type":"string","description":"Component ID"},"nodes":{"type":"array","items":{"type":"string"},"description":"Node IDs in the component"},"s_value":{"type":"number","format":"double","description":"S-value (connectivity threshold)"}}},"ComponentHealthDto":{"type":"object","description":"Component health DTO","required":["name","status"],"properties":{"message":{"type":["string","null"]},"name":{"type":"string"},"status":{"type":"string"}}},"ComputeGlbRequest":{"type":"object","description":"Request to compute GLB","required":["sort1_id","sort2_id"],"properties":{"sort1_id":{"type":"string","format":"uuid","description":"First sort ID"},"sort2_id":{"type":"string","format":"uuid","description":"Second sort ID"}}},"ComputeGlbResponse":{"type":"object","description":"Response for GLB computation","properties":{"glb":{"type":["string","null"],"format":"uuid","description":"GLB sort ID if exists"}}},"ComputeLubRequest":{"type":"object","description":"Request to compute LUB","required":["sort1_id","sort2_id"],"properties":{"sort1_id":{"type":"string","format":"uuid","description":"First sort ID"},"sort2_id":{"type":"string","format":"uuid","description":"Second sort ID"}}},"ComputeLubResponse":{"type":"object","description":"Response for LUB computation","properties":{"lub":{"type":["string","null"],"format":"uuid","description":"LUB sort ID if exists"}}},"ConceptMatchDto":{"type":"object","description":"Matched concept DTO","required":["concept_id","canonical_name","match_degree","match_reason","source_ids","features"],"properties":{"canonical_name":{"type":"string"},"concept_id":{"type":"string"},"features":{"type":"object","additionalProperties":{},"propertyNames":{"type":"string"}},"match_degree":{"type":"number","format":"double"},"match_reason":{"type":"string"},"name_variants":{"type":["object","null"],"additionalProperties":{"type":"string"},"propertyNames":{"type":"string"}},"source_ids":{"type":"array","items":{"type":"string"}}}},"CondRequest":{"type":"object","description":"Request for conditional execution","required":["session_id","condition","then_goal","else_goal"],"properties":{"condition":{"type":"object","description":"Condition goal to test"},"else_goal":{"type":"object","description":"Goal to execute if condition fails"},"session_id":{"type":"string"},"then_goal":{"type":"object","description":"Goal to execute if condition succeeds"}}},"CondResponse":{"type":"object","description":"Response from conditional execution","required":["condition_succeeded","branch_executed","success"],"properties":{"branch_executed":{"type":"string"},"condition_succeeded":{"type":"boolean"},"success":{"type":"boolean"}}},"ConditionalIndependenceRequest":{"type":"object","required":["var_x","var_y","conditioning_set"],"properties":{"conditioning_set":{"type":"array","items":{"type":"string"},"description":"Conditioning set"},"var_x":{"type":"string","description":"First variable name"},"var_y":{"type":"string","description":"Second variable name"}}},"ConditionalIndependenceResponse":{"type":"object","required":["independent","explanation"],"properties":{"explanation":{"type":"string","description":"Explanation"},"independent":{"type":"boolean","description":"Whether X and Y are conditionally independent given conditioning set"},"p_value":{"type":["number","null"],"format":"double","description":"P-value from the independence test"}}},"ConfirmResponseDto":{"type":"object","description":"Response after confirming an implication.\n\nPOST /api/v1/analysis/attribute-exploration/{session_id}/confirm","required":["progress"],"properties":{"next_question":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ExplorationQuestionDto","description":"Next question (None if exploration is complete)"}]},"progress":{"$ref":"#/components/schemas/ExplorationProgressDto","description":"Current exploration progress"}}},"ConflictResolution":{"type":"string","description":"How to resolve feature conflicts when merging","enum":["keep_existing","use_new","merge"]},"ConnectorInstanceDto":{"type":"object","required":["id","name","type_name","display_name","status"],"properties":{"connected_at":{"type":["string","null"]},"connected_by":{"type":["string","null"]},"display_name":{"type":"string"},"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"type_name":{"type":"string"}}},"ConnectorTypeDto":{"type":"object","required":["type_name","display_name","auth_type"],"properties":{"auth_type":{"type":"string"},"display_name":{"type":"string"},"icon_url":{"type":["string","null"]},"type_name":{"type":"string"}}},"ConstraintCheckDto":{"type":"object","description":"A single constraint check in the verification result.","required":["description","satisfied"],"properties":{"description":{"type":"string","description":"Description of the constraint."},"satisfied":{"type":"boolean","description":"Whether the constraint was satisfied."}}},"ConstraintDto":{"oneOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["Integer"]}}},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["String"]}}},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["Boolean"]}}},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["Real"]}}},{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["IntegerRange"]},"value":{"type":"object","required":["min","max"],"properties":{"max":{"type":"integer","format":"int64"},"min":{"type":"integer","format":"int64"}}}}},{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["StringPattern"]},"value":{"type":"string"}}},{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["Enum"]},"value":{"type":"array","items":{"$ref":"#/components/schemas/ValueDto"}}}},{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["DateRange"]},"value":{"type":"object","required":["start","end"],"properties":{"end":{"type":"string"},"start":{"type":"string"}}}}},{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["TimestampBefore"]},"value":{"type":"string"}}},{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["TimestampAfter"]},"value":{"type":"string"}}},{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["PathEquation"]},"value":{"type":"object","required":["path1","path2"],"properties":{"path1":{"type":"array","items":{"type":"string"}},"path2":{"type":"array","items":{"type":"string"}}}}}},{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["FuzzyRange"]},"value":{"type":"object","required":["center","tolerance"],"properties":{"center":{"type":"number","format":"double"},"tolerance":{"type":"number","format":"double"}}}}},{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["FuzzyLinguistic"]},"value":{"type":"object","required":["variable","term"],"properties":{"term":{"type":"string"},"variable":{"type":"string"}}}}},{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["FuzzyPathSimilarity"]},"value":{"type":"object","required":["path1","path2","min_similarity"],"properties":{"min_similarity":{"type":"number","format":"double"},"path1":{"type":"array","items":{"type":"string"}},"path2":{"type":"array","items":{"type":"string"}}}}}},{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["PathLessThan"]},"value":{"type":"object","required":["path1","path2"],"properties":{"path1":{"type":"array","items":{"type":"string"}},"path2":{"type":"array","items":{"type":"string"}}}}}},{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["PathLessOrEqual"]},"value":{"type":"object","required":["path1","path2"],"properties":{"path1":{"type":"array","items":{"type":"string"}},"path2":{"type":"array","items":{"type":"string"}}}}}}],"description":"API representation of a constraint"},"ConstraintGraphRequest":{"type":"object","description":"Request for constraint dependency graph visualization","properties":{"detect_cycles":{"type":"boolean","description":"Whether to detect and highlight cycles"},"generate_dot":{"type":"boolean","description":"Whether to generate DOT output"},"include_fd_domains":{"type":"boolean","description":"Whether to include FD domain states"},"term_id":{"type":["string","null"],"format":"uuid","description":"Optional term ID to focus on"}}},"ConstraintGraphResponse":{"type":"object","description":"Response for constraint graph visualization","required":["graph","stats"],"properties":{"cycles":{"type":"array","items":{"$ref":"#/components/schemas/CycleDto"},"description":"Detected cycles (if requested)"},"fd_domains":{"type":"array","items":{"$ref":"#/components/schemas/FdDomainStateDto"},"description":"FD domain states (if requested)"},"graph":{"$ref":"#/components/schemas/VisualizationGraphDto","description":"The visualization graph"},"stats":{"$ref":"#/components/schemas/ConstraintGraphStats","description":"Statistics"}}},"ConstraintGraphStats":{"type":"object","description":"Statistics about the constraint graph","required":["total_constraints","total_variables","active_constraints","determined_variables","cycle_count"],"properties":{"active_constraints":{"type":"integer","description":"Number of active constraints","minimum":0},"cycle_count":{"type":"integer","description":"Number of cycles detected","minimum":0},"determined_variables":{"type":"integer","description":"Number of determined variables","minimum":0},"total_constraints":{"type":"integer","description":"Total number of constraints","minimum":0},"total_variables":{"type":"integer","description":"Total number of variables","minimum":0}}},"ConstraintInputDto":{"oneOf":[{"type":"object","description":"Guard constraint: comparison between two values\n\nLeft and right can be:\n- Variable references: \"?StartTime\", \"?EndTime\"\n- Integer literals: \"1583020800000\"\n- String literals: \"alice\"\n\nOperators: \"lt\" (<), \"lte\" (<=), \"gt\" (>), \"gte\" (>=), \"eq\" (=), \"ne\" (!=)","required":["left","op","right","type"],"properties":{"left":{"type":"string","description":"Left operand (variable or literal)"},"op":{"type":"string","description":"Comparison operator"},"right":{"type":"string","description":"Right operand (variable or literal)"},"type":{"type":"string","enum":["Guard"]}}},{"type":"object","description":"Equality constraint between two variables","required":["var1","var2","type"],"properties":{"type":{"type":"string","enum":["Equality"]},"var1":{"type":"string"},"var2":{"type":"string"}}},{"type":"object","description":"Disequality constraint (not equal)","required":["var1","var2","type"],"properties":{"type":{"type":"string","enum":["Disequality"]},"var1":{"type":"string"},"var2":{"type":"string"}}},{"type":"object","description":"Allen temporal constraint: interval_a has relation to interval_b\n\nAllen's Interval Algebra supports 13 relations:\n- before, after: No overlap, ordered by endpoints\n- meets, met_by: Adjacent intervals (A.end = B.start)\n- overlaps, overlapped_by: Partial overlap\n- during, contains: Full containment\n- starts, started_by: Same start, different end\n- finishes, finished_by: Different start, same end\n- equals: Identical intervals\n\nExample: Find intervals that are BEFORE Meeting B","required":["interval_a","relation","interval_b_term_id","type"],"properties":{"interval_a":{"type":"string","description":"Reference to interval_a (use \"?\" to refer to the goal term itself)"},"interval_b_term_id":{"type":"string","format":"uuid","description":"Term ID of interval_b (the reference interval)"},"relation":{"type":"string","description":"Allen relation (before, after, meets, met_by, overlaps, etc.)"},"type":{"type":"string","enum":["Allen"]}}}],"description":"Constraint input for queries (guards, comparisons, etc.)\n\nThese constraints are evaluated during backward chaining to filter solutions.\nThey are essential for temporal reasoning queries like \"find employees before date X\"."},"ConstraintSessionStatusResponse":{"type":"object","description":"Session status information\n\nRenamed to avoid utoipa schema collision with the oversight module's\n`SessionStatusResponse` (which has `alerts`, `current_score`, etc.).","required":["session_id","created_at","last_accessed","constraint_count","satisfied_count","suspended_count","current_bindings","all_satisfied","metadata"],"properties":{"all_satisfied":{"type":"boolean"},"constraint_count":{"type":"integer","minimum":0},"created_at":{"type":"string","format":"date-time"},"current_bindings":{"type":"object","additionalProperties":{"type":"integer","format":"int64"},"propertyNames":{"type":"string"}},"last_accessed":{"type":"string","format":"date-time"},"metadata":{"type":"object","additionalProperties":{"type":"string"},"propertyNames":{"type":"string"}},"satisfied_count":{"type":"integer","minimum":0},"session_id":{"type":"string","format":"uuid"},"suspended_count":{"type":"integer","minimum":0}}},"ContainmentVerificationDto":{"type":"object","description":"Containment verification sub-DTO.","required":["total_pairs","correct_pairs","accuracy","violation_count"],"properties":{"accuracy":{"type":"number","format":"double","description":"Accuracy (correct_pairs / total_pairs)."},"correct_pairs":{"type":"integer","description":"Number of pairs where containment correctly matches the hierarchy.","minimum":0},"total_pairs":{"type":"integer","description":"Total number of sort pairs checked.","minimum":0},"violation_count":{"type":"integer","description":"Number of violations.","minimum":0}}},"ConversationMessageRequestDto":{"type":"object","description":"Request to send a message in a conversation.","required":["message"],"properties":{"conversation_id":{"type":["string","null"],"description":"Optional conversation ID to continue an existing conversation.\nIf omitted, a new conversation is created."},"current_sort_context":{"type":["string","null"],"description":"Optional sort name hint from the current page context."},"generate_certificate":{"type":"boolean","description":"When true, generate a cryptographic validity certificate for this response."},"message":{"type":"string","description":"The user's natural language message."},"session_id":{"type":["string","null"],"description":"Session ID for session tracking."}}},"ConversationMessageResponseDto":{"type":"object","description":"Response from processing a conversation message.","required":["assistant_message","conversation_id","intent","produced_term_ids","suggestions"],"properties":{"assistant_message":{"type":"string","description":"The assistant's natural language response."},"claim_annotations":{"type":["array","null"],"items":{"$ref":"#/components/schemas/ClaimAnnotationDto"},"description":"Per-claim provenance annotations (if claims were annotated)."},"cognitive_strategy":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/CognitiveStrategyDto","description":"Cognitive strategy used for this response (when RL training is active).\nPresent when a cognitive agent exists for the tenant and the integrated\ncognitive engine influenced the LLM prompts."}]},"conversation_id":{"type":"string","description":"The conversation ID (existing or newly created)."},"intent":{"type":"string","description":"Classified intent type."},"llm_context":{"type":["string","null"],"description":"Assembled LLM context used for response generation (for execution trace inspection)."},"matched_templates":{"type":["array","null"],"items":{"$ref":"#/components/schemas/QueryTemplateDto"},"description":"Query templates matching the current intent and referenced sort.\nUseful for suggesting reusable patterns to the UI."},"osfql_executed":{"type":["string","null"],"description":"OSFQL that was executed (if any)."},"produced_term_ids":{"type":"array","items":{"type":"string"},"description":"IDs of terms produced by the OSFQL execution."},"proof_trace":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ProofTraceNodeDto","description":"Proof tree for this response (populated when PROVE / backward chaining was used)."}]},"query_results":{"type":["array","null"],"items":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/OsfqlValueDto"},"propertyNames":{"type":"string"}},"description":"Query results (if OSFQL was a MATCH)."},"suggestions":{"type":"array","items":{"type":"string"},"description":"Contextual OSFQL suggestions."},"system_prompt":{"type":["string","null"],"description":"System prompt sent to the LLM for intent classification (for execution trace inspection)."},"ui_customizations":{"type":["array","null"],"items":{"$ref":"#/components/schemas/UICustomizationDto"},"description":"UI customizations detected in this response (for multi-turn UI evolution)."},"ui_sort_id":{"type":["string","null"],"description":"Sort ID referenced in the message (for UI rendering)."},"validity_certificate_hash":{"type":["string","null"],"description":"SHA-256 hash of the validity certificate."},"validity_certificate_id":{"type":["string","null"],"description":"ID of the validity certificate (if generate_certificate was true)."}}},"ConversationSummaryDto":{"type":"object","description":"A conversation summary.","required":["id","created_at","turn_count"],"properties":{"created_at":{"type":"string","description":"ISO 8601 creation timestamp."},"id":{"type":"string","description":"Conversation ID."},"session_id":{"type":["string","null"],"description":"Session ID."},"turn_count":{"type":"integer","format":"int64","description":"Number of turns."}}},"ConversationTrainingConfigDto":{"type":"object","description":"Configuration for training on conversation data.\n\nControls how synthetic conversation transcripts are generated\nand scored during RL training with conversation environments.","properties":{"agent_id":{"type":["string","null"],"format":"uuid","description":"Optional agent ID to scope training to a specific agent's conversations"},"conversation_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Optional conversation IDs to train on specifically. When empty and\nuse_real_conversations is true, uses the most recent conversations."},"max_turns":{"type":"integer","description":"Maximum turns per episode (default: 20)","minimum":0},"num_transcripts":{"type":"integer","description":"Number of synthetic transcripts to generate for training (default: 10)","minimum":0},"reward_goal_completion":{"type":"number","format":"double","description":"Reward for goal completion (default: 1.0)"},"reward_step_cost":{"type":"number","format":"double","description":"Step cost penalty (default: -0.01)"},"reward_successful_proof":{"type":"number","format":"double","description":"Reward for successful proof (default: 0.3)"},"topics":{"type":"array","items":{"type":"string"},"description":"Conversation topics for synthetic transcript generation"},"use_real_conversations":{"type":"boolean","description":"When true, loads actual conversation history from the knowledge base\ninstead of generating synthetic transcripts. The most recent N conversations\nare used (controlled by num_transcripts)."}}},"ConversationTurnDto":{"type":"object","description":"Conversation turn in request format","required":["role","content"],"properties":{"content":{"type":"string"},"role":{"type":"string"}}},"ConversationTurnsResponseDto":{"type":"object","description":"Response for getting conversation turns.","required":["conversation_id","turns"],"properties":{"conversation_id":{"type":"string"},"turns":{"type":"array","items":{"$ref":"#/components/schemas/TurnDto"}}}},"CoordinatedResourceSet":{"type":"object","description":"A single coordinated resource set (N resources matched together)","required":["resource_ids","compatibility_score"],"properties":{"compatibility_score":{"type":"number","format":"double","description":"Compatibility score for this set (0.0-1.0)"},"resource_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Resource IDs in order matching the request's resource specs\nIndex 0 = first resource spec, Index 1 = second resource spec, etc."}}},"CopyModeDto":{"type":"string","description":"Copy modes","enum":["exact","quote","eval"]},"CopyResultDto":{"type":"object","description":"Single copy result","required":["original_term_id","copied_term_id","success"],"properties":{"copied_term_id":{"type":"string"},"error":{"type":["string","null"]},"original_term_id":{"type":"string"},"success":{"type":"boolean"}}},"CopyTermRequest":{"type":"object","description":"Request for copy operation","required":["session_id","term_id","copy_mode"],"properties":{"copy_mode":{"$ref":"#/components/schemas/CopyModeDto"},"session_id":{"type":"string"},"term_id":{"type":"string"}}},"CopyTermResponse":{"type":"object","description":"Response from copy operation","required":["original_term_id","copied_term_id","copy_mode","copied_features"],"properties":{"copied_features":{"type":"array","items":{"type":"string"},"description":"Features that were copied"},"copied_term_id":{"type":"string"},"copy_mode":{"$ref":"#/components/schemas/CopyModeDto"},"original_term_id":{"type":"string"}}},"CorrectEntityRequest":{"type":"object","description":"Request to correct an entity before approval","required":["review_id"],"properties":{"features":{"type":["object","null"],"description":"Corrected features","additionalProperties":{},"propertyNames":{"type":"string"}},"notes":{"type":["string","null"],"description":"Correction notes"},"review_id":{"type":"string","format":"uuid","description":"The review ID to correct"},"sort":{"type":["string","null"],"description":"Corrected sort (if different from extracted)"}}},"CorrelationRequest":{"type":"object","required":["var_x","var_y"],"properties":{"var_x":{"type":"string","description":"First variable name"},"var_y":{"type":"string","description":"Second variable name"}}},"CorrelationResponse":{"type":"object","required":["count","success"],"properties":{"correlation":{"type":["number","null"],"format":"double","description":"Pearson correlation coefficient"},"count":{"type":"integer","description":"Number of paired observations","minimum":0},"success":{"type":"boolean","description":"Success flag"}}},"CountAuditEntriesResponse":{"type":"object","required":["count"],"properties":{"count":{"type":"integer","minimum":0}}},"CounterfactualRequest":{"type":"object","description":"Request to evaluate a counterfactual query","required":["evidence","antecedent_variable","antecedent_value","consequent_variable"],"properties":{"antecedent_value":{"description":"Antecedent value: what we're hypothetically setting the variable to"},"antecedent_variable":{"type":"string","description":"Antecedent: the variable to intervene on in the counterfactual world"},"consequent_variable":{"type":"string","description":"Consequent: the variable we're querying in the counterfactual world"},"evidence":{"type":"object","description":"Factual evidence (observed values in the actual world)","additionalProperties":{},"propertyNames":{"type":"string"}}}},"CounterfactualResponse":{"type":"object","description":"Response for counterfactual query","required":["success","query","exogenous_values","explanation","trace"],"properties":{"counterfactual_value":{"description":"The counterfactual result (predicted value of consequent)"},"exogenous_values":{"type":"object","description":"Exogenous values computed during abduction","additionalProperties":{},"propertyNames":{"type":"string"}},"explanation":{"type":"string","description":"Step-by-step explanation of the three-step algorithm"},"query":{"type":"string","description":"The counterfactual query in natural language"},"success":{"type":"boolean","description":"Whether the counterfactual evaluation was successful"},"trace":{"$ref":"#/components/schemas/CounterfactualTraceDto","description":"Detailed trace of abduction, action, and prediction steps"}}},"CounterfactualTraceDto":{"type":"object","description":"Trace of the counterfactual evaluation steps","required":["abduction","action","prediction"],"properties":{"abduction":{"type":"string","description":"Step 1: Abduction - computing exogenous values"},"action":{"type":"string","description":"Step 2: Action - applying intervention"},"prediction":{"type":"string","description":"Step 3: Prediction - querying in modified world"}}},"CreateAgentRequest":{"type":"object","description":"Request to create a new cognitive agent.","required":["name","tenant_id"],"properties":{"config":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/AgentConfigDto","description":"Optional configuration"}]},"name":{"type":"string","description":"Name for the agent"},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID for multi-tenancy"}}},"CreateAgentResponse":{"type":"object","description":"Response after creating an agent.","required":["agent_id","name","message"],"properties":{"agent_id":{"type":"string","format":"uuid","description":"ID of the created agent (TermId as UUID)"},"message":{"type":"string","description":"Message"},"name":{"type":"string","description":"Name of the agent"}}},"CreateChildNamespaceRequest":{"type":"object","description":"Request to create a child namespace\n\n# Tenant Context\nThe tenant is determined from the `X-Tenant-Id` header.","required":["path","visibility"],"properties":{"path":{"type":"string","description":"Full path (e.g., \"acme.engineering\")"},"visibility":{"$ref":"#/components/schemas/VisibilityDto","description":"Visibility level"}}},"CreateCognitiveSortRequest":{"type":"object","description":"Request to create a sort in the cognitive registry.","required":["tenant_id","sort_name"],"properties":{"parent_sort_names":{"type":"array","items":{"type":"string"},"description":"Parent sort names (optional, defaults to \"thing\")"},"sort_name":{"type":"string","description":"Sort name"},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"}}},"CreateCognitiveSortResponse":{"type":"object","description":"Response after creating a cognitive sort.","required":["sort_id","message"],"properties":{"message":{"type":"string","description":"Message"},"sort_id":{"type":"string","format":"uuid","description":"Sort ID"}}},"CreateCollectionRequest":{"type":"object","description":"Request to create a collection\n\n# Namespace Context\nThe namespace is determined from the `X-Namespace-Id` header.","required":["path","tags"],"properties":{"description":{"type":["string","null"],"description":"Optional description"},"path":{"type":"string","description":"Collection path (e.g., \"/documents/reports/2024\")"},"tags":{"type":"array","items":{"type":"string"},"description":"Tags for categorization"}}},"CreateConstraintSessionRequest":{"type":"object","description":"Request to create a new constraint session\n\nRenamed to avoid utoipa schema collision with the oversight module's\n`CreateSessionRequest` (which has `user_intent`, `initial_steps`, etc.).","properties":{"description":{"type":["string","null"]},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"propertyNames":{"type":"string"}},"name":{"type":["string","null"]}}},"CreateCurriedFunctionRequest":{"type":"object","description":"Request to create a curried function","required":["tenant_id","function_name","arity"],"properties":{"arity":{"type":"integer","minimum":0},"can_curry":{"type":"boolean","description":"Whether this function can be further curried","default":true},"function_name":{"type":"string"},"provided_arguments":{"type":"array","items":{"$ref":"#/components/schemas/PositionalArgumentDto"},"description":"Initial arguments to provide (position -> value)"},"tenant_id":{"type":"string","format":"uuid"}}},"CreateExecutionSessionRequest":{"type":"object","description":"Request to create a new execution session with trail-based backtracking","required":["tenant_id"],"properties":{"name":{"type":["string","null"],"description":"Optional name for the session"},"tenant_id":{"type":"string","format":"uuid"}}},"CreateGoalRequest":{"type":"object","description":"Request to create and persist a goal.\n\nTRUE HOMOICONICITY: Goals are first-class Ψ-terms. This endpoint creates\na goal from clauses (query patterns) and persists it for later execution.","required":["clauses"],"properties":{"clauses":{"type":"array","items":{"$ref":"#/components/schemas/TermInputDto"},"description":"The clauses that make up the goal (query patterns).\nEach clause is a TermInputDto representing a pattern to match."},"constraints":{"type":"array","items":{"$ref":"#/components/schemas/ConstraintInputDto"},"description":"Optional constraints to apply during inference.\nThese are additional conditions like guards, Allen constraints, etc."},"min_degree":{"type":["number","null"],"format":"double","description":"Minimum certainty threshold for solutions (0.0 to 1.0).\nSolutions with lower certainty will be filtered out."}}},"CreateGoalResponse":{"type":"object","description":"Response after creating a goal.","required":["goal_id","clause_count","constraint_count","goal"],"properties":{"clause_count":{"type":"integer","description":"Number of clauses in the goal","minimum":0},"constraint_count":{"type":"integer","description":"Number of constraint clauses added","minimum":0},"goal":{"$ref":"#/components/schemas/PsiTermDto","description":"The full goal as a PsiTermDto"},"goal_id":{"type":"string","format":"uuid","description":"The created goal's unique TermId"}}},"CreateModuleRequest":{"type":"object","description":"Request to create a module","required":["session_id","name"],"properties":{"name":{"type":"string"},"parents":{"type":"array","items":{"type":"string"},"description":"Parent modules for inheritance"},"session_id":{"type":"string"}}},"CreateModuleResponse":{"type":"object","description":"Response after creating a module","required":["module_name","success"],"properties":{"module_name":{"type":"string"},"success":{"type":"boolean"}}},"CreateRootNamespaceRequest":{"type":"object","description":"Request to create a root namespace\n\n# Tenant Context\nThe tenant is determined from the `X-Tenant-Id` header.","required":["name","visibility"],"properties":{"name":{"type":"string","description":"Namespace name (e.g., \"acme\")"},"visibility":{"$ref":"#/components/schemas/VisibilityDto","description":"Visibility level"}}},"CreateRuleStoreRequest":{"type":"object","description":"Request to create a new rule store","required":["tenant_id"],"properties":{"tenant_id":{"type":"string","format":"uuid"}}},"CreateScenarioRequest":{"type":"object","description":"Request body for scenario creation (generate + materialize).","required":["prompt"],"properties":{"agent_name":{"type":["string","null"],"description":"Optional custom agent name."},"answers":{"type":["object","null"],"description":"Answers to clarification questions (2nd call in multi-turn flow).","additionalProperties":{"type":"string"},"propertyNames":{"type":"string"}},"create_agent":{"type":"boolean","description":"Whether to create a cognitive agent from the scenario."},"enable_curriculum":{"type":"boolean","description":"Whether to generate curriculum stages."},"enable_grounding":{"type":"boolean","description":"Whether to apply concept grounding after materialization."},"prompt":{"type":"string","description":"Natural language task description (e.g., \"organize a conference\")."},"run_initial_cycle":{"type":"boolean","description":"Whether to run an initial cognitive cycle after materialization.\nRequires `create_agent` to be true."},"session_id":{"type":["string","null"],"description":"Session ID for multi-turn clarification continuity."}}},"CreateScenarioResponse":{"oneOf":[{"type":"object","required":["status","questions","understood","session_id"],"properties":{"questions":{"type":"array","items":{"$ref":"#/components/schemas/ClarificationQuestionDto"}},"session_id":{"type":"string"},"status":{"type":"string","enum":["needs_clarification"]},"understood":{"type":"object","description":"Arbitrary JSON value"}}},{"type":"object","required":["status","scenario_id","scenario","materialization","groundings_applied","total_time_ms"],"properties":{"agent_id":{"type":"string"},"cycle_outcome":{"$ref":"#/components/schemas/CycleOutcomeSummaryDto"},"groundings_applied":{"type":"integer","minimum":0},"materialization":{"$ref":"#/components/schemas/MaterializationSummaryDto"},"scenario":{"type":"object","description":"Arbitrary JSON value"},"scenario_id":{"type":"string"},"status":{"type":"string","enum":["complete"]},"total_time_ms":{"type":"integer","minimum":0}}}],"title":"CreateScenarioResponse","description":"Response for scenario creation. Discriminated by the 'status' field. Variants: needs_clarification, complete.","discriminator":{"propertyName":"status"}},"CreateSessionRequest":{"type":"object","description":"Request to create a live oversight session.","required":["user_intent"],"properties":{"config":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/JudgeConfigDto","description":"Optional pipeline configuration overrides"}]},"initial_steps":{"type":"array","items":{"$ref":"#/components/schemas/TrajectoryStepDto"},"description":"Optional initial trajectory steps (if some steps already executed)"},"user_intent":{"type":"string","description":"User instruction (what the agent is being asked to do)"}}},"CreateSessionResponse":{"type":"object","description":"Response from creating a live oversight session.","required":["session_id","status","created_at"],"properties":{"created_at":{"type":"integer","format":"int64","description":"Unix timestamp (ms) when session was created","minimum":0},"session_id":{"type":"string","description":"Unique session identifier"},"status":{"type":"string","description":"Session status (should be \"active\")"}}},"CreateSnapshotRequest":{"type":"object","description":"Request body for creating a new snapshot.","required":["name"],"properties":{"name":{"type":"string","description":"Human-readable name for the snapshot (e.g., \"before-etf-experiment\")."}}},"CreateSortRequest":{"type":"object","description":"Request to create a sort\n\n# Tenant Context\nThe tenant is determined from the `X-Tenant-Id` header.\n\n# ID Field\nIf `id` is provided, the sort will be created with that specific UUID.\nThis is useful for homoiconic systems where clients need deterministic IDs\nfor cross-referencing between sorts, rules, and facts.","properties":{"bound_constraints":{"type":"array","items":{"$ref":"#/components/schemas/BoundConstraintDto"},"description":"Bound constraints on feature values\n\nThese enforce relationships like valid_to <= person.death_date"},"description":{"type":["string","null"],"description":"Human-readable description (semantic definition for LLM sort assignment)"},"features":{"type":"array","items":{"$ref":"#/components/schemas/FeatureDescriptorDto"},"description":"Feature descriptors"},"id":{"type":["string","null"],"format":"uuid","description":"Optional specific ID for the sort.\nIf not provided, a new UUID will be generated."},"name":{"type":"string","description":"Sort name"},"parents":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Parent sort IDs"}}},"CreateSpaceRequest":{"type":"object","description":"Request to create a new computation space","required":["constraints","choice_points"],"properties":{"choice_points":{"type":"array","items":{"$ref":"#/components/schemas/ChoicePointDto"},"description":"Choice points to create"},"constraints":{"type":"array","items":{"$ref":"#/components/schemas/SpaceConstraintDto"},"description":"Initial constraints (for testing/simple cases)"},"description":{"type":["string","null"],"description":"Description of the computation"}}},"CreateStoreTermRequest":{"type":"object","description":"Request to create a term in the term store","required":["sort_id"],"properties":{"features":{"type":"object","description":"Optional features to set on the term","additionalProperties":{"type":"object"},"propertyNames":{"type":"string"}},"sort_id":{"type":"string"}}},"CreateTemplateRequestDto":{"type":"object","description":"Request to create a new template.","required":["sort_name","intent","osfql_pattern"],"properties":{"description":{"type":["string","null"],"description":"Optional description."},"intent":{"type":"string","description":"Intent type (query, create, etc.)."},"osfql_pattern":{"type":"string","description":"The OSFQL pattern."},"sort_name":{"type":"string","description":"Primary sort name for this template."}}},"CreateTermRequest":{"type":"object","description":"Request to create a term\n\n# Tenant Context\nThe tenant is determined from the `X-Tenant-Id` header.","required":["sort_id","owner_id","features"],"properties":{"features":{"type":"object","description":"Features map","additionalProperties":{"$ref":"#/components/schemas/ValueDto"},"propertyNames":{"type":"string"}},"owner_id":{"type":"string","format":"uuid","description":"Owner ID"},"sort_id":{"type":"string","format":"uuid","description":"Sort ID for the term"}}},"CreateTermResponse":{"type":"object","description":"Response after creating a term or variable","required":["term_id","is_variable"],"properties":{"is_variable":{"type":"boolean"},"term_id":{"type":"string"}}},"CreateTermStoreRequest":{"type":"object","description":"Request to create a new term store session","required":["tenant_id"],"properties":{"owner_id":{"type":["string","null"],"format":"uuid"},"tenant_id":{"type":"string","format":"uuid"}}},"CreateVariableRequest":{"type":"object","description":"Request to create a variable in the term store","required":["sort_id"],"properties":{"sort_id":{"type":"string"}}},"CriticViolationDto":{"type":"object","description":"Individual critic violation record.","required":["kind","feature_path","reason"],"properties":{"feature_path":{"type":"string","description":"Feature path the facet applied to (may be empty for non-restriction violations)."},"kind":{"type":"string","description":"Facet kind (e.g. `min_count`, `disjoint_classes`)."},"reason":{"type":"string","description":"Human-readable reason."}}},"CuriosityTargetDto":{"type":"object","description":"Curiosity target DTO representing a term the agent wants to explore.","required":["target_id","novelty","exploration_priority"],"properties":{"exploration_priority":{"type":"number","format":"double","description":"Exploration priority (higher = more interesting)"},"novelty":{"type":"number","format":"double","description":"Novelty score (0.0 to 1.0)"},"target_id":{"type":"string","format":"uuid","description":"Target term ID"}}},"CurriedFunctionResponse":{"type":"object","description":"Response with curried function info","required":["curried_id","function_name","original_arity","provided_count","remaining_count","missing_positions","is_fully_applied","can_curry"],"properties":{"can_curry":{"type":"boolean"},"curried_id":{"type":"string"},"function_name":{"type":"string"},"is_fully_applied":{"type":"boolean"},"missing_positions":{"type":"array","items":{"type":"integer","minimum":0}},"original_arity":{"type":"integer","minimum":0},"provided_count":{"type":"integer","minimum":0},"remaining_count":{"type":"integer","minimum":0}}},"CurryingContextResponse":{"type":"object","description":"Response with currying context","required":["more_call_attr","more_def_attr","should_curry","missing_in_call","missing_in_def"],"properties":{"missing_in_call":{"type":"array","items":{"type":"string"}},"missing_in_def":{"type":"array","items":{"type":"string"}},"more_call_attr":{"type":"boolean"},"more_def_attr":{"type":"boolean"},"should_curry":{"type":"boolean"}}},"CutRequest":{"type":"object","description":"Request for cut","required":["session_id"],"properties":{"session_id":{"type":"string"}}},"CutResponse":{"type":"object","description":"Response from cut","required":["choice_points_removed"],"properties":{"choice_points_removed":{"type":"integer","description":"Number of choice points removed","minimum":0}}},"CycleDto":{"type":"object","description":"A cycle in the constraint graph","required":["nodes","edges","is_problematic"],"properties":{"edges":{"type":"array","items":{"type":"string"},"description":"Edge IDs in the cycle"},"is_problematic":{"type":"boolean","description":"Whether this cycle is problematic"},"nodes":{"type":"array","items":{"type":"string"},"description":"Node IDs in the cycle"}}},"CycleOutcomeDto":{"type":"object","description":"Outcome of an agent cycle.","required":["goals_pursued","goals_achieved","goals_failed","new_beliefs","updated_beliefs","actions_executed","success_rate"],"properties":{"actions_executed":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Actions executed (assert/retract)"},"goals_achieved":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Goals that succeeded"},"goals_failed":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Goals that failed"},"goals_pursued":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Goals that were pursued"},"new_beliefs":{"type":"array","items":{"type":"string","format":"uuid"},"description":"New beliefs acquired"},"success_rate":{"type":"number","format":"double","description":"Success rate (0.0 to 1.0)"},"updated_beliefs":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Beliefs that were updated"}}},"CycleOutcomeSummaryDto":{"type":"object","description":"Summary of a cognitive cycle outcome.","required":["goals_achieved","goals_failed","actions_executed","rules_learned"],"properties":{"actions_executed":{"type":"integer","description":"Number of actions executed during the cycle.","minimum":0},"goals_achieved":{"type":"integer","description":"Number of goals achieved during the cycle.","minimum":0},"goals_failed":{"type":"integer","description":"Number of goals failed during the cycle.","minimum":0},"rules_learned":{"type":"integer","description":"Number of rules learned during the cycle.","minimum":0}}},"DSeparatedRequest":{"type":"object","description":"Request to check d-separation between two variables","required":["x","y","conditioning_set"],"properties":{"conditioning_set":{"type":"array","items":{"type":"string"},"description":"Conditioning set (variables to condition on)"},"x":{"type":"string","description":"First variable"},"y":{"type":"string","description":"Second variable"}}},"DSeparatedResponse":{"type":"object","description":"Response for d-separation check","required":["d_separated","active_paths","explanation"],"properties":{"active_paths":{"type":"array","items":{"type":"array","items":{"type":"string"}},"description":"Active paths between X and Y (if not d-separated)"},"d_separated":{"type":"boolean","description":"Whether X and Y are d-separated given the conditioning set"},"explanation":{"type":"string","description":"Explanation of the result"}}},"DataMixingStatsDto":{"type":"object","description":"Data mixing statistics.","required":["real_count","synthetic_count","negative_count","total_count","real_ratio","synthetic_ratio","negative_ratio","sort_coverage"],"properties":{"negative_count":{"type":"integer","description":"Number of negative examples.","minimum":0},"negative_ratio":{"type":"number","format":"double","description":"Actual negative ratio."},"real_count":{"type":"integer","description":"Number of real examples.","minimum":0},"real_ratio":{"type":"number","format":"double","description":"Actual real ratio."},"sort_coverage":{"type":"object","description":"Per-sort coverage counts.","additionalProperties":{"type":"integer","minimum":0},"propertyNames":{"type":"string"}},"synthetic_count":{"type":"integer","description":"Number of synthetic examples.","minimum":0},"synthetic_ratio":{"type":"number","format":"double","description":"Actual synthetic ratio."},"total_count":{"type":"integer","description":"Total example count.","minimum":0}}},"DataNeededDto":{"type":"object","required":["var_x","var_y","samples_needed"],"properties":{"samples_needed":{"type":"integer","description":"Additional samples needed","minimum":0},"var_x":{"type":"string","description":"First variable"},"var_y":{"type":"string","description":"Second variable"}}},"DataPointDto":{"type":"object","description":"A single data point in the time series.","required":["timestamp","values"],"properties":{"timestamp":{"type":"string","format":"date-time","description":"Timestamp (ISO 8601)."},"values":{"type":"object","description":"Feature values.","additionalProperties":{"type":"number","format":"double"},"propertyNames":{"type":"string"}}}},"DatasetStatisticsDto":{"type":"object","description":"Statistics for an enhanced training dataset.","required":["total_examples","by_source","by_sort","by_format","positive_count","negative_count","real_ratio","synthetic_ratio","verbalized_ratio","negative_ratio","verified_count","mean_faithfulness_score"],"properties":{"by_format":{"type":"object","description":"Examples by format (Extraction, QA, FillBlank, etc.).","additionalProperties":{"type":"integer","minimum":0},"propertyNames":{"type":"string"}},"by_sort":{"type":"object","description":"Examples by sort name.","additionalProperties":{"type":"integer","minimum":0},"propertyNames":{"type":"string"}},"by_source":{"type":"object","description":"Examples by source type (real, synthetic, verbalized, enhanced_negative).","additionalProperties":{"type":"integer","minimum":0},"propertyNames":{"type":"string"}},"diversity_summary":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/DiversityAnalysisDto","description":"Diversity analysis summary (if computed)."}]},"mean_faithfulness_score":{"type":"number","format":"double","description":"Mean faithfulness score of verified examples."},"negative_count":{"type":"integer","description":"Number of negative examples.","minimum":0},"negative_ratio":{"type":"number","format":"double"},"positive_count":{"type":"integer","description":"Number of positive examples.","minimum":0},"real_ratio":{"type":"number","format":"double","description":"Achieved data mixing ratios."},"synthetic_ratio":{"type":"number","format":"double"},"total_examples":{"type":"integer","description":"Total examples in the dataset.","minimum":0},"verbalized_ratio":{"type":"number","format":"double"},"verified_count":{"type":"integer","description":"Number of verified examples.","minimum":0}}},"DecodeGlbRequest":{"type":"object","description":"Request to decode GLB as type disjunction\n\nComputes the GLB of two sorts and decodes the result into\na human-readable type disjunction (e.g., \"int | real\").","required":["sort1_id","sort2_id"],"properties":{"sort1_id":{"type":"string","format":"uuid","description":"First sort ID"},"sort2_id":{"type":"string","format":"uuid","description":"Second sort ID"}}},"DecodeGlbResponse":{"type":"object","description":"Response for GLB decode operation\n\nReturns the type disjunction as both a list of sort IDs/names\nand a formatted string.","required":["sort_ids","sort_names","formatted","is_bottom"],"properties":{"formatted":{"type":"string","description":"Formatted type disjunction string (e.g., \"int | real\")"},"is_bottom":{"type":"boolean","description":"Whether the GLB is empty (⊥ / bottom)"},"sort_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Sort IDs in the type disjunction"},"sort_names":{"type":"array","items":{"type":"string"},"description":"Sort names in the type disjunction"}}},"DecomposeGoalRequest":{"type":"object","description":"Request to decompose a goal using HTN.","required":["tenant_id","agent_id","goal_id"],"properties":{"agent_id":{"type":"string","format":"uuid","description":"Agent ID"},"goal_id":{"type":"string","format":"uuid","description":"Goal to decompose"},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"}}},"DecomposeGoalResponse":{"type":"object","description":"Response with decomposed task network.","required":["success","tasks","executable_actions","status","message"],"properties":{"executable_actions":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Executable actions in order"},"message":{"type":"string","description":"Message"},"root_task":{"type":["string","null"],"format":"uuid","description":"Root task ID (if successful)"},"status":{"$ref":"#/components/schemas/NetworkStatusDto","description":"Network status"},"success":{"type":"boolean","description":"Whether decomposition succeeded"},"tasks":{"type":"array","items":{"$ref":"#/components/schemas/TaskDto"},"description":"All tasks in the network"}}},"DeepCopyRequest":{"type":"object","description":"Request for deep copy with cycle detection","required":["session_id","term_id","copy_mode"],"properties":{"copy_mode":{"$ref":"#/components/schemas/CopyModeDto"},"max_depth":{"type":["integer","null"],"description":"Maximum depth to copy (None for unlimited)","minimum":0},"session_id":{"type":"string"},"term_id":{"type":"string"}}},"DeepCopyResponse":{"type":"object","description":"Response from deep copy","required":["original_term_id","copied_term_id","copy_mode","terms_copied","cycles_detected","translation_table"],"properties":{"copied_term_id":{"type":"string"},"copy_mode":{"$ref":"#/components/schemas/CopyModeDto"},"cycles_detected":{"type":"boolean","description":"True if cycles were detected and handled"},"original_term_id":{"type":"string"},"terms_copied":{"type":"integer","description":"Number of terms copied (including nested)","minimum":0},"translation_table":{"type":"array","items":{"$ref":"#/components/schemas/TermTranslationDto"},"description":"Translation table mapping original IDs to copied IDs"}}},"DegreeDistributionDto":{"type":"object","description":"Degree distribution for the hypergraph","required":["node_degrees","hyperedge_sizes","avg_node_degree","max_node_degree"],"properties":{"avg_node_degree":{"type":"number","format":"double","description":"Average node degree"},"hyperedge_sizes":{"type":"object","description":"Hyperedge size histogram (size -> count)","additionalProperties":{"type":"integer","minimum":0},"propertyNames":{"type":"integer","minimum":0}},"max_node_degree":{"type":"integer","description":"Maximum node degree","minimum":0},"node_degrees":{"type":"object","description":"Node degree histogram (degree -> count)","additionalProperties":{"type":"integer","minimum":0},"propertyNames":{"type":"integer","minimum":0}}}},"DeleteAgentResponse":{"type":"object","description":"Response from deleting a cognitive agent.","required":["deleted","message"],"properties":{"deleted":{"type":"boolean","description":"Whether the agent was deleted"},"message":{"type":"string","description":"Message"}}},"DeleteGoalResponse":{"type":"object","description":"Response for deleting a goal.","required":["deleted","goal_id"],"properties":{"deleted":{"type":"boolean","description":"Whether the goal was deleted"},"goal_id":{"type":"string","format":"uuid","description":"The goal ID that was deleted"},"references_deleted":{"type":["integer","null"],"description":"Number of referenced terms also deleted (if delete_references was true)","minimum":0}}},"DeletePlanResponse":{"type":"object","description":"Response after deleting a plan.","required":["deleted","message"],"properties":{"deleted":{"type":"boolean","description":"Whether the plan was deleted"},"message":{"type":"string","description":"Message"}}},"DeleteSessionResponse":{"type":"object","description":"Response from deleting a constraint session","required":["success","message"],"properties":{"message":{"type":"string"},"success":{"type":"boolean"}}},"DeleteSnapshotResponse":{"type":"object","description":"Response for the delete snapshot endpoint.","required":["message","id"],"properties":{"id":{"type":"string","description":"ID of the deleted snapshot."},"message":{"type":"string","description":"Confirmation message."}}},"DependentInfoDto":{"type":"object","description":"Dependent info DTO","required":["concept_id","canonical_name","depends_on","evidence"],"properties":{"canonical_name":{"type":"string"},"concept_id":{"type":"string"},"depends_on":{"type":"string"},"evidence":{"$ref":"#/components/schemas/EvidenceSourceDto"}}},"DereferenceRequest":{"type":"object","description":"Request to dereference a term ID","required":["term_id"],"properties":{"term_id":{"type":"string"}}},"DereferenceResponse":{"type":"object","description":"Response with dereferenced term","required":["original_id","dereferenced_id","is_bound"],"properties":{"dereferenced_id":{"type":"string"},"is_bound":{"type":"boolean"},"original_id":{"type":"string"}}},"DerivationSummaryDto":{"type":"object","description":"Summary of a derivation chain for an inferred claim.","required":["step_count","rules_involved","root_source_ids"],"properties":{"root_source_ids":{"type":"array","items":{"type":"string"},"description":"Root source term IDs at the base of the chain."},"rules_involved":{"type":"array","items":{"type":"string"},"description":"Names/IDs of rules involved."},"step_count":{"type":"integer","description":"Number of derivation steps.","minimum":0}}},"DerivedInferenceRequest":{"type":"object","description":"Request for derived inference (Phase 4).","required":["pairs"],"properties":{"pairs":{"type":"array","items":{"$ref":"#/components/schemas/FeaturePair"},"description":"Pairs of feature vectors for inference."}}},"DerivedInferenceResponse":{"type":"object","description":"Response for derived inference.","required":["results","architecture"],"properties":{"architecture":{"$ref":"#/components/schemas/ArchitectureInfoDto","description":"Architecture summary."},"results":{"type":"array","items":{"$ref":"#/components/schemas/DerivedInferenceResultDto"},"description":"Per-pair inference results."}}},"DerivedInferenceResultDto":{"type":"object","description":"Single pair inference result from the derived layer.","required":["match_score","gate_value","proceed","combined_confidence","sort_predictions"],"properties":{"combined_confidence":{"type":"number","format":"float"},"gate_value":{"type":"number","format":"float"},"match_score":{"type":"number","format":"float"},"proceed":{"type":"boolean"},"sort_predictions":{"type":"object","additionalProperties":{"type":"number","format":"float"},"propertyNames":{"type":"string"}}}},"DetectCommunitiesRequest":{"type":"object","description":"Request to detect communities from existing terms","required":["tenant_id"],"properties":{"config":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/CommunityDetectionConfigDto","description":"Configuration for community detection"}]},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID for multi-tenancy isolation"},"term_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Optional: specific term IDs to cluster (if empty, uses all tenant terms)"}}},"DetectCommunitiesResponse":{"type":"object","description":"Response from community detection","required":["success","stats","communities"],"properties":{"communities":{"type":"array","items":{"$ref":"#/components/schemas/CommunityDto"},"description":"Detected communities"},"stats":{"$ref":"#/components/schemas/CommunityDetectionStatsDto","description":"Detection statistics"},"success":{"type":"boolean","description":"Whether detection was successful"}}},"DetectMissingAttributesRequest":{"type":"object","description":"Request to detect missing attributes for currying","required":["call_attributes","definition_attributes"],"properties":{"call_attributes":{"type":"array","items":{"type":"string"}},"definition_attributes":{"type":"array","items":{"type":"string"}}}},"DiDValidationRequest":{"type":"object","description":"Request to validate a Difference-in-Differences design","required":["treatment","outcome_pre","outcome_post"],"properties":{"covariates":{"type":"array","items":{"type":"string"},"description":"Conditioning set (covariates)"},"outcome_post":{"type":"string","description":"Post-treatment outcome variable"},"outcome_pre":{"type":"string","description":"Pre-treatment outcome variable"},"treatment":{"type":"string","description":"The treatment variable"}}},"DiDValidationResponse":{"type":"object","description":"Response for DiD validation","required":["is_valid","explanation","bad_controls","framework"],"properties":{"bad_controls":{"type":"array","items":{"type":"string"},"description":"Identified \"bad controls\" (nodes that induce bias if conditioned on)"},"explanation":{"type":"string","description":"Explanation of the result"},"framework":{"type":"string","description":"The framework used for validation"},"is_valid":{"type":"boolean","description":"Whether the design is valid"}}},"DiagnosticDto":{"type":"object","description":"A pipeline diagnostic message.","required":["stage","level","message"],"properties":{"level":{"type":"string","description":"Severity level: \"info\", \"warning\", or \"error\"."},"message":{"type":"string","description":"Diagnostic message."},"stage":{"type":"string","description":"Pipeline stage that produced this diagnostic."}}},"DiagnosticsResponse":{"type":"object","description":"Response for the diagnostics endpoint.","required":["enabled"],"properties":{"diagnostics":{"type":["object","null"],"description":"Diagnostics snapshot (None if disabled)."},"enabled":{"type":"boolean","description":"Whether the neuro-symbolic subsystem is enabled."}}},"DifferentiableFcRequest":{"type":"object","description":"Request for differentiable forward chaining (Phases 1+2).","properties":{"max_iterations":{"type":"integer","format":"int32","description":"Maximum forward chaining iterations (default: 20).","minimum":0},"min_weight_threshold":{"type":"number","format":"double","description":"Minimum weight threshold for fact propagation (default: 0.01)."},"temperature":{"type":"number","format":"double","description":"Softmax temperature for rule attention (default: 1.0)."}}},"DifferentiableFcResponse":{"type":"object","description":"Response for differentiable forward chaining.","required":["weighted_facts","iteration_metrics","symbolic_result","elapsed_ms"],"properties":{"elapsed_ms":{"type":"integer","format":"int64","description":"Elapsed time in milliseconds.","minimum":0},"iteration_metrics":{"type":"array","items":{"$ref":"#/components/schemas/IterationMetricDto"},"description":"Per-iteration metrics for training diagnostics."},"symbolic_result":{"$ref":"#/components/schemas/SymbolicResultDto","description":"Summary of the symbolic forward chaining result."},"weighted_facts":{"type":"array","items":{"$ref":"#/components/schemas/WeightedFactDto"},"description":"Weighted facts with confidence scores."}}},"DiscoverCausalRequest":{"type":"object","required":["variables"],"properties":{"min_samples":{"type":["integer","null"],"description":"Minimum samples required before discovery (default: 30)","minimum":0},"variables":{"type":"array","items":{"type":"string"},"description":"Variables to include in discovery"}}},"DiscoverCausalResponse":{"type":"object","required":["success","relationships_discovered","relationships","message"],"properties":{"data_needed":{"type":["array","null"],"items":{"$ref":"#/components/schemas/DataNeededDto"},"description":"Data still needed (if discovery incomplete)"},"message":{"type":"string","description":"Message explaining the result"},"relationships":{"type":"array","items":{"$ref":"#/components/schemas/CausalRelationshipDto"},"description":"Discovered causal relationships"},"relationships_discovered":{"type":"integer","description":"Number of causal relationships discovered","minimum":0},"success":{"type":"boolean","description":"Whether discovery was successful"}}},"DiscoverEffectsRequest":{"type":"object","description":"Request to train effect discovery from time series data.","required":["name","data","target_feature"],"properties":{"config":{"$ref":"#/components/schemas/DiscoveryConfigDto","description":"Configuration overrides."},"data":{"type":"array","items":{"$ref":"#/components/schemas/DataPointDto"},"description":"Time series data points."},"name":{"type":"string","description":"Name for this discovery session."},"parent_sort_id":{"type":["string","null"],"format":"uuid","description":"Optional parent sort ID to attach discovered sorts."},"target_feature":{"type":"string","description":"Feature to predict effects for."}}},"DiscoverEffectsResponse":{"type":"object","description":"Response from effect discovery.","required":["success","regimes_discovered","effects_extracted","discovered_horizons","sort_ids","terms_created","root_sort_id","processing_time_ms"],"properties":{"discovered_horizons":{"type":"array","items":{"$ref":"#/components/schemas/HorizonDto"},"description":"Discovered optimal horizons."},"effects_extracted":{"type":"integer","description":"Number of effects extracted.","minimum":0},"processing_time_ms":{"type":"integer","description":"Processing time in milliseconds.","minimum":0},"regimes_discovered":{"type":"integer","description":"Number of regimes discovered.","minimum":0},"root_sort_id":{"type":"string","format":"uuid","description":"Root sort ID for the discovery."},"sort_ids":{"type":"object","description":"Created sort IDs (regime -> sort).","additionalProperties":{"type":"string","format":"uuid"},"propertyNames":{"type":"string"}},"success":{"type":"boolean","description":"Whether discovery succeeded."},"terms_created":{"type":"integer","description":"Number of PsiTerms created.","minimum":0}}},"DiscoverSchemaRequest":{"type":"object","description":"Request to discover schema from a registered source.","properties":{"include_sample_data":{"type":"boolean","description":"Whether to include sample data in response (default: true)"},"sample_size":{"type":"integer","description":"Sample size for schema inference (default: 100)","minimum":0}}},"DiscoverSchemaResponse":{"type":"object","description":"Response from schema discovery.","required":["source_id","sorts","relations","total_columns"],"properties":{"relations":{"type":"array","items":{"$ref":"#/components/schemas/DiscoveredRelationDto"},"description":"Discovered relations between sorts"},"sorts":{"type":"array","items":{"$ref":"#/components/schemas/DiscoveredSortDto"},"description":"Discovered sorts/types"},"source_id":{"type":"string","description":"Source identifier"},"total_columns":{"type":"integer","description":"Total number of columns/features discovered","minimum":0},"warnings":{"type":"array","items":{"type":"string"},"description":"Warnings during discovery"}}},"DiscoveredFeatureDto":{"type":"object","description":"A feature/field discovered from a source.","required":["name","source_name","required","is_identifier","is_relation"],"properties":{"constraints":{"type":"array","items":{"type":"string"},"description":"Constraints discovered"},"description":{"type":["string","null"],"description":"Human-readable description"},"is_identifier":{"type":"boolean","description":"Whether the field is a primary key/identifier"},"is_relation":{"type":"boolean","description":"Whether the field is a relation"},"name":{"type":"string","description":"Feature name"},"relation_target":{"type":["string","null"],"description":"Target sort if this is a relation"},"required":{"type":"boolean","description":"Whether the field is required"},"source_name":{"type":"string","description":"Original source field name"},"type_hint":{"type":["string","null"],"description":"Type hint (e.g., \"VARCHAR(255)\", \"integer\", \"boolean\")"}}},"DiscoveredRelationDto":{"type":"object","description":"A relation discovered between sorts.","required":["source_sort","relation_name","target_sort","cardinality","confidence"],"properties":{"cardinality":{"type":"string","description":"Cardinality string (e.g., \"0..1\", \"1\", \"0..*\", \"1..*\")"},"confidence":{"type":"number","format":"double","description":"Confidence score (0.0 - 1.0)"},"inverse_name":{"type":["string","null"],"description":"Inverse relation name (if bidirectional)"},"relation_name":{"type":"string","description":"Relation/feature name"},"source_sort":{"type":"string","description":"Source sort name"},"target_sort":{"type":"string","description":"Target sort name"}}},"DiscoveredSortDto":{"type":"object","description":"A sort/type discovered from a source.","required":["name","source_name","features","confidence"],"properties":{"confidence":{"type":"number","format":"double","description":"Confidence score (0.0 - 1.0)"},"description":{"type":["string","null"],"description":"Human-readable description"},"features":{"type":"array","items":{"$ref":"#/components/schemas/DiscoveredFeatureDto"},"description":"Features/fields discovered"},"name":{"type":"string","description":"Sort/type name as found in the source"},"source_name":{"type":"string","description":"Source name where this was discovered"},"suggested_parents":{"type":"array","items":{"type":"string"},"description":"Suggested parent sorts"}}},"DiscoveryConfigDto":{"type":"object","description":"Discovery configuration overrides.","properties":{"min_effect_samples":{"type":["integer","null"],"description":"Minimum samples for effect estimation.","minimum":0},"num_regimes":{"type":["integer","null"],"description":"Number of regimes to discover.","minimum":0},"window_size":{"type":["integer","null"],"description":"Window size for feature extraction.","minimum":0},"window_step":{"type":["integer","null"],"description":"Step between windows.","minimum":0}}},"DiscoveryProofNodeDto":{"type":"object","required":["id","step_type","explanation","depth"],"properties":{"depth":{"type":"integer","description":"Depth in tree","minimum":0},"explanation":{"type":"string","description":"Explanation"},"id":{"type":"string","description":"Node ID"},"p_value":{"type":["number","null"],"format":"double","description":"P-value (for CI tests)"},"parent_id":{"type":["string","null"],"description":"Parent node ID"},"step_type":{"type":"string","description":"Step type description"}}},"DiscoveryProofStatsDto":{"type":"object","required":["total_nodes","max_depth"],"properties":{"duration_ms":{"type":["integer","null"],"format":"int64","description":"Duration in milliseconds","minimum":0},"max_depth":{"type":"integer","description":"Maximum depth","minimum":0},"total_nodes":{"type":"integer","description":"Total nodes in tree","minimum":0}}},"DiscoveryProofTreeDto":{"type":"object","required":["nodes","statistics"],"properties":{"dot_format":{"type":["string","null"],"description":"DOT format for visualization"},"nodes":{"type":"array","items":{"$ref":"#/components/schemas/DiscoveryProofNodeDto"},"description":"All proof nodes"},"root_id":{"type":["string","null"],"description":"Root node ID"},"statistics":{"$ref":"#/components/schemas/DiscoveryProofStatsDto","description":"Statistics"}}},"DiscoveryStateDto":{"type":"object","required":["state_type"],"properties":{"current_samples":{"type":["integer","null"],"description":"Current samples (if insufficient data)","minimum":0},"required_samples":{"type":["integer","null"],"description":"Required samples (if insufficient data)","minimum":0},"state_type":{"type":"string","description":"State type: \"insufficient_data\", \"running\", \"complete_with_uncertainty\", \"complete\""},"uncertain_count":{"type":["integer","null"],"description":"Uncertain edge count (if complete with uncertainty)","minimum":0}}},"DiscoveryStatusResponse":{"type":"object","required":["state","total_uncertainty","has_graph","directed_edge_count","undirected_edge_count"],"properties":{"directed_edge_count":{"type":"integer","description":"Number of directed edges","minimum":0},"has_graph":{"type":"boolean","description":"Has a graph been discovered?"},"state":{"$ref":"#/components/schemas/DiscoveryStateDto","description":"Current state"},"total_uncertainty":{"type":"number","format":"double","description":"Total uncertainty score"},"undirected_edge_count":{"type":"integer","description":"Number of undirected edges","minimum":0}}},"DiscoveryStrategy":{"type":"string","description":"Strategy for structure learning","enum":["pc","mcmc","hybrid"]},"DisentailmentRequest":{"type":"object","description":"Request for disentailment check.\n\nChecks if antecedent disentails consequent (A =/=> B: if A holds, B must NOT hold).\nA violation means both A and B hold simultaneously, indicating a conflict.","required":["antecedent","consequent"],"properties":{"antecedent":{"$ref":"#/components/schemas/TermInputDto","description":"Antecedent clause (if this holds...)"},"consequent":{"$ref":"#/components/schemas/TermInputDto","description":"Consequent clause (...then this must NOT hold)"},"facts":{"type":"array","items":{"$ref":"#/components/schemas/TermInputDto"},"description":"Known facts"}}},"DisentailmentResponse":{"type":"object","description":"Response from disentailment check.","required":["violated","holds","confidence","computation_time_ms"],"properties":{"computation_time_ms":{"type":"integer","format":"int64","description":"Computation time in milliseconds","minimum":0},"confidence":{"type":"number","format":"double","description":"Confidence degree"},"holds":{"type":"boolean","description":"Whether the disentailment holds (antecedent is false, or consequent is false)"},"violated":{"type":"boolean","description":"Whether the disentailment is violated (both antecedent AND consequent hold = conflict)"}}},"DiversityAnalysisDto":{"type":"object","description":"Diversity analysis summary.","required":["total_pairs","mean_similarity","is_balanced","bucket_counts"],"properties":{"bucket_counts":{"type":"object","description":"Distribution of examples across buckets (near, medium, far, unrelated).","additionalProperties":{"type":"integer","minimum":0},"propertyNames":{"type":"string"}},"is_balanced":{"type":"boolean","description":"Whether diversity is balanced (no bucket has >60% of pairs)."},"mean_similarity":{"type":"number","format":"double","description":"Average Wu-Palmer similarity across all pairs."},"total_pairs":{"type":"integer","description":"Total sort pairs analyzed.","minimum":0}}},"DlqAbandonResponse":{"type":"object","description":"Response for abandoning a DLQ entry.","required":["abandoned","message"],"properties":{"abandoned":{"type":"boolean","description":"Whether the entry was successfully abandoned"},"message":{"type":"string","description":"Human-readable message"}}},"DlqCountResponse":{"type":"object","description":"Response for counting DLQ entries.","required":["pending_count"],"properties":{"pending_count":{"type":"integer","format":"int64","description":"Number of pending DLQ entries","minimum":0}}},"DlqEntryDto":{"type":"object","description":"A single DLQ entry representing a persistently failed chunk extraction.","required":["id","session_id","document_id","chunk_index","chunk_text_preview","error_message","error_category","retry_attempts","status","failed_at"],"properties":{"chunk_index":{"type":"integer","description":"Zero-based index of the failed chunk","minimum":0},"chunk_text_preview":{"type":"string","description":"Preview of the chunk text (first 100 chars)"},"document_id":{"type":"string","description":"Document within the session"},"error_category":{"type":"string","description":"Error category: \"transient\", \"permanent\", or \"unknown\""},"error_message":{"type":"string","description":"Human-readable error message"},"failed_at":{"type":"string","description":"When the failure was first recorded (ISO 8601)"},"id":{"type":"string","description":"Unique identifier for this DLQ entry"},"retry_attempts":{"type":"integer","format":"int32","description":"Number of retry attempts already made","minimum":0},"session_id":{"type":"string","description":"Session that owns the ingestion job"},"status":{"type":"string","description":"Current status of this entry"}}},"DlqListResponse":{"type":"object","description":"Response for listing DLQ entries.","required":["entries","total"],"properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/DlqEntryDto"},"description":"The DLQ entries matching the query"},"total":{"type":"integer","format":"int64","description":"Total number of pending entries (for pagination)","minimum":0}}},"DocumentAnalysisResponse":{"type":"object","description":"Response DTO wrapping the analysis report.","required":["documents","overall_compliance","total_rules_evaluated","total_rules_passed","total_rules_failed"],"properties":{"documents":{"type":"array","items":{},"description":"Per-document analysis results."},"overall_compliance":{"type":"number","format":"double","description":"Overall compliance score (0.0-1.0)."},"total_rules_evaluated":{"type":"integer","description":"Total rules evaluated.","minimum":0},"total_rules_failed":{"type":"integer","description":"Total rules failed.","minimum":0},"total_rules_passed":{"type":"integer","description":"Total rules passed.","minimum":0}}},"DocumentBatchItem":{"type":"object","description":"A single document in a batch request","required":["document_id","document"],"properties":{"document":{"$ref":"#/components/schemas/DocumentSource","description":"Document source (base64 or URL)"},"document_id":{"type":"string","description":"Unique document identifier (for tracking)"},"document_type":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/DocumentType","description":"Document type hint"}]}}},"DocumentBatchResultDto":{"type":"object","description":"Result for a single document in batch processing","required":["document_id","success"],"properties":{"document_id":{"type":"string","description":"Document ID from the request"},"error":{"type":["string","null"],"description":"Error message (if failed)"},"ingestion_stats":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/IngestionStatsDto","description":"Ingestion statistics (if successful)"}]},"metadata":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ParsedDocumentMetadataDto","description":"Document metadata (if successful)"}]},"parse_stats":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/DocumentParseStatsDto","description":"Parse statistics (if successful)"}]},"success":{"type":"boolean","description":"Whether this document was processed successfully"}}},"DocumentInputDto":{"type":"object","required":["name","content"],"properties":{"content":{"type":"string"},"name":{"type":"string"},"type_hint":{"type":["string","null"]}}},"DocumentMetadataDto":{"type":"object","description":"Metadata about a document","properties":{"created_at":{"type":["string","null"],"description":"Creation date (ISO 8601)"},"source":{"type":["string","null"],"description":"Source URL or path"},"tags":{"type":"array","items":{"type":"string"},"description":"Custom tags"},"title":{"type":["string","null"],"description":"Document title"}}},"DocumentParseStatsDto":{"type":"object","description":"Statistics from document parsing","required":["parse_time_ms","parser_used","pages_processed","tables_extracted","images_extracted"],"properties":{"images_extracted":{"type":"integer","description":"Number of images extracted","minimum":0},"pages_processed":{"type":"integer","description":"Number of pages processed","minimum":0},"parse_time_ms":{"type":"integer","format":"int64","description":"Time spent parsing in milliseconds","minimum":0},"parser_used":{"type":"string","description":"Parser that was used"},"tables_extracted":{"type":"integer","description":"Number of tables extracted","minimum":0},"warnings":{"type":"array","items":{"type":"string"},"description":"Any warnings during parsing"}}},"DocumentParser":{"type":"string","description":"Available document parsers","enum":["docling","dotsocr","olmocr","auto"]},"DocumentProgressDto":{"type":"object","description":"Live progress snapshot for a single document being ingested.","required":["document_id","current_step","current_step_label","current_chunk","total_chunks","chunks_processed","chunks_failed","extraction_strategy","entities_extracted","relations_extracted","relations_integrated","sorts_created","sorts_reused","sorts_reused_semantic","entities_created","entities_merged","entities_filtered","entities_pending_review","reviews_persisted","inference_rules_applied","relations_from_inference","residuations_created","residuations_resumed","references_resolved","references_unresolved","tokens_input","tokens_output","started_at","updated_at","elapsed_seconds","step_log"],"properties":{"chunks_failed":{"type":"integer","description":"Number of chunks that failed.","minimum":0},"chunks_processed":{"type":"integer","description":"Number of chunks fully processed.","minimum":0},"current_chunk":{"type":"integer","description":"Current chunk index (0-based).","minimum":0},"current_chunk_preview":{"type":["string","null"],"description":"Preview of the chunk currently being processed."},"current_step":{"type":"string","description":"Current pipeline step (e.g., \"chunking\", \"llm_extraction\", \"sort_reconciliation\")."},"current_step_label":{"type":"string","description":"Human-readable label for the current step."},"discovered_entity_types":{"type":"array","items":{"type":"string"},"description":"Entity types discovered during schema discovery."},"discovered_relation_types":{"type":"array","items":{"type":"string"},"description":"Relation types discovered during schema discovery."},"document_id":{"type":"string","format":"uuid","description":"Document ID."},"domain_summary":{"type":["string","null"],"description":"Domain summary from schema discovery."},"elapsed_seconds":{"type":"integer","format":"int64","description":"Elapsed seconds since start.","minimum":0},"entities_created":{"type":"integer","description":"New entities created.","minimum":0},"entities_extracted":{"type":"integer","description":"Entities extracted so far.","minimum":0},"entities_filtered":{"type":"integer","description":"Entities filtered out by validation.","minimum":0},"entities_merged":{"type":"integer","description":"Entities merged via deduplication.","minimum":0},"entities_pending_review":{"type":"integer","description":"Entities pending review.","minimum":0},"estimated_cost_usd":{"type":["number","null"],"format":"double","description":"Estimated USD cost."},"extraction_strategy":{"type":"string","description":"Extraction strategy (\"llm\", \"local_ner\", \"hybrid\", \"schema_guided\", \"adaptive\")."},"inference_rules_applied":{"type":"integer","description":"Inference rules applied.","minimum":0},"model_name":{"type":["string","null"],"description":"LLM model name (if applicable)."},"references_resolved":{"type":"integer","description":"References resolved.","minimum":0},"references_unresolved":{"type":"integer","description":"Unresolved references.","minimum":0},"relations_extracted":{"type":"integer","description":"Relations extracted so far.","minimum":0},"relations_from_inference":{"type":"integer","description":"Relations from inference rules.","minimum":0},"relations_integrated":{"type":"integer","description":"Relations integrated as OSF features.","minimum":0},"residuations_created":{"type":"integer","description":"Residuations created (suspended operations).","minimum":0},"residuations_resumed":{"type":"integer","description":"Residuations resumed.","minimum":0},"reviews_persisted":{"type":"integer","description":"Reviews persisted.","minimum":0},"sort_names":{"type":"array","items":{"type":"string"},"description":"Sort names created or reused."},"sorts_created":{"type":"integer","description":"New sorts created.","minimum":0},"sorts_reused":{"type":"integer","description":"Existing sorts reused (exact match).","minimum":0},"sorts_reused_semantic":{"type":"integer","description":"Sorts reused via semantic matching.","minimum":0},"started_at":{"type":"string","description":"When ingestion started (ISO 8601)."},"step_log":{"type":"array","items":{"$ref":"#/components/schemas/StepLogEntryDto"},"description":"Chronological log of pipeline events."},"tokens_input":{"type":"integer","description":"Total input tokens consumed.","minimum":0},"tokens_output":{"type":"integer","description":"Total output tokens consumed.","minimum":0},"total_chunks":{"type":"integer","description":"Total number of chunks in the document.","minimum":0},"updated_at":{"type":"string","description":"Last progress update (ISO 8601)."}}},"DocumentSource":{"oneOf":[{"type":"object","description":"Base64-encoded document content with filename","required":["base64"],"properties":{"base64":{"type":"object","description":"Base64-encoded document content with filename","required":["data","filename"],"properties":{"data":{"type":"string"},"filename":{"type":"string"}}}}},{"type":"object","description":"URL to download the document from","required":["url"],"properties":{"url":{"type":"string","description":"URL to download the document from"}}}],"description":"Source of the document to ingest"},"DocumentStatsDto":{"type":"object","description":"Stats for a single document within a session","required":["document_id","term_ids","sort_names","processing_time_ms","chunks_processed","entities_extracted","relations_extracted","total_tokens"],"properties":{"chunks_processed":{"type":"integer","description":"Number of chunks successfully processed","minimum":0},"completed_at":{"type":["string","null"],"format":"date-time","description":"When ingestion completed"},"document_id":{"type":"string","format":"uuid","description":"Document identifier"},"entities_extracted":{"type":"integer","description":"Number of entities extracted from text","minimum":0},"processing_time_ms":{"type":"integer","format":"int64","description":"Processing time in milliseconds","minimum":0},"relations_extracted":{"type":"integer","description":"Number of relations extracted from text","minimum":0},"sort_names":{"type":"array","items":{"type":"string"},"description":"Names of sorts created/reused"},"term_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"IDs of terms created/updated during ingestion"},"total_tokens":{"type":"integer","description":"Total tokens consumed across all LLM calls","minimum":0}}},"DocumentStatusCounts":{"type":"object","description":"Document status counts DTO","required":["pending","in_progress","complete","failed"],"properties":{"cancelled":{"type":"integer","format":"int64","minimum":0},"complete":{"type":"integer","format":"int64","minimum":0},"failed":{"type":"integer","format":"int64","minimum":0},"in_progress":{"type":"integer","format":"int64","minimum":0},"pending":{"type":"integer","format":"int64","minimum":0}}},"DocumentType":{"type":"string","description":"Supported document types","enum":["pdf","docx","pptx","xlsx","html","image","markdown","unknown"]},"DriveDeficitDto":{"type":"object","description":"Drive deficit DTO representing a drive below its baseline.","required":["drive_type","deficit","urgency"],"properties":{"deficit":{"type":"number","format":"double","description":"How much below baseline (0.0 to 1.0)"},"drive_type":{"type":"string","description":"Drive type (curiosity, competence, social, autonomy)"},"urgency":{"type":"number","format":"double","description":"Priority/urgency for addressing this deficit (0.0 to 1.0)"}}},"DriveDto":{"type":"object","description":"Drive state DTO representing an intrinsic drive (Self-Determination Theory).","required":["drive_type","activation","baseline","decay_rate"],"properties":{"activation":{"type":"number","format":"double","description":"Current activation level (0.0 to 1.0)"},"baseline":{"type":"number","format":"double","description":"Baseline level (0.0 to 1.0)"},"decay_rate":{"type":"number","format":"double","description":"Decay rate for drive satiation"},"drive_type":{"type":"string","description":"Drive type (curiosity, competence, social, autonomy)"}}},"DynamicAddSortRequest":{"type":"object","description":"Request for dynamic sort addition (Phase 6).","required":["sort_name"],"properties":{"feature_names":{"type":"array","items":{"type":"string"},"description":"Feature names associated with this sort."},"parent_sort_names":{"type":"array","items":{"type":"string"},"description":"Names of parent sorts in the hierarchy."},"sort_name":{"type":"string","description":"Name of the new sort."}}},"DynamicAddSortResponse":{"type":"object","description":"Response for dynamic sort addition.","required":["sort_id","sort_index","initialization","adaptation_time_us","predictions_preserved","max_deviation"],"properties":{"adaptation_time_us":{"type":"integer","format":"int64","minimum":0},"initialization":{"type":"string"},"max_deviation":{"type":"number","format":"double"},"predictions_preserved":{"type":"boolean"},"sort_id":{"type":"string","format":"uuid"},"sort_index":{"type":"integer","minimum":0},"verification":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/CdlVerificationDto"}]}}},"DynamicDiscoveryRequest":{"type":"object","properties":{"alpha":{"type":["number","null"],"format":"double","description":"Significance level for independence testing (default: 0.05)"},"edge_threshold":{"type":["number","null"],"format":"double","description":"Hybrid-specific: edge confidence threshold (default: 0.5)"},"mcmc_burn_in":{"type":["integer","null"],"description":"MCMC-specific: burn-in period (default: 100)","minimum":0},"mcmc_samples":{"type":["integer","null"],"description":"MCMC-specific: number of samples (default: 500)","minimum":0},"min_samples":{"type":["integer","null"],"description":"Minimum samples before discovery (default: 30)","minimum":0},"strategy":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/DiscoveryStrategy","description":"Structure learning strategy (default: \"pc\")\n- \"pc\": Constraint-based PC algorithm\n- \"mcmc\": Bayesian MCMC structure learning\n- \"hybrid\": PC skeleton + MCMC orientation (best of both)"}]},"temporal_tiers":{"type":["array","null"],"items":{"type":"array","items":{"type":"string"}},"description":"Temporal tiers for background knowledge (tPC algorithm)\nEach tier is a list of variables that belong to that temporal tier.\nTiers are ordered from past to future (tier 0 = earliest).\nReference: Andrews et al. (2024) Int. J. Epidemiol."},"use_active_learning":{"type":["boolean","null"],"description":"Enable active learning recommendations (default: true)"},"use_ges":{"type":["boolean","null"],"description":"Enable GES refinement (default: true)"}}},"DynamicDiscoveryResponse":{"type":"object","required":["success","state","relationships","uncertain_edges","recommended_interventions","strategy"],"properties":{"edge_posteriors":{"type":["array","null"],"items":{"$ref":"#/components/schemas/EdgePosteriorDto"},"description":"Edge posteriors (for Hybrid/MCMC strategies)\nMaps (from, to) -> probability"},"ges_result":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/GESResultDto","description":"GES refinement result"}]},"proof_tree":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/DiscoveryProofTreeDto","description":"Proof tree for audit trail"}]},"recommended_interventions":{"type":"array","items":{"$ref":"#/components/schemas/InterventionRecommendationDto"},"description":"Recommended interventions to resolve uncertainty"},"relationships":{"type":"array","items":{"$ref":"#/components/schemas/CausalRelationshipDto"},"description":"Discovered causal relationships"},"skeleton":{"type":["array","null"],"items":{"type":"array","items":false,"prefixItems":[{"type":"string"},{"type":"string"}]},"description":"Skeleton edges (for Hybrid strategy)\nThese are edges discovered by PC that passed CI tests"},"state":{"$ref":"#/components/schemas/DiscoveryStateDto","description":"Current state of discovery"},"strategy":{"type":"string","description":"Strategy used for discovery"},"success":{"type":"boolean","description":"Whether discovery was successful"},"uncertain_edges":{"type":"array","items":{"$ref":"#/components/schemas/UncertainEdgeDto"},"description":"Uncertain edges (direction unknown)"}}},"DynamicQueryClauseDto":{"type":"object","description":"A dynamic query clause","required":["feature","pattern"],"properties":{"feature":{"type":"string","description":"Feature name"},"pattern":{"$ref":"#/components/schemas/ValuePatternDto","description":"Pattern to match"}}},"DynamicQueryGroupDto":{"type":"object","description":"A group result from dynamic query (when group_by is used)","required":["key","entities","count"],"properties":{"count":{"type":"integer","description":"Count of entities in group","minimum":0},"entities":{"type":"array","items":{"$ref":"#/components/schemas/DynamicQueryResultDto"},"description":"Entities in this group"},"key":{"type":"object","description":"Group key values","additionalProperties":{},"propertyNames":{"type":"string"}}}},"DynamicQueryRequest":{"type":"object","description":"Request for dynamic query building\n\nBuild and execute queries using pattern matching on features.\nSupports complex predicates, variable bindings, and aggregations.","required":["clauses"],"properties":{"clauses":{"type":"array","items":{"$ref":"#/components/schemas/DynamicQueryClauseDto"},"description":"Query clauses (all must match - conjunction)"},"descending":{"type":"boolean","description":"Optional: sort descending"},"group_by":{"type":"array","items":{"type":"string"},"description":"Optional: group by features"},"limit":{"type":"integer","description":"Maximum number of results","minimum":0},"open":{"type":"boolean","description":"Whether additional features are allowed (open) or exact match required (closed)"},"project":{"type":"array","items":{"type":"string"},"description":"Optional: project only specific features in results"},"sort_by":{"type":["string","null"],"description":"Optional: sort by feature"}}},"DynamicQueryResponse":{"type":"object","description":"Response from dynamic query","required":["total_matches","duration_us"],"properties":{"duration_us":{"type":"integer","format":"int64","description":"Query time in microseconds","minimum":0},"groups":{"type":"array","items":{"$ref":"#/components/schemas/DynamicQueryGroupDto"},"description":"Grouped results (when group_by is used)"},"results":{"type":"array","items":{"$ref":"#/components/schemas/DynamicQueryResultDto"},"description":"Query results (when not grouping)"},"total_matches":{"type":"integer","description":"Total matches found","minimum":0}}},"DynamicQueryResultDto":{"type":"object","description":"A result from dynamic query","required":["id","sort_name","features"],"properties":{"bindings":{"type":"object","description":"Variable bindings (from Bind patterns)","additionalProperties":{},"propertyNames":{"type":"string"}},"features":{"type":"object","description":"Matched/projected features","additionalProperties":{},"propertyNames":{"type":"string"}},"id":{"type":"string","format":"uuid","description":"Entity ID"},"sort_name":{"type":"string","description":"Entity's sort name"}}},"E2eTrainingRequest":{"type":"object","description":"Request body for the E2E differentiable training endpoint.","properties":{"epochs":{"type":"integer","description":"Number of training epochs to run.","minimum":0},"ground_truth":{"type":"array","items":{"$ref":"#/components/schemas/GroundTruthEntry"},"description":"Ground truth facts: term_id → expected label (1.0 = should be derived, 0.0 = should not).\nIf empty, all facts in the knowledge base are used as positive ground truth."},"max_facts":{"type":"integer","description":"Maximum facts derived before stopping.","minimum":0},"max_iterations":{"type":"integer","description":"Maximum forward chaining iterations per epoch.","minimum":0}}},"E2eTrainingResponse":{"type":"object","description":"Response for the E2E differentiable training endpoint.","required":["triggered","epochs_completed","epoch_results","message"],"properties":{"epoch_results":{"type":"array","items":{"type":"object"},"description":"Per-epoch training results."},"epochs_completed":{"type":"integer","description":"Number of epochs completed.","minimum":0},"error":{"type":["string","null"],"description":"Error message if training failed."},"final_accuracy":{"type":["number","null"],"format":"double","description":"Final accuracy (last epoch)."},"final_loss":{"type":["number","null"],"format":"double","description":"Final loss (last epoch)."},"initial_loss":{"type":["number","null"],"format":"double","description":"Initial loss (first epoch)."},"message":{"type":"string","description":"Human-readable summary message."},"triggered":{"type":"boolean","description":"Whether E2E training was triggered successfully."}}},"EdgePosteriorDto":{"type":"object","required":["from","to","probability"],"properties":{"from":{"type":"string","description":"Source variable"},"probability":{"type":"number","format":"double","description":"Posterior probability of this edge direction"},"to":{"type":"string","description":"Target variable"}}},"EdgeTypeDto":{"oneOf":[{"type":"string","enum":["subtype"]},{"type":"string","enum":["multiple_inheritance"]},{"type":"string","enum":["glb_path"]},{"type":"string","enum":["lub_path"]},{"type":"string","enum":["constraint_dependency"]},{"type":"string","enum":["propagation"]},{"type":"string","enum":["feature"]},{"type":"string","enum":["coreference"]},{"type":"string","enum":["trigger_dependency"]},{"type":"string","enum":["relation_source"]},{"type":"string","enum":["relation_target"]},{"type":"object","required":["custom"],"properties":{"custom":{"type":"string"}}}],"description":"Edge type in the graph"},"EffectDto":{"oneOf":[{"type":"object","required":["gaussian"],"properties":{"gaussian":{"type":"object","required":["mean","std_dev"],"properties":{"mean":{"type":"number","format":"double"},"std_dev":{"type":"number","format":"double"}}}}},{"type":"object","required":["triangular"],"properties":{"triangular":{"type":"object","required":["a","b","c"],"properties":{"a":{"type":"number","format":"double"},"b":{"type":"number","format":"double"},"c":{"type":"number","format":"double"}}}}},{"type":"object","required":["trapezoidal"],"properties":{"trapezoidal":{"type":"object","required":["a","b","c","d"],"properties":{"a":{"type":"number","format":"double"},"b":{"type":"number","format":"double"},"c":{"type":"number","format":"double"},"d":{"type":"number","format":"double"}}}}},{"type":"object","required":["sigmoid"],"properties":{"sigmoid":{"type":"object","required":["midpoint","steepness"],"properties":{"midpoint":{"type":"number","format":"double"},"steepness":{"type":"number","format":"double"}}}}},{"type":"object","required":["bell"],"properties":{"bell":{"type":"object","required":["center","width","slope"],"properties":{"center":{"type":"number","format":"double"},"slope":{"type":"number","format":"double"},"width":{"type":"number","format":"double"}}}}},{"type":"object","required":["sigmoid_difference"],"properties":{"sigmoid_difference":{"type":"object","required":["midpoint1","steepness1","midpoint2","steepness2"],"properties":{"midpoint1":{"type":"number","format":"double"},"midpoint2":{"type":"number","format":"double"},"steepness1":{"type":"number","format":"double"},"steepness2":{"type":"number","format":"double"}}}}},{"type":"object","required":["gaussian_product"],"properties":{"gaussian_product":{"type":"object","required":["mean1","std_dev1","mean2","std_dev2"],"properties":{"mean1":{"type":"number","format":"double"},"mean2":{"type":"number","format":"double"},"std_dev1":{"type":"number","format":"double"},"std_dev2":{"type":"number","format":"double"}}}}},{"type":"object","required":["sigmoid_product"],"properties":{"sigmoid_product":{"type":"object","required":["midpoint1","steepness1","midpoint2","steepness2"],"properties":{"midpoint1":{"type":"number","format":"double"},"midpoint2":{"type":"number","format":"double"},"steepness1":{"type":"number","format":"double"},"steepness2":{"type":"number","format":"double"}}}}},{"type":"object","required":["cosine"],"properties":{"cosine":{"type":"object","required":["center","width"],"properties":{"center":{"type":"number","format":"double"},"width":{"type":"number","format":"double"}}}}},{"type":"object","required":["spike"],"properties":{"spike":{"type":"object","required":["center","width"],"properties":{"center":{"type":"number","format":"double"},"width":{"type":"number","format":"double"}}}}},{"type":"object","required":["cauchy"],"properties":{"cauchy":{"type":"object","required":["center","gamma"],"properties":{"center":{"type":"number","format":"double"},"gamma":{"type":"number","format":"double"}}}}},{"type":"object","required":["s_shape"],"properties":{"s_shape":{"type":"object","required":["a","b"],"properties":{"a":{"type":"number","format":"double"},"b":{"type":"number","format":"double"}}}}},{"type":"object","required":["z_shape"],"properties":{"z_shape":{"type":"object","required":["a","b"],"properties":{"a":{"type":"number","format":"double"},"b":{"type":"number","format":"double"}}}}},{"type":"object","required":["pi_shape"],"properties":{"pi_shape":{"type":"object","required":["a","b","c","d"],"properties":{"a":{"type":"number","format":"double"},"b":{"type":"number","format":"double"},"c":{"type":"number","format":"double"},"d":{"type":"number","format":"double"}}}}},{"type":"object","required":["piecewise_linear"],"properties":{"piecewise_linear":{"type":"object","required":["points"],"properties":{"points":{"type":"array","items":{"type":"array","items":false,"prefixItems":[{"type":"number","format":"double"},{"type":"number","format":"double"}]}}}}}}],"description":"FuzzyNumber shape for effect prediction response"},"EffectPredictionDto":{"type":"object","required":["mean","std_dev","confidence"],"properties":{"confidence":{"type":"number","format":"double"},"mean":{"type":"number","format":"double"},"std_dev":{"type":"number","format":"double"}}},"EloSummaryDto":{"type":"object","description":"Elo rating summary.","required":["matches_played","ratings"],"properties":{"matches_played":{"type":"integer","description":"Number of pairwise matches played.","minimum":0},"ratings":{"type":"array","items":{"type":"number","format":"double"},"description":"Per-sample final Elo rating in the same index order as `samples`."}}},"EmbeddingVerificationResponse":{"type":"object","description":"Response for the embedding verification endpoint.","required":["available"],"properties":{"available":{"type":"boolean","description":"Whether box embeddings are available."},"containment":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ContainmentVerificationDto","description":"Containment verification result."}]},"embedding_dim":{"type":["integer","null"],"description":"Embedding dimensionality.","minimum":0},"error":{"type":["string","null"],"description":"Error message if verification failed."},"meet_preservation":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/MeetPreservationDto","description":"Meet-preservation verification result."}]},"sort_count":{"type":["integer","null"],"description":"Number of sorts with embeddings.","minimum":0},"specificity":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/SpecificityDto","description":"Volume-specificity verification result."}]}}},"EnrichedHealthResponse":{"type":"object","description":"Enriched health response with component statuses and build info","required":["status","components","build_info"],"properties":{"build_info":{"$ref":"#/components/schemas/BuildInfoDto"},"components":{"type":"array","items":{"$ref":"#/components/schemas/ComponentHealthDto"}},"status":{"type":"string"}}},"EntailmentRequest":{"type":"object","description":"Request for entailment check.\n\nChecks if antecedent entails consequent given known facts.","required":["antecedent","consequent"],"properties":{"antecedent":{"$ref":"#/components/schemas/TermInputDto","description":"Antecedent clause (if this holds...)"},"consequent":{"$ref":"#/components/schemas/TermInputDto","description":"Consequent clause (...then this must hold)"},"facts":{"type":"array","items":{"$ref":"#/components/schemas/TermInputDto"},"description":"Known facts"}}},"EntailmentResponse":{"type":"object","description":"Response from entailment check.","required":["entails","confidence","computation_time_ms"],"properties":{"computation_time_ms":{"type":"integer","format":"int64","description":"Computation time in milliseconds","minimum":0},"confidence":{"type":"number","format":"double","description":"Confidence degree"},"entails":{"type":"boolean","description":"Whether antecedent entails consequent"}}},"EntityDto":{"type":"object","description":"A lightweight entity representation for verification requests.","required":["sort_id","features"],"properties":{"features":{"type":"object","description":"Feature name-value pairs.","additionalProperties":{},"propertyNames":{"type":"string"}},"sort_id":{"type":"string","format":"uuid","description":"Sort ID this entity belongs to."}}},"EntityMergeAuditDto":{"type":"object","description":"Audit record for one substring-based entity merge.","required":["merged_from_id","merged_from_name","merged_from_sort","merged_into_id","merged_into_name","merged_into_sort"],"properties":{"merged_from_id":{"type":"string","format":"uuid","description":"Term ID of the entity that was merged away (the shorter form)."},"merged_from_name":{"type":"string","description":"Name of the merged-away entity."},"merged_from_sort":{"type":"string","description":"Original sort name of the merged-away entity."},"merged_into_id":{"type":"string","format":"uuid","description":"Term ID of the surviving entity (the longer/canonical form)."},"merged_into_name":{"type":"string","description":"Name of the surviving entity."},"merged_into_sort":{"type":"string","description":"Sort name of the surviving entity (which won the merge)."}}},"EntityVerificationDetailDto":{"type":"object","description":"Per-entity verification detail.","required":["ground_truth_id","sort_similarity","feature_recovery","entity_score","matched","recovered_features","missing_features","mismatched_features","extra_features"],"properties":{"entity_score":{"type":"number","format":"double","description":"Combined entity score."},"extra_features":{"type":"array","items":{"type":"string"},"description":"Extra features in extraction not in ground truth."},"extracted_id":{"type":["string","null"],"format":"uuid","description":"Matched extracted term ID (if any)."},"feature_recovery":{"type":"number","format":"double","description":"Feature recovery rate (0.0-1.0)."},"ground_truth_id":{"type":"string","format":"uuid","description":"Ground truth term ID."},"matched":{"type":"boolean","description":"Whether this entity was considered matched."},"mismatched_features":{"type":"array","items":{"$ref":"#/components/schemas/FeatureMismatchDto"},"description":"Features present but with mismatched values."},"missing_features":{"type":"array","items":{"type":"string"},"description":"Features missing from extraction."},"recovered_features":{"type":"array","items":{"type":"string"},"description":"Features successfully recovered."},"sort_similarity":{"type":"number","format":"double","description":"Sort similarity score (0.0-1.0)."}}},"EpisodeDto":{"type":"object","description":"Episode DTO.","required":["id","goal_id","outcome","reward","timestamp"],"properties":{"goal_id":{"type":"string","format":"uuid","description":"Goal pursued"},"goal_sort":{"type":["string","null"],"description":"Sort name of the episode's goal"},"id":{"type":"string","format":"uuid","description":"Episode ID"},"outcome":{"type":"string","description":"Outcome"},"reward":{"type":"number","format":"double","description":"Reward"},"timestamp":{"type":"string","description":"Timestamp"}}},"EpisodeOutcomeDto":{"type":"string","description":"Episode outcome type.","enum":["success","failure","partial"]},"EpisodeStatsResponse":{"type":"object","description":"Episode statistics.","required":["total_episodes","successes","failures","success_rate","average_reward"],"properties":{"average_reward":{"type":"number","format":"double","description":"Average reward"},"failures":{"type":"integer","description":"Failed episodes","minimum":0},"success_rate":{"type":"number","format":"double","description":"Success rate"},"successes":{"type":"integer","description":"Successful episodes","minimum":0},"total_episodes":{"type":"integer","description":"Total episodes","minimum":0}}},"EquivalenceClass":{"type":"object","description":"An equivalence class of sorts","required":["sort_ids","size"],"properties":{"size":{"type":"integer","description":"Number of sorts in the class","minimum":0},"sort_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Sort IDs in this equivalence class"}}},"ErrorResponse":{"type":"object","description":"JSON error response for consistent API error format.","required":["error"],"properties":{"error":{"type":"string"}}},"EvalBuiltinRequest":{"type":"object","description":"Request to evaluate a built-in function","required":["function_name","arguments"],"properties":{"arguments":{"type":"array","items":{"type":"object"}},"function_name":{"type":"string"}}},"EvalBuiltinResponse":{"oneOf":[{"type":"object","description":"Evaluation succeeded with a value","required":["result","status"],"properties":{"result":{"type":"object"},"status":{"type":"string","enum":["success"]}}},{"type":"object","description":"Evaluation succeeded (no return value, like predicates)","required":["status"],"properties":{"status":{"type":"string","enum":["success_unit"]}}},{"type":"object","description":"Evaluation failed (predicate returned false)","required":["status"],"properties":{"status":{"type":"string","enum":["failure"]}}},{"type":"object","description":"Evaluation suspended (needs more information)","required":["blocking_arg_index","status"],"properties":{"blocking_arg_index":{"type":"integer","minimum":0},"status":{"type":"string","enum":["residuate"]}}},{"type":"object","description":"Error during evaluation","required":["message","status"],"properties":{"message":{"type":"string"},"status":{"type":"string","enum":["error"]}}}],"description":"Response from evaluation"},"EvalFunctionInfoDto":{"type":"object","description":"Information about an eval function","required":["name","category","description"],"properties":{"arity":{"type":["integer","null"],"minimum":0},"category":{"type":"string"},"description":{"type":"string"},"name":{"type":"string"}}},"EvaluateFunctionRequest":{"type":"object","description":"Request to evaluate a function","required":["tenant_id","function_name","arguments"],"properties":{"arguments":{"type":"array","items":{"$ref":"#/components/schemas/FunctionValueDto"}},"function_name":{"type":"string"},"max_depth":{"type":"integer","default":100,"minimum":0},"tenant_id":{"type":"string","format":"uuid"}}},"EvaluateFunctionResponse":{"oneOf":[{"type":"object","description":"Function evaluated to a value","required":["value","result_type"],"properties":{"result_type":{"type":"string","enum":["Value"]},"value":{"$ref":"#/components/schemas/FunctionValueDto"}}},{"type":"object","description":"Function suspended due to insufficient information","required":["reason","result_type"],"properties":{"reason":{"type":"string"},"result_type":{"type":"string","enum":["Suspend"]}}}],"description":"Response from function evaluation"},"EvaluatePatternRequest":{"type":"object","description":"Request to evaluate a learned pattern on new inputs.","required":["pattern_id","inputs"],"properties":{"inputs":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Input values to evaluate."},"max_depth":{"type":"integer","description":"Maximum recursion depth. Default: 100","minimum":0},"pattern_id":{"type":"string","description":"Pattern ID from learn_pattern response."}}},"EvaluatePatternResponse":{"type":"object","description":"Response from pattern evaluation.","required":["success","results","processing_time_ms"],"properties":{"processing_time_ms":{"type":"integer","description":"Processing time in milliseconds.","minimum":0},"results":{"type":"array","items":{"$ref":"#/components/schemas/EvaluationResult"},"description":"Results for each input."},"success":{"type":"boolean","description":"Whether all evaluations succeeded."}}},"EvaluatedValueDto":{"type":"object","description":"A value that was evaluated","required":["term_name"],"properties":{"comparison":{"type":["string","null"]},"term_name":{"type":"string"},"threshold":{"type":["string","null"]},"value":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ExecutionValueDto"}]}}},"EvaluationResult":{"type":"object","description":"A single evaluation result.","required":["input"],"properties":{"error":{"type":["string","null"],"description":"Error message (if failed)."},"input":{"type":"integer","format":"int64","description":"Input value."},"output":{"type":["integer","null"],"format":"int64","description":"Computed output value (if successful)."}}},"EvidenceAssessmentRequest":{"type":"object","description":"Request for evidence-based assessment\n\nThis is a GENERIC system for assessing truthfulness/validity of any subject\nbased on related evidence. Works for:\n- Health claims (subject: claim, evidence: studies, reviews)\n- News articles (subject: article, evidence: sources, fact-checks)\n- Scientific hypotheses (subject: hypothesis, evidence: experiments)\n- Any domain with subject-evidence relationships\n\n# Example (Health Claim Assessment):\n```json\n{\n \"tenant_id\": \"...\",\n \"subject_id\": \"claim-uuid\",\n \"evidence_sort_id\": \"evidence-sort-uuid\",\n \"evidence_link_field\": \"claim_id\",\n \"support_field\": \"supports_claim\",\n \"quality_field\": \"quality_weight\",\n \"quality_threshold\": 0.7,\n \"aggregation_strategy\": \"product\"\n}\n```","required":["subject_id","evidence_sort_id","evidence_link_field","support_field","quality_field"],"properties":{"aggregation_strategy":{"type":["string","null"],"description":"T-norm aggregation strategy: \"product\" (default), \"min\", \"lukasiewicz\""},"evidence_link_field":{"type":"string","description":"Field in evidence that links to the subject (e.g., \"claim_id\")\nEvidence with this field matching subject_id will be included"},"evidence_sort_id":{"type":"string","format":"uuid","description":"Sort ID of evidence terms"},"penalty_field":{"type":["string","null"],"description":"Optional penalty field (0.0-1.0) applied to final score\ne.g., \"manipulation_penalty\" for detected manipulation signals"},"quality_field":{"type":"string","description":"Field in evidence containing quality weight (0.0-1.0)\ne.g., \"quality_weight\" for evidence pyramid position"},"quality_threshold":{"type":"number","format":"double","description":"Quality threshold for residuation (default: 0.7)\nIf max evidence quality < threshold, assessment is residuated (suspended)"},"subject_id":{"type":"string","format":"uuid","description":"The subject term ID to assess (e.g., health claim, news article)"},"subject_penalty_field":{"type":["string","null"],"description":"Optional field containing penalty value on the subject term"},"support_field":{"type":"string","description":"Field in evidence indicating support (true) or contradiction (false)\ne.g., \"supports_claim\" with Boolean value"}}},"EvidenceAssessmentResponse":{"type":"object","description":"Response from evidence-based assessment","required":["subject_id","truthfulness","label","color","residuated","supporting_evidence","contradicting_evidence","evidence_count","max_quality","avg_support_quality","avg_contradict_quality","explanation","computation_time_ms"],"properties":{"avg_contradict_quality":{"type":"number","format":"double","description":"Average quality of contradicting evidence"},"avg_support_quality":{"type":"number","format":"double","description":"Average quality of supporting evidence"},"color":{"type":"string","description":"CSS color for UI display (hex format, e.g., \"#52c41a\")"},"computation_time_ms":{"type":"integer","format":"int64","description":"Computation time in milliseconds","minimum":0},"contradicting_evidence":{"type":"array","items":{"$ref":"#/components/schemas/EvidenceItemDto"},"description":"Contradicting evidence items"},"evidence_count":{"type":"integer","description":"Total evidence count","minimum":0},"explanation":{"type":"array","items":{"type":"string"},"description":"Explanation trace (list of reasoning steps)"},"label":{"type":"string","description":"Human-readable label based on truthfulness score\ne.g., \"High Confidence True\", \"Likely False\", \"Insufficient Evidence\""},"max_quality":{"type":"number","format":"double","description":"Maximum quality weight among all evidence"},"penalty_applied":{"type":["number","null"],"format":"double","description":"Penalty applied (if any)"},"residuated":{"type":"boolean","description":"Whether assessment is residuated (suspended due to insufficient evidence)"},"residuation_reason":{"type":["string","null"],"description":"Reason for residuation if applicable"},"residuation_trigger":{"type":["string","null"],"description":"Trigger that would lift residuation"},"score_before_penalty":{"type":["number","null"],"format":"double","description":"Score before penalty was applied"},"subject_id":{"type":"string","format":"uuid","description":"Subject term ID that was assessed"},"supporting_evidence":{"type":"array","items":{"$ref":"#/components/schemas/EvidenceItemDto"},"description":"Supporting evidence items"},"truthfulness":{"type":"number","format":"double","description":"Computed truthfulness/validity score (0.0-1.0)\n0.5 = neutral/insufficient, >0.5 = supported, <0.5 = contradicted"}}},"EvidenceDerivationConfigDto":{"type":"object","description":"DTO for evidence derivation configuration (wire format).","properties":{"context_dependent_relations":{"type":"object","description":"Relations whose polarity depends on the target entity's sort.\nMaps relation name → list of target sort names that make it negative.","additionalProperties":{"type":"array","items":{"type":"string"}},"propertyNames":{"type":"string"}},"default_quality_weight":{"type":"number","format":"double","description":"Default quality weight for NER-derived evidence (0.0-1.0)."},"evidence_sort_name":{"type":"string","description":"Sort name to use for derived evidence terms."},"negative_relations":{"type":"array","items":{"type":"string"},"description":"Relation names that indicate contradiction."},"positive_relations":{"type":"array","items":{"type":"string"},"description":"Relation names that indicate support."}}},"EvidenceItemDto":{"type":"object","description":"A single piece of evidence used in assessment","required":["term_id","supports","quality_weight","contribution"],"properties":{"contribution":{"type":"number","format":"double","description":"Contribution to the assessment (quality * support direction)"},"quality_weight":{"type":"number","format":"double","description":"Quality weight of this evidence (0.0-1.0)"},"supports":{"type":"boolean","description":"Whether this evidence supports (true) or contradicts (false) the subject"},"term_id":{"type":"string","format":"uuid","description":"Evidence term ID"}}},"EvidenceSourceDto":{"oneOf":[{"type":"object","required":["type"],"properties":{"relation_term_id":{"type":["string","null"]},"type":{"type":"string","enum":["Explicit"]}}},{"type":"object","required":["unified_degree","type"],"properties":{"type":{"type":"string","enum":["Emergent"]},"unified_degree":{"type":"number","format":"double"}}},{"type":"object","required":["unified_degree","type"],"properties":{"relation_term_id":{"type":["string","null"]},"type":{"type":"string","enum":["Both"]},"unified_degree":{"type":"number","format":"double"}}}],"description":"Evidence source DTO"},"ExecutionGoalDto":{"oneOf":[{"type":"object","required":["type","term1_id","term2_id"],"properties":{"eval_flag":{"type":"boolean"},"term1_id":{"type":"string"},"term2_id":{"type":"string"},"type":{"type":"string","enum":["unify"]}}},{"type":"object","required":["type","predicate_name","arguments"],"properties":{"arguments":{"type":"array","items":{"type":"string"}},"predicate_name":{"type":"string"},"type":{"type":"string","enum":["prove"]}}},{"type":"object","required":["type","function_name","arguments","result_var"],"properties":{"arguments":{"type":"array","items":{"type":"string"}},"function_name":{"type":"string"},"result_var":{"type":"string"},"type":{"type":"string","enum":["eval"]}}},{"type":"object","required":["type","term_id","types"],"properties":{"term_id":{"type":"string"},"type":{"type":"string","enum":["type_disj"]},"types":{"type":"array","items":{"type":"string"}}}},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["cut"]}}},{"type":"object","required":["type","condition","then_goal","else_goal"],"properties":{"condition":{"$ref":"#/components/schemas/ExecutionGoalDto"},"else_goal":{"$ref":"#/components/schemas/ExecutionGoalDto"},"then_goal":{"$ref":"#/components/schemas/ExecutionGoalDto"},"type":{"type":"string","enum":["if_then_else"]}}}],"title":"ExecutionGoalDto","description":"Execution engine goal, discriminated by the 'type' field. Variants: unify, prove, eval, type_disj, cut, if_then_else.","discriminator":{"propertyName":"type"}},"ExecutionSessionResponse":{"type":"object","description":"Response with session ID","required":["session_id","tenant_id","trail_length","choice_point_count","bindings_count"],"properties":{"bindings_count":{"type":"integer","minimum":0},"choice_point_count":{"type":"integer","minimum":0},"session_id":{"type":"string"},"tenant_id":{"type":"string","format":"uuid"},"trail_length":{"type":"integer","minimum":0}}},"ExecutionValueDto":{"oneOf":[{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["integer"]},"value":{"type":"integer","format":"int64"}}},{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["real"]},"value":{"type":"number","format":"double"}}},{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["string"]},"value":{"type":"string"}}},{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["boolean"]},"value":{"type":"boolean"}}},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["uninstantiated"]}}}],"description":"Value types for execution"},"ExplorationCompleteResponseDto":{"type":"object","description":"Response after completing exploration and creating rules.\n\nPOST /api/v1/analysis/attribute-exploration/{session_id}/complete","required":["total_implications","implications","counterexamples_added","rules_created"],"properties":{"counterexamples_added":{"type":"integer","description":"Number of counterexample objects added during exploration","minimum":0},"implications":{"type":"array","items":{"$ref":"#/components/schemas/ImplicationDto"},"description":"All confirmed implications"},"rules_created":{"type":"integer","description":"Number of sort rules created in the hierarchy","minimum":0},"total_implications":{"type":"integer","description":"Total number of implications in the Duquenne-Guigues basis","minimum":0}}},"ExplorationProgressDto":{"type":"object","description":"Progress of an exploration session.","required":["implications_confirmed","implications_refuted","counterexamples_added","is_complete"],"properties":{"counterexamples_added":{"type":"integer","description":"Number of counterexample objects added to the context","minimum":0},"implications_confirmed":{"type":"integer","description":"Number of implications confirmed by the expert","minimum":0},"implications_refuted":{"type":"integer","description":"Number of implications refuted with counterexamples","minimum":0},"is_complete":{"type":"boolean","description":"Whether the exploration is complete (no more questions)"}}},"ExplorationQuestionDto":{"type":"object","description":"A single implication question for the expert.","required":["premise","conclusion","question_text"],"properties":{"conclusion":{"type":"array","items":{"type":"string"},"description":"Feature names forming the conclusion (right side of implication)"},"premise":{"type":"array","items":{"type":"string"},"description":"Feature names forming the premise (left side of implication)"},"question_text":{"type":"string","description":"Human-readable question text"}}},"ExplorationStatusResponseDto":{"type":"object","description":"Response for session status query.\n\nGET /api/v1/analysis/attribute-exploration/{session_id}/status","required":["session_id","progress","confirmed_implications"],"properties":{"confirmed_implications":{"type":"array","items":{"$ref":"#/components/schemas/ImplicationDto"},"description":"All confirmed implications so far"},"progress":{"$ref":"#/components/schemas/ExplorationProgressDto","description":"Current exploration progress"},"session_id":{"type":"string","description":"Session identifier"}}},"ExportJsonlResponse":{"type":"object","description":"Response with JSONL-formatted training data.","required":["jsonl","example_count"],"properties":{"example_count":{"type":"integer","description":"Number of examples exported.","minimum":0},"jsonl":{"type":"string","description":"JSONL string (one JSON object per line)."}}},"ExpressionDto":{"oneOf":[{"type":"object","required":["name","type"],"properties":{"name":{"type":"string"},"type":{"type":"string","enum":["Variable"]}}},{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["Literal"]},"value":{"$ref":"#/components/schemas/FunctionValueDto"}}},{"type":"object","required":["op","left","right","type"],"properties":{"left":{"$ref":"#/components/schemas/ExpressionDto"},"op":{"$ref":"#/components/schemas/BinaryOperatorDto"},"right":{"$ref":"#/components/schemas/ExpressionDto"},"type":{"type":"string","enum":["BinaryOp"]}}},{"type":"object","required":["function_name","arguments","type"],"properties":{"arguments":{"type":"array","items":{"$ref":"#/components/schemas/ExpressionDto"}},"function_name":{"type":"string"},"type":{"type":"string","enum":["FunctionCall"]}}}],"description":"Arithmetic/logical expression"},"ExtendedAgentStateDto":{"type":"object","description":"Extended agent state DTO with full cognitive state.","required":["agent_id","name","beliefs","goals","intentions","pending_changes","activations","recent_episodes","rule_utilities"],"properties":{"activations":{"type":"array","items":{"$ref":"#/components/schemas/ActivationDto"},"description":"Activation levels for key terms"},"agent_id":{"type":"string","format":"uuid","description":"Agent ID"},"beliefs":{"type":"array","items":{"$ref":"#/components/schemas/AgentBeliefDto"},"description":"Current beliefs"},"goals":{"type":"array","items":{"$ref":"#/components/schemas/AgentGoalDto"},"description":"Current goals (desires)"},"intentions":{"type":"array","items":{"$ref":"#/components/schemas/IntentionDto"},"description":"Current intentions (committed plans)"},"motivation":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/MotivationStateDto","description":"Motivation state (drives, deficits, curiosity targets)"}]},"name":{"type":"string","description":"Agent name"},"pending_changes":{"type":"array","items":{"$ref":"#/components/schemas/KbChangeDto"},"description":"Pending KB changes (perceptions)"},"recent_episodes":{"type":"array","items":{"$ref":"#/components/schemas/EpisodeDto"},"description":"Recent episodes"},"rule_utilities":{"type":"array","items":{"$ref":"#/components/schemas/RuleUtilityDto"},"description":"Rule utility summary"}}},"ExternalActionSummaryDto":{"type":"object","description":"Summary of a registered external action.","required":["action_id","name","webhook_url","required_inputs","outputs","enabled"],"properties":{"action_id":{"type":"string","description":"Action ID"},"description":{"type":["string","null"],"description":"Description"},"enabled":{"type":"boolean","description":"Whether enabled"},"name":{"type":"string","description":"Action name (also the sort name)"},"outputs":{"type":"array","items":{"type":"string"},"description":"Output features"},"required_inputs":{"type":"array","items":{"type":"string"},"description":"Required inputs"},"sort_id":{"type":["string","null"],"format":"uuid","description":"The sort ID created for this action"},"webhook_url":{"type":"string","description":"Webhook URL"}}},"ExtractEntitiesRequest":{"type":"object","description":"Request to extract named entities from text using the tenant's sort hierarchy as labels.\n\nThe extraction uses GLiNER2 (zero-shot NER) with the tenant's sort names as entity labels,\nguaranteeing that all returned entity labels are valid sort names in the knowledge base.","required":["text"],"properties":{"confidence_threshold":{"type":["number","null"],"format":"float","description":"Minimum confidence threshold for entity recognition (0.0-1.0).\nDefaults to 0.5 (GLiNER2 default)."},"labels":{"type":["array","null"],"items":{"type":"string"},"description":"Optional list of specific labels (sort names) to use for extraction.\nIf not provided, all tenant sort names are used as labels."},"text":{"type":"string","description":"The text to extract entities from"}}},"ExtractEntitiesResponse":{"type":"object","description":"Response from entity extraction","required":["entities","processing_time_ms","model","labels_used"],"properties":{"entities":{"type":"array","items":{"$ref":"#/components/schemas/ExtractedEntityDto"},"description":"Extracted entities with their sort labels and text spans"},"labels_used":{"type":"array","items":{"type":"string"},"description":"The labels that were used for extraction (sort names)"},"model":{"type":"string","description":"Model used for extraction (e.g., \"gliner2-large-v2.5\")"},"processing_time_ms":{"type":"integer","format":"int64","description":"Processing time in milliseconds","minimum":0}}},"ExtractImageRequest":{"type":"object","description":"Request to extract concepts from an image using a vision LLM.\n\nSends the image directly to a vision-capable model (e.g., Qwen3-VL) that\nunderstands visual elements, spatial relationships, and diagram semantics.\n\nTenant ID is provided via the `X-Tenant-Id` header.","required":["image","filename","owner_id"],"properties":{"filename":{"type":"string","description":"Original filename (used for media type detection via extension)\nExamples: \"architecture.png\", \"whiteboard.jpg\", \"diagram.webp\""},"image":{"type":"string","description":"Base64-encoded image data"},"instruction":{"type":["string","null"],"description":"Optional domain-specific instruction for the vision LLM.\nExamples:\n- \"Focus on architecture components and their connections\"\n- \"Extract medical entities from this clinical diagram\"\n- \"Identify all labeled boxes and arrows in this flowchart\""},"owner_id":{"type":"string","format":"uuid","description":"Owner ID (user who owns the extracted data)"},"persist":{"type":"boolean","description":"Whether to persist extracted terms to the knowledge base (default: true).\nSet to false for dry-run / preview mode."}}},"ExtractImageResponse":{"type":"object","description":"Response from vision-based image extraction.","required":["success","entities","relations","suggested_sorts","stats","term_ids"],"properties":{"entities":{"type":"array","items":{"$ref":"#/components/schemas/ImageExtractedEntityDto"},"description":"Extracted entities (visual elements identified in the image)"},"error":{"type":["string","null"],"description":"Error message if extraction failed"},"relations":{"type":"array","items":{"$ref":"#/components/schemas/ImageExtractedRelationDto"},"description":"Extracted relations (connections/arrows between entities)"},"stats":{"$ref":"#/components/schemas/ImageExtractionStatsDto","description":"Extraction statistics"},"success":{"type":"boolean","description":"Whether the extraction was successful"},"suggested_sorts":{"type":"array","items":{"$ref":"#/components/schemas/ImageSuggestedSortDto"},"description":"Suggested sorts (new types discovered in the image)"},"term_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"IDs of persisted PsiTerms (empty if persist=false)"}}},"ExtractTaxonomyRequest":{"type":"object","description":"Reasoning-driven taxonomy extraction (paper-inspired path).","required":["target_description"],"properties":{"best_of_n":{"type":"integer","description":"Best-of-N rounds for child expansion under each factor.","minimum":0},"child_hint":{"type":"integer","description":"Max children to request per round.","minimum":0},"max_factors":{"type":"integer","description":"Max top-level factors to request from the LLM.","minimum":0},"min_support":{"type":"integer","description":"Keep only children with support ≥ this count after pooling N rounds.","minimum":0},"target_description":{"type":"string","description":"Free-text dataset description (`y` in the paper)."}}},"ExtractTaxonomyResponse":{"type":"object","description":"Response: proposed factors + per-factor expanded children.","required":["target_description","factors","children_by_factor"],"properties":{"children_by_factor":{"type":"array","items":{"$ref":"#/components/schemas/FactorChildrenDto"},"description":"Per-factor child candidates with support counts."},"factors":{"type":"array","items":{"$ref":"#/components/schemas/ProposedFactorDto"},"description":"Top-level factors proposed by the LLM."},"target_description":{"type":"string","description":"Free-text description echoed back for audit."}}},"ExtractedEntityDto":{"type":"object","description":"A single extracted entity mapped to a valid sort name","required":["text","label","start","end","confidence"],"properties":{"confidence":{"type":"number","format":"float","description":"Confidence score (0.0-1.0)"},"end":{"type":"integer","description":"End character position in the original text","minimum":0},"label":{"type":"string","description":"The sort name label (guaranteed to be a valid sort in the tenant's hierarchy)"},"start":{"type":"integer","description":"Start character position in the original text","minimum":0},"text":{"type":"string","description":"The text span that was recognized in the input"}}},"ExtractionPredictionDto":{"type":"object","description":"A single extraction prediction.","required":["sort_id","confidence","is_correct"],"properties":{"confidence":{"type":"number","format":"double","description":"Model confidence (0.0 to 1.0)."},"feature_name":{"type":["string","null"],"description":"Feature name (if feature-level prediction)."},"is_correct":{"type":"boolean","description":"Whether the prediction was correct."},"sort_id":{"type":"string","format":"uuid","description":"Sort UUID this prediction pertains to."}}},"ExtractionStatsDto":{"type":"object","description":"Statistics about how facts were extracted.","required":["deterministic_facts","semantic_facts","total_llm_calls"],"properties":{"deterministic_facts":{"type":"integer","description":"Number of facts extracted deterministically (no LLM)","minimum":0},"semantic_facts":{"type":"integer","description":"Number of facts extracted via LLM (semantic)","minimum":0},"total_llm_calls":{"type":"integer","description":"Total number of LLM calls made","minimum":0}}},"ExtractionStrategyAdaptive":{"type":"object","description":"Adaptive: auto-select strategy based on learned patterns. The fallback field accepts any ExtractionStrategy variant (e.g. {\"type\": \"llm\"}).","required":["type","fallback"],"properties":{"fallback":{"$ref":"#/components/schemas/ExtractionStrategyDto"},"type":{"type":"string","description":"Discriminator -- always \"adaptive\".","example":"adaptive"}}},"ExtractionStrategyDto":{"oneOf":[{"$ref":"#/components/schemas/ExtractionStrategyLlm"},{"$ref":"#/components/schemas/ExtractionStrategyLocalNer"},{"$ref":"#/components/schemas/ExtractionStrategyHybrid"},{"$ref":"#/components/schemas/ExtractionStrategySchemaGuided"},{"$ref":"#/components/schemas/ExtractionStrategyAdaptive"}],"title":"ExtractionStrategyDto","description":"Extraction strategy — an internally tagged enum discriminated by the 'type' field.\nVariants:\n- `{\"type\": \"llm\"}` — LLM-based extraction\n- `{\"type\": \"local_ner\"}` — local NER model (GLiNER2)\n- `{\"type\": \"hybrid\", \"ner_confidence_threshold\": 0.8}` — NER + LLM fallback\n- `{\"type\": \"schema_guided\", ...}` — NER + pattern-based, LLM when needed\n- `{\"type\": \"adaptive\", \"fallback\": {...}}` — auto-select strategy","discriminator":{"propertyName":"type","mapping":{"adaptive":"#/components/schemas/ExtractionStrategyAdaptive","hybrid":"#/components/schemas/ExtractionStrategyHybrid","llm":"#/components/schemas/ExtractionStrategyLlm","local_ner":"#/components/schemas/ExtractionStrategyLocalNer","schema_guided":"#/components/schemas/ExtractionStrategySchemaGuided"}}},"ExtractionStrategyHybrid":{"type":"object","required":["type","ner_confidence_threshold"],"properties":{"ner_confidence_threshold":{"type":"number","format":"float","description":"NER confidence threshold below which to use LLM (0.0-1.0)."},"type":{"type":"string","description":"Discriminator -- always `\"hybrid\"`.","example":"hybrid"}}},"ExtractionStrategyLlm":{"type":"object","required":["type"],"properties":{"type":{"type":"string","description":"Discriminator -- always `\"llm\"`.","example":"llm"}}},"ExtractionStrategyLocalNer":{"type":"object","required":["type"],"properties":{"type":{"type":"string","description":"Discriminator -- always `\"local_ner\"`.","example":"local_ner"}}},"ExtractionStrategySchemaGuided":{"type":"object","required":["type","ner_confidence_threshold","relation_confidence_threshold","escalate_unknown_types"],"properties":{"escalate_unknown_types":{"type":"boolean","description":"Whether to escalate to LLM for unknown entity types."},"ner_confidence_threshold":{"type":"number","format":"float","description":"NER confidence threshold below which to escalate to LLM (0.0-1.0)."},"relation_confidence_threshold":{"type":"number","format":"float","description":"Relation pattern confidence threshold (0.0-1.0)."},"type":{"type":"string","description":"Discriminator -- always `\"schema_guided\"`.","example":"schema_guided"}}},"FactConfidenceEntry":{"type":"object","description":"A fact confidence entry for tagged forward chaining.","required":["term_id","confidence"],"properties":{"confidence":{"type":"number","format":"double","description":"Confidence value in [0.0, 1.0]."},"term_id":{"type":"string","format":"uuid","description":"The term ID of the fact (UUID)."}}},"FactorChildrenDto":{"type":"object","description":"Children returned by best-of-N expansion under a single factor.","required":["factor","children"],"properties":{"children":{"type":"array","items":{"$ref":"#/components/schemas/ChildCandidateDto"},"description":"Ranked child candidates (highest-support first)."},"factor":{"type":"string","description":"Factor whose children these are."}}},"FactoryResetResponse":{"type":"object","description":"Response for the factory-reset operation.\n\nReports exactly what was wiped across all storage backends\nso operators can verify the operation succeeded.","required":["message","postgres_tables_cleared","qdrant_collections_deleted","cache_cleared","tenant_states_cleared"],"properties":{"cache_cleared":{"type":"boolean","description":"Whether the cache (Valkey / in-memory) was flushed"},"message":{"type":"string","description":"Human-readable summary message"},"postgres_tables_cleared":{"type":"integer","description":"Number of PostgreSQL tables that were truncated","minimum":0},"qdrant_collections_deleted":{"type":"integer","description":"Number of Qdrant vector collections deleted","minimum":0},"tenant_states_cleared":{"type":"boolean","description":"Whether the in-memory tenant inference states were cleared"}}},"FailedReviewDto":{"type":"object","description":"A failed review with reason","required":["review_id","reason"],"properties":{"reason":{"type":"string","description":"Reason for failure"},"review_id":{"type":"string","format":"uuid","description":"The review ID that failed"}}},"FdDomainStateDto":{"type":"object","description":"FD variable domain state","required":["variable_id","is_determined"],"properties":{"is_determined":{"type":"boolean","description":"Whether the variable is determined (single value)"},"max":{"type":["integer","null"],"format":"int64","description":"Maximum value (for range domains)"},"min":{"type":["integer","null"],"format":"int64","description":"Minimum value (for range domains)"},"values":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Current domain values (for enumerated domains)"},"variable_id":{"type":"string","description":"Variable ID"},"variable_name":{"type":["string","null"],"description":"Variable name (if available)"}}},"FeatureBindingDto":{"type":"object","description":"A feature binding","required":["name","value"],"properties":{"name":{"type":"string"},"value":{"$ref":"#/components/schemas/ExecutionValueDto"}}},"FeatureConfigDto":{"type":"object","description":"Feature naming configuration DTO\n\nAllows callers to specify their own feature naming conventions.\nDefaults match common extraction patterns.","properties":{"dependent_feature":{"type":"string","description":"Feature name for dependent/teaches relations (default: \"enables\")"},"id_feature":{"type":"string","description":"Feature name for concept ID (default: \"concept_id\")"},"name_feature":{"type":"string","description":"Feature name for concept name (default: \"name\")"},"prerequisite_feature":{"type":"string","description":"Feature name for prerequisite/requires relations (default: \"requires\")"},"related_feature":{"type":"string","description":"Feature name for related concepts (default: \"related\")"},"searchable_text_feature":{"type":"string","description":"Feature name for searchable text (default: \"searchable_text\")"},"source_feature":{"type":"string","description":"Feature name for source IDs (default: \"source_activity_id\")"}}},"FeatureConstraintDto":{"oneOf":[{"type":"object","description":"Feature must equal this integer","required":["value","type"],"properties":{"type":{"type":"string","enum":["integer_equals"]},"value":{"type":"integer","format":"int64"}}},{"type":"object","description":"Feature must be >= this value","required":["value","type"],"properties":{"type":{"type":"string","enum":["integer_min"]},"value":{"type":"integer","format":"int64"}}},{"type":"object","description":"Feature must be <= this value","required":["value","type"],"properties":{"type":{"type":"string","enum":["integer_max"]},"value":{"type":"integer","format":"int64"}}},{"type":"object","description":"Feature must be in range [min, max]","required":["min","max","type"],"properties":{"max":{"type":"integer","format":"int64"},"min":{"type":"integer","format":"int64"},"type":{"type":"string","enum":["integer_range"]}}},{"type":"object","description":"Feature must equal this string","required":["value","type"],"properties":{"type":{"type":"string","enum":["string_equals"]},"value":{"type":"string"}}},{"type":"object","description":"Feature must be one of these strings","required":["values","type"],"properties":{"type":{"type":"string","enum":["string_one_of"]},"values":{"type":"array","items":{"type":"string"}}}},{"type":"object","description":"Feature (a term reference) must be of this sort","required":["sort","allow_subsorts","type"],"properties":{"allow_subsorts":{"type":"boolean"},"sort":{"type":"string"},"type":{"type":"string","enum":["sort_constraint"]}}},{"type":"object","description":"Feature (a set) must contain this term","required":["term_id","type"],"properties":{"term_id":{"type":"string"},"type":{"type":"string","enum":["set_contains"]}}},{"type":"object","description":"Feature (a set) must NOT contain this term","required":["term_id","type"],"properties":{"term_id":{"type":"string"},"type":{"type":"string","enum":["set_not_contains"]}}}],"description":"Feature constraint for FeatureSetConstraint"},"FeatureDescriptorDto":{"type":"object","description":"API representation of a feature descriptor","required":["name","required"],"properties":{"annotations":{"type":"object","description":"Custom OWL annotations for this feature (e.g., isIdentifier, unit, enumValues)","additionalProperties":{"type":"string"},"propertyNames":{"type":"string"}},"constraint":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ConstraintDto","description":"Optional constraint on the feature value"}]},"expected_sort":{"type":["string","null"],"format":"uuid","description":"Expected sort for the feature value (for nested PSI-terms)"},"expected_type_hint":{"type":["string","null"],"description":"Primitive type hint for LLM extraction (e.g., \"DateTime\", \"Integer\", \"String\", \"Real\")\nUsed to tell the LLM what type of value to extract for this feature.\nIf `expected_sort` is set, it takes precedence over this hint."},"name":{"type":"string","description":"Feature name"},"required":{"type":"boolean","description":"Whether this feature is required"}}},"FeatureInputValueDto":{"oneOf":[{"type":"object","title":"TermRef","description":"Reference to an existing term","required":["term_id"],"properties":{"term_id":{"type":"string","format":"uuid"}}},{"type":"object","title":"Variable","description":"Reference by variable name (unconstrained)","required":["name"],"properties":{"name":{"type":"string"}}},{"type":"object","title":"ConstrainedVariable","description":"Variable with constraint as Ψ-term","required":["name","constraint"],"properties":{"constraint":{"$ref":"#/components/schemas/TermInputDto"},"name":{"type":"string"}}},{"type":"object","title":"InlineTerm","description":"Nested inline term definition","required":["sort_id"],"properties":{"features":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/FeatureInputValueDto"}},"sort_id":{"type":"string","format":"uuid"}}},{"type":"object","title":"InlineTermByName","description":"Nested inline term definition by name (resolved server-side)","required":["sort_name"],"properties":{"features":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/FeatureInputValueDto"}},"sort_name":{"type":"string"}}},{"type":"array","title":"List","items":{"$ref":"#/components/schemas/FeatureInputValueDto"},"description":"List of feature values"},{"type":"string","title":"StringValue","description":"String primitive value"},{"type":"integer","title":"IntegerValue","description":"Integer primitive value"},{"type":"number","title":"NumberValue","description":"Real number primitive value"},{"type":"boolean","title":"BooleanValue","description":"Boolean primitive value"}],"title":"FeatureInputValueDto","description":"Input value for a Ψ-term feature (TRUE HOMOICONICITY). Can be:\n- {term_id: UUID} - reference existing term\n- {name: \"?X\"} - unbound variable\n- {name: \"?X\", constraint: {sort_id: UUID, ...}} - constrained variable\n- {sort_id: UUID, features: {...}} - nested inline term\n- array, string, integer, real, or boolean\n\nConstrained variables follow Aït-Kaci's OSF/LIFE vision where constraints ARE Ψ-terms."},"FeatureMismatchDto":{"type":"object","description":"Detail about a mismatched feature value.","required":["feature_name","expected","actual","similarity"],"properties":{"actual":{"type":"string","description":"Actual value (from extraction)."},"expected":{"type":"string","description":"Expected value (from ground truth)."},"feature_name":{"type":"string","description":"Feature name."},"similarity":{"type":"number","format":"double","description":"Similarity between expected and actual (0.0-1.0)."}}},"FeaturePair":{"type":"object","description":"A pair of feature vectors for the derived inference pipeline.","required":["features_a","features_b"],"properties":{"features_a":{"type":"array","items":{"type":"number","format":"float"}},"features_b":{"type":"array","items":{"type":"number","format":"float"}}}},"FeatureRequirementDto":{"type":"object","description":"A feature requirement for row queries","required":["name"],"properties":{"feature_type":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/FeatureTypeDto","description":"Expected type (optional - Any if not specified)"}]},"name":{"type":"string","description":"Feature name"},"value":{"description":"Expected value (optional - for exact matching)"}}},"FeatureTargetDto":{"oneOf":[{"$ref":"#/components/schemas/TaggedFeatureValueDto"},{"type":"string","description":"Variable reference (e.g., \"?Name\")"}],"title":"FeatureTargetDto","description":"Target of a feature constraint (untagged union). Either:\n- A typed value object (e.g., {\"type\": \"String\", \"value\": \"hello\"})\n- A plain string variable reference (e.g., \"?Name\")"},"FeatureTypeDto":{"type":"string","description":"Feature type specification for row queries","enum":["string","integer","real","boolean","reference","any"]},"FeatureValueDto":{"oneOf":[{"type":"string","description":"Term reference (UUID) or string value"},{"type":"integer","format":"int64","description":"Integer value"},{"type":"number","format":"double","description":"Real number value"},{"type":"boolean","description":"Boolean value"},{"type":"null","description":"Null/uninstantiated value"},{"type":"array","items":{"$ref":"#/components/schemas/FeatureValueDto"},"description":"List of values"}],"title":"FeatureValueDto","description":"Feature value in a Ψ-term (untagged union). Can be:\n- UUID string (term reference)\n- string value\n- integer (i64)\n- number (f64)\n- boolean\n- null\n- array of FeatureValueDto"},"FinalizeSessionRequest":{"type":"object","description":"Request to finalize a live oversight session.","properties":{"execution_log":{"type":["string","null"],"description":"Optional execution log (for full provenance)"},"final_output":{"type":["string","null"],"description":"Optional final output from the agent (for faithfulness check)"}}},"FindBySortRequest":{"type":"object","description":"Request to find terms by sort.\n\nProvide either `sort_id` (UUID) or `sort_name` (String).\nIf both are provided, `sort_id` takes precedence.\n\nAn optional `filter` map restricts results to terms whose features match\nall provided key-value pairs (exact string match).\n\n# Tenant Context\nThe tenant is determined from the `X-Tenant-Id` header.","properties":{"filter":{"type":["object","null"],"description":"Optional feature-level filter. Each entry maps a feature name to the\nexpected string value. Only terms whose features match ALL entries are\nreturned. Omit or pass an empty map to disable filtering.","additionalProperties":{"type":"string"},"propertyNames":{"type":"string"}},"sort_id":{"type":["string","null"],"format":"uuid","description":"Sort ID to search for (takes precedence over sort_name)"},"sort_name":{"type":["string","null"],"description":"Sort name to search for (resolved server-side via SortHierarchy)"}}},"FindPlansRequest":{"type":"object","description":"Request to find matching plans.","required":["tenant_id","agent_id","goal_id"],"properties":{"agent_id":{"type":"string","format":"uuid","description":"Agent ID"},"goal_id":{"type":"string","format":"uuid","description":"Goal to find plans for"},"max_results":{"type":"integer","description":"Maximum number of plans to return","default":10,"minimum":0},"min_score":{"type":"number","format":"double","description":"Minimum match score (0.0-1.0)","default":0.5},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"}}},"FindPlansResponse":{"type":"object","description":"Response with matching plans.","required":["plans","count"],"properties":{"count":{"type":"integer","description":"Total count","minimum":0},"plans":{"type":"array","items":{"$ref":"#/components/schemas/PlanMatchDto"},"description":"Matching plans"}}},"FindRulesRequest":{"type":"object","description":"Request to find matching rules","required":["pattern"],"properties":{"pattern":{"$ref":"#/components/schemas/RuleClauseDto"}}},"FindRulesResponse":{"type":"object","description":"Response with matching rules","required":["matching_rules"],"properties":{"matching_rules":{"type":"array","items":{"$ref":"#/components/schemas/RuleDto"}}}},"FindSimilarRequest":{"allOf":[{"$ref":"#/components/schemas/QueryTerm","description":"Query term (can use PsiTerm JSON representation or just ID)"},{"type":"object","properties":{"fail_on_unknown":{"type":"boolean","description":"Whether to fail unification when encountering unknown data (Uninstantiated) with constraints\nWhen true: recipes with unknown allergen data will be filtered out (safety-critical mode)\nWhen false: residuation is applied, allowing partial matches with unknown data"},"min_degree":{"type":"number","format":"double","description":"Minimum similarity degree (0.0 to 1.0)"},"similarity_mode":{"type":"string","description":"String similarity strategy:\n- \"fast\": Exact → Normalized → Jaccard only (NO embeddings) - fastest\n- \"hybrid\": Exact → Normalized → Jaccard → Embeddings (default)\n- \"semantic\": Exact → Normalized → Embeddings (skip Jaccard) - most accurate for NL","example":"hybrid"}}}],"description":"Request for similarity search"},"FindallRequest":{"type":"object","description":"Request for findall","required":["session_id","template","goal"],"properties":{"goal":{"type":"object","description":"Goal that generates solutions"},"max_solutions":{"type":["integer","null"],"description":"Maximum solutions to collect (None for all)","minimum":0},"session_id":{"type":"string"},"template":{"type":"string","description":"Template term to collect"}}},"FindallResponse":{"type":"object","description":"Response from findall","required":["solutions","count"],"properties":{"count":{"type":"integer","description":"Number of solutions found","minimum":0},"solutions":{"type":"array","items":{"type":"string"},"description":"Collected solutions"}}},"FixSuggestionDto":{"type":"object","description":"A fix suggestion for a violation.","required":["description","confidence"],"properties":{"confidence":{"type":"number","format":"double","description":"Confidence in the fix suggestion (0.0-1.0)"},"description":{"type":"string","description":"Human-readable fix description"},"fix_type":{"type":["string","null"],"description":"Type of fix (e.g., \"add_fact\", \"modify_feature\", \"narrow_sort\", \"add_rule\")"}}},"ForallRequest":{"type":"object","description":"Request for forall","required":["session_id","generator","test"],"properties":{"generator":{"type":"object","description":"Generator goal that produces solutions"},"session_id":{"type":"string"},"test":{"type":"object","description":"Test goal that must succeed for all solutions"}}},"ForallResponse":{"type":"object","description":"Response from forall","required":["result","solutions_tested"],"properties":{"result":{"type":"boolean","description":"True if test succeeded for all generated solutions"},"solutions_tested":{"type":"integer","description":"Number of solutions tested","minimum":0}}},"FormalJudgeRefinementResponse":{"type":"object","description":"Response from the iterative refinement pipeline (paper §4.5).\n\nContains results from each refinement round, plus aggregated statistics.","required":["rounds","total_rounds","converged","total_elapsed_ms"],"properties":{"converged":{"type":"boolean","description":"Whether the final verdict is safe (refinement succeeded)"},"rounds":{"type":"array","items":{"$ref":"#/components/schemas/FormalJudgeResponse"},"description":"Results from each refinement round (first = initial, last = final)"},"total_elapsed_ms":{"type":"integer","format":"int64","description":"Total processing time across all rounds (milliseconds)","minimum":0},"total_rounds":{"type":"integer","description":"Total number of refinement rounds executed","minimum":0}}},"FormalJudgeRequest":{"type":"object","description":"Request to run the FormalJudge oversight pipeline.\n\nContains the user intent, agent trajectory (tool calls + results),\nand optional configuration.","required":["user_intent","trajectory"],"properties":{"config":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/JudgeConfigDto","description":"Optional pipeline configuration overrides"}]},"execution_log":{"type":["string","null"],"description":"Raw execution log (optional, for full provenance)"},"final_output":{"type":["string","null"],"description":"Agent's final output/answer (optional)\nPaper Table 5: `output.final_answer`"},"risk_categories":{"type":["array","null"],"items":{"type":"string"},"description":"Risk categories from the benchmark dataset (e.g., [\"Lead to property loss\", \"Violate laws\"])\nUsed by the 3-agent per-task decomposition pipeline to generate task-specific atomic conditions."},"trajectory":{"type":"array","items":{"$ref":"#/components/schemas/TrajectoryStepDto"},"description":"Agent execution trajectory (ordered list of tool calls + results)\nPaper Table 5: `trajectory.tool_calls`"},"user_intent":{"type":"string","description":"User instruction (what the agent was asked to do)"}}},"FormalJudgeResponse":{"type":"object","description":"Response from the FormalJudge oversight pipeline.","required":["verdict","overall_score","layer_results","violations","fix_suggestions","fabrications_detected","elapsed_ms","extraction_stats"],"properties":{"agent_sub_verdicts":{"type":"array","items":{"$ref":"#/components/schemas/AgentSubVerdictDto"},"description":"Per-agent sub-verdicts for multi-agent trajectories (Gap 4).\nEmpty for single-agent trajectories."},"certificate":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/CertificateDto","description":"Full validity certificate with per-layer attestations (if safe and enabled).\nReplaces the flat `certificate_hash` with structured cryptographic proof."}]},"certificate_hash":{"type":["string","null"],"description":"Merkle root hash of the validity certificate (if safe) — kept for backward compat."},"deception_fact_map":{"type":["object","null"],"description":"Deception fact map: all 25 atomic deception facts (paper Table 6) with boolean answers.\nKeys are fact type names (e.g., \"ToolCallAttempted\", \"FabricatedContent\"),\nvalues are true/false for each atomic fact.","additionalProperties":{"type":"boolean"},"propertyNames":{"type":"string"}},"detected_deception_predicates":{"type":"array","items":{"type":"string"},"description":"Deception predicates that triggered (paper §B.6: φ1-φ4)"},"elapsed_ms":{"type":"integer","format":"int64","description":"Processing time in milliseconds","minimum":0},"extraction_stats":{"$ref":"#/components/schemas/ExtractionStatsDto","description":"Extraction statistics (deterministic vs. semantic)"},"fabrications_detected":{"type":"integer","description":"Number of fabricated facts detected","minimum":0},"faithfulness_score":{"type":["number","null"],"format":"double","description":"Faithfulness/deception detection score (if enabled)"},"fix_suggestions":{"type":"array","items":{"$ref":"#/components/schemas/FixSuggestionDto"},"description":"Actionable fix suggestions for violations"},"is_deceptive":{"type":["boolean","null"],"description":"Whether the master deception predicate Φ_deceptive triggered"},"layer_results":{"type":"array","items":{"$ref":"#/components/schemas/LayerResultDto"},"description":"Per-layer verification results"},"overall_score":{"type":"number","format":"double","description":"Overall aggregated score (T-norm of layer scores, 0.0-1.0)"},"proof_traces":{"type":"array","items":{"$ref":"#/components/schemas/ProofTraceDto"},"description":"Failed proof traces with causal chains for violated constraints.\nEach trace explains WHY a constraint failed, at what depth, and suggests fixes."},"verdict":{"type":"string","description":"Overall verdict: \"safe\", \"unsafe\", \"partial\", or \"residuated\""},"violations":{"type":"array","items":{"$ref":"#/components/schemas/ViolationDto"},"description":"Specific constraint violations (if any)"}}},"FormalVerdictDto":{"type":"object","description":"FormalJudge semantic verification verdict.\nOnly present when an LLM is configured and semantic verification was performed.","required":["overall_verdict","confidence","layer_results","deterministic_facts","semantic_facts","total_llm_calls"],"properties":{"confidence":{"type":"number","format":"double","description":"Overall score (0.0 to 1.0)"},"deterministic_facts":{"type":"integer","description":"Number of deterministic facts checked (no LLM)","minimum":0},"layer_results":{"type":"array","items":{"$ref":"#/components/schemas/LayerResultSummaryDto"},"description":"Per-layer verification summaries"},"overall_verdict":{"type":"string","description":"Overall verdict: \"safe\", \"unsafe\", \"partial\", or \"residuated\""},"semantic_facts":{"type":"integer","description":"Number of semantic facts checked (with LLM)","minimum":0},"total_llm_calls":{"type":"integer","description":"Total LLM calls made","minimum":0}}},"ForwardChainRequest":{"type":"object","description":"Request for forward chaining.","properties":{"enable_provenance_tags":{"type":"boolean","description":"Enable provenance tag propagation alongside symbolic forward chaining.\nWhen true, each derived fact gets a confidence tag via the probabilistic semiring.\nThe symbolic engine decides WHICH facts are derivable; tags only decide WEIGHTS.\nDefault: false (standard symbolic-only forward chaining)"},"initial_facts":{"type":"array","items":{"$ref":"#/components/schemas/TermInputDto"},"description":"Initial facts (optional - uses existing facts if not provided)"},"max_facts":{"type":"integer","description":"Maximum facts to derive","default":100000,"minimum":0},"max_iterations":{"type":"integer","description":"Maximum iterations","default":1000,"minimum":0},"persist_derived":{"type":"boolean","description":"TRUE HOMOICONICITY: Persist derived facts to PostgreSQL and add to homoiconic_rules.\nWhen true, derived facts become permanent facts/rules that survive server restart\nand are available for backward chaining.\nDefault: false (derived facts are ephemeral, returned but not persisted)"}}},"ForwardChainResponse":{"type":"object","description":"Response for forward chaining.","required":["total_facts","derived_count","derived_facts","iterations","materialization_time_ms"],"properties":{"derived_count":{"type":"integer","description":"Number of newly derived facts","minimum":0},"derived_facts":{"type":"array","items":{"$ref":"#/components/schemas/PsiTermDto"},"description":"Derived facts (as terms)"},"iterations":{"type":"integer","description":"Number of iterations performed","minimum":0},"materialization_time_ms":{"type":"integer","description":"Materialization time in milliseconds","minimum":0},"persisted_count":{"type":"integer","description":"TRUE HOMOICONICITY: Number of derived facts persisted to PostgreSQL\n(only populated when persist_derived=true in request)","minimum":0},"provenance_tags":{"type":"array","items":{"$ref":"#/components/schemas/ProvenanceTagDto"},"description":"Provenance tags for derived facts (only populated when enable_provenance_tags=true).\nEach tag maps a derived fact (by index into derived_facts) to its confidence score."},"total_facts":{"type":"integer","description":"Total facts after materialization","minimum":0}}},"FunctionBodyDto":{"oneOf":[{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["Value"]},"value":{"$ref":"#/components/schemas/FunctionValueDto"}}},{"type":"object","required":["expr","type"],"properties":{"expr":{"$ref":"#/components/schemas/ExpressionDto"},"type":{"type":"string","enum":["Expression"]}}},{"type":"object","required":["function_name","arguments","type"],"properties":{"arguments":{"type":"array","items":{"$ref":"#/components/schemas/ExpressionDto"}},"function_name":{"type":"string"},"type":{"type":"string","enum":["FunctionCall"]}}}],"description":"Function body - what to compute"},"FunctionClauseDto":{"type":"object","description":"A single clause in a function definition","required":["parameters","body"],"properties":{"body":{"$ref":"#/components/schemas/FunctionBodyDto"},"guard":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/GuardDto"}]},"parameters":{"type":"array","items":{"$ref":"#/components/schemas/PatternDto"}}}},"FunctionValueDto":{"oneOf":[{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["Integer"]},"value":{"type":"integer","format":"int64"}}},{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["Real"]},"value":{"type":"number","format":"double"}}},{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["String"]},"value":{"type":"string"}}},{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["Boolean"]},"value":{"type":"boolean"}}},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["Uninstantiated"]}}}],"description":"Value type for literals"},"FuzzyConceptLevelDto":{"type":"object","description":"Summary of fuzzy concept enumeration at one alpha-cut level.","required":["alpha","concept_count","novel_at_this_level"],"properties":{"alpha":{"type":"number","format":"double","description":"Alpha threshold for this level"},"concept_count":{"type":"integer","description":"Number of concepts discovered at this threshold","minimum":0},"novel_at_this_level":{"type":"integer","description":"Number of concepts novel at this level (not found at higher alpha)","minimum":0}}},"FuzzyMergeRequest":{"type":"object","description":"Request for fuzzy merge operation","required":["term1_id","term2_id"],"properties":{"strategy":{"type":["string","null"],"description":"Merge strategy: \"max\", \"min\", \"probabilistic_sum\", \"product\""},"term1_id":{"type":"string","format":"uuid","description":"First term ID"},"term2_id":{"type":"string","format":"uuid","description":"Second term ID"}}},"FuzzyMergeResponse":{"type":"object","description":"Response from fuzzy merge","required":["merged_features","computation_time_ms"],"properties":{"computation_time_ms":{"type":"integer","format":"int64","description":"Computation time in milliseconds","minimum":0},"merged_features":{"type":"integer","description":"Number of features in merged result","minimum":0},"strategy":{"type":["string","null"],"description":"Strategy used"}}},"FuzzyProveRequest":{"type":"object","description":"Request for fuzzy inference.","properties":{"goal":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/TermInputDto","description":"The goal to prove.\nEither `goal` or `goal_id` must be provided, but not both."}]},"goal_id":{"type":["string","null"],"format":"uuid","description":"Load a previously saved goal by ID (TRUE HOMOICONICITY).\nEither `goal` or `goal_id` must be provided, but not both."},"max_solutions":{"type":"integer","description":"Maximum solutions","default":10,"minimum":0},"min_degree":{"type":"number","format":"double","description":"Minimum degree threshold","default":0.0},"open_world":{"type":"boolean","description":"Use open-world semantics (default: false = closed-world backward chaining).\n\nWhen true, missing evidence is treated as unknown (residuated) rather than\nfalse. Rules are evaluated by checking which body antecedents have matching\nfacts, producing partial solutions ranked by evidence ratio.\n\nThis follows LIFE's open-world principle: absence of evidence is not\nevidence of absence.","default":false},"save_goal":{"type":"boolean","description":"Persist the goal after creation for later reuse (TRUE HOMOICONICITY)."},"tnorm":{"type":"string","description":"T-norm strategy: \"min\", \"product\", or \"lukasiewicz\"","default":"min"}}},"FuzzyProveResponse":{"type":"object","description":"Response for fuzzy inference.","required":["solutions","query_time_ms"],"properties":{"goal_id":{"type":["string","null"],"format":"uuid","description":"TRUE HOMOICONICITY: Goal ID if the goal was saved (when save_goal=true)"},"query_time_ms":{"type":"integer","description":"Query time in milliseconds","minimum":0},"solutions":{"type":"array","items":{"$ref":"#/components/schemas/SolutionDto"},"description":"Solutions with fuzzy degrees"}}},"FuzzySearchTopKRequest":{"allOf":[{"$ref":"#/components/schemas/QueryTerm","description":"Query term"},{"type":"object","required":["k"],"properties":{"fail_on_unknown":{"type":"boolean","description":"Whether to fail when encountering unknown (Uninstantiated) values instead of residuating\nfalse = enable residuation (default)"},"k":{"type":"integer","description":"Number of results to return","minimum":0},"min_degree":{"type":["number","null"],"format":"double","description":"Optional minimum similarity degree"},"similarity_mode":{"type":"string","description":"String similarity strategy:\n- \"fast\": Exact → Normalized → Jaccard only (NO embeddings) - fastest\n- \"hybrid\": Exact → Normalized → Jaccard → Embeddings (default)\n- \"semantic\": Exact → Normalized → Embeddings (skip Jaccard) - most accurate for NL","example":"hybrid"}}}],"description":"Request for top-K similarity search"},"FuzzyShapeDto":{"oneOf":[{"type":"object","required":["a","b","c","kind"],"properties":{"a":{"type":"number","format":"double"},"b":{"type":"number","format":"double"},"c":{"type":"number","format":"double"},"kind":{"type":"string","enum":["Triangular"]}}},{"type":"object","required":["a","b","c","d","kind"],"properties":{"a":{"type":"number","format":"double"},"b":{"type":"number","format":"double"},"c":{"type":"number","format":"double"},"d":{"type":"number","format":"double"},"kind":{"type":"string","enum":["Trapezoidal"]}}},{"type":"object","required":["mean","std_dev","kind"],"properties":{"kind":{"type":"string","enum":["Gaussian"]},"mean":{"type":"number","format":"double"},"std_dev":{"type":"number","format":"double"}}},{"type":"object","required":["mean","std_dev","period","kind"],"properties":{"kind":{"type":"string","enum":["CyclicGaussian"]},"mean":{"type":"number","format":"double"},"period":{"type":"number","format":"double"},"std_dev":{"type":"number","format":"double"}}},{"type":"object","required":["midpoint","steepness","kind"],"properties":{"kind":{"type":"string","enum":["Sigmoid"]},"midpoint":{"type":"number","format":"double"},"steepness":{"type":"number","format":"double"}}},{"type":"object","required":["center","width","slope","kind"],"properties":{"center":{"type":"number","format":"double"},"kind":{"type":"string","enum":["Bell"]},"slope":{"type":"number","format":"double"},"width":{"type":"number","format":"double"}}},{"type":"object","required":["midpoint1","steepness1","midpoint2","steepness2","kind"],"properties":{"kind":{"type":"string","enum":["SigmoidDifference"]},"midpoint1":{"type":"number","format":"double"},"midpoint2":{"type":"number","format":"double"},"steepness1":{"type":"number","format":"double"},"steepness2":{"type":"number","format":"double"}}},{"type":"object","required":["mean1","std_dev1","mean2","std_dev2","kind"],"properties":{"kind":{"type":"string","enum":["GaussianProduct"]},"mean1":{"type":"number","format":"double"},"mean2":{"type":"number","format":"double"},"std_dev1":{"type":"number","format":"double"},"std_dev2":{"type":"number","format":"double"}}},{"type":"object","required":["midpoint1","steepness1","midpoint2","steepness2","kind"],"properties":{"kind":{"type":"string","enum":["SigmoidProduct"]},"midpoint1":{"type":"number","format":"double"},"midpoint2":{"type":"number","format":"double"},"steepness1":{"type":"number","format":"double"},"steepness2":{"type":"number","format":"double"}}},{"type":"object","required":["center","width","kind"],"properties":{"center":{"type":"number","format":"double"},"kind":{"type":"string","enum":["Cosine"]},"width":{"type":"number","format":"double"}}},{"type":"object","required":["center","width","kind"],"properties":{"center":{"type":"number","format":"double"},"kind":{"type":"string","enum":["Spike"]},"width":{"type":"number","format":"double"}}},{"type":"object","required":["center","gamma","kind"],"properties":{"center":{"type":"number","format":"double"},"gamma":{"type":"number","format":"double"},"kind":{"type":"string","enum":["Cauchy"]}}},{"type":"object","required":["a","b","kind"],"properties":{"a":{"type":"number","format":"double"},"b":{"type":"number","format":"double"},"kind":{"type":"string","enum":["SShape"]}}},{"type":"object","required":["a","b","kind"],"properties":{"a":{"type":"number","format":"double"},"b":{"type":"number","format":"double"},"kind":{"type":"string","enum":["ZShape"]}}},{"type":"object","required":["a","b","c","d","kind"],"properties":{"a":{"type":"number","format":"double"},"b":{"type":"number","format":"double"},"c":{"type":"number","format":"double"},"d":{"type":"number","format":"double"},"kind":{"type":"string","enum":["PiShape"]}}},{"type":"object","required":["points","kind"],"properties":{"kind":{"type":"string","enum":["PiecewiseLinear"]},"points":{"type":"array","items":{"type":"array","items":false,"prefixItems":[{"type":"number","format":"double"},{"type":"number","format":"double"}]}}}}],"description":"Fuzzy shape DTO"},"FuzzySubsumptionRequest":{"type":"object","description":"Request for fuzzy subsumption check","required":["general_term_id","specific_term_id"],"properties":{"general_term_id":{"type":"string","format":"uuid","description":"The general (more abstract) term ID"},"lenient":{"type":["boolean","null"],"description":"Enable lenient primitive matching (default: true).\nWhen true, string mismatches use semantic similarity instead of\nrequiring exact equality, and the similarity oracle is consulted."},"specific_term_id":{"type":"string","format":"uuid","description":"The specific (more concrete) term ID"},"threshold":{"type":["number","null"],"format":"double","description":"Optional minimum threshold for subsumption"}}},"FuzzySubsumptionResponse":{"type":"object","description":"Response from fuzzy subsumption","required":["degree","subsumes","computation_time_ms"],"properties":{"computation_time_ms":{"type":"integer","format":"int64","description":"Computation time in milliseconds","minimum":0},"degree":{"type":"number","format":"double","description":"Subsumption degree μ ∈ [0,1]"},"subsumes":{"type":"boolean","description":"Whether specific is subsumed by general (degree >= threshold)"}}},"FuzzyUnifyRequest":{"type":"object","description":"Request to fuzzy unify two terms","required":["term1_id","term2_id"],"properties":{"fail_on_unknown":{"type":"boolean","description":"Whether to fail when encountering unknown (Uninstantiated) values instead of residuating\nfalse = enable residuation (default)"},"similarity_mode":{"type":"string","description":"String similarity strategy:\n- \"fast\": Exact → Normalized → Jaccard only (NO embeddings) - fastest\n- \"hybrid\": Exact → Normalized → Jaccard → Embeddings (default)\n- \"semantic\": Exact → Normalized → Embeddings (skip Jaccard) - most accurate for NL","example":"hybrid"},"term1_id":{"type":"string","format":"uuid","description":"First term ID to unify"},"term2_id":{"type":"string","format":"uuid","description":"Second term ID to unify"},"threshold":{"type":"number","format":"double","description":"Minimum similarity threshold (0.0 to 1.0)"}}},"FuzzyUnifyResponse":{"type":"object","description":"Response from fuzzy unification","required":["term","degree","confidence_percent"],"properties":{"confidence_percent":{"type":"number","format":"double","description":"Percentage representation (0-100)"},"degree":{"type":"number","format":"double","description":"Unification degree μ ∈ [0,1]"},"term":{"$ref":"#/components/schemas/TermDto","description":"The unified term"}}},"GESResultDto":{"type":"object","required":["initial_score","final_score","improvement","edges_added","edges_removed","was_refined"],"properties":{"edges_added":{"type":"integer","description":"Edges added during forward phase","minimum":0},"edges_removed":{"type":"integer","description":"Edges removed during backward phase","minimum":0},"final_score":{"type":"number","format":"double","description":"Final BIC score after refinement"},"improvement":{"type":"number","format":"double","description":"Score improvement"},"initial_score":{"type":"number","format":"double","description":"Initial BIC score"},"was_refined":{"type":"boolean","description":"Was the graph refined?"}}},"GFlowNetSampleRequest":{"type":"object","description":"Request for standalone GFlowNet hypothesis sampling.","required":["target_sort"],"properties":{"max_body_size":{"type":["integer","null"],"description":"Maximum body size for sampled rules (default: 3).","minimum":0},"num_trajectories":{"type":["integer","null"],"description":"Number of sampling trajectories (default: 50).","minimum":0},"target_sort":{"type":"string","description":"Target sort name to sample hypotheses for."},"temperature":{"type":["number","null"],"format":"double","description":"Exploration temperature (default: 1.0, higher = more diverse)."}}},"GFlowNetSampleResponse":{"type":"object","description":"Response from GFlowNet hypothesis sampling.","required":["success","hypotheses","total_sampled","masked_count","joined_count","neural_guide_available","processing_time_ms"],"properties":{"error":{"type":["string","null"],"description":"Error message if sampling failed."},"hypotheses":{"type":"array","items":{"$ref":"#/components/schemas/SampledHypothesisDto"},"description":"Sampled hypotheses with body sorts as names."},"joined_count":{"type":"integer","description":"Number of hypotheses produced by rule joining.","minimum":0},"masked_count":{"type":"integer","description":"Number of hypotheses masked by constraints.","minimum":0},"neural_guide_available":{"type":"boolean","description":"Whether a neural guide was available."},"processing_time_ms":{"type":"integer","description":"Processing time in milliseconds.","minimum":0},"success":{"type":"boolean","description":"Whether sampling succeeded."},"total_sampled":{"type":"integer","description":"Total number of hypotheses sampled.","minimum":0}}},"GFlowNetTrainResponse":{"type":"object","description":"Response for the GFlowNet training endpoint.","required":["triggered","trajectories_consumed","loss"],"properties":{"error":{"type":["string","null"],"description":"Error message if training failed."},"loss":{"type":"number","format":"float","description":"Training loss after the cycle."},"trajectories_consumed":{"type":"integer","description":"Number of trajectories consumed from the buffer.","minimum":0},"triggered":{"type":"boolean","description":"Whether training was triggered."}}},"GeneralConstraintDto":{"type":"object","title":"GeneralConstraintDto","description":"General constraint: Arithmetic, Basic {constraint_type, value}, Conjunction {constraints}, or Disjunction {constraints}"},"GenerateDocumentRequest":{"type":"object","description":"Request body for `POST /api/v1/generate`.","required":["modality","root_term_id"],"properties":{"metadata":{"type":"object","description":"Additional metadata to guide generation (passed through to the backend).","additionalProperties":{"type":"string"},"propertyNames":{"type":"string"}},"modality":{"type":"string","description":"Target modality for the output artifact.\nCurrently only `\"text\"` is supported."},"root_term_id":{"type":"string","format":"uuid","description":"Root term ID describing the artifact to generate.\nThe pipeline derives a specification from this root via forward chaining."},"tenant_id":{"type":["string","null"],"format":"uuid","description":"Tenant ID (overridden by X-Tenant-Id header when present)."}}},"GenerateDocumentResponse":{"type":"object","description":"Response body for `POST /api/v1/generate`.","required":["success","diagnostics"],"properties":{"artifact":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ArtifactDto","description":"The generated artifact (if successful)."}]},"diagnostics":{"type":"array","items":{"$ref":"#/components/schemas/DiagnosticDto"},"description":"Diagnostic messages from each pipeline stage."},"success":{"type":"boolean","description":"Whether the pipeline completed successfully."},"verification":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/VerificationDto","description":"Verification result (if generation succeeded)."}]}}},"GenerateNegativesRequest":{"type":"object","description":"Request to generate enhanced negative examples.","required":["target_sorts"],"properties":{"enable_cross_sort_confusion":{"type":"boolean","description":"Whether to use cross-sort confusion strategy (default: true)."},"enable_feature_perturbation":{"type":"boolean","description":"Whether to use feature perturbation strategy (default: true)."},"enable_sort_incompatibility":{"type":"boolean","description":"Whether to use sort incompatibility strategy (default: true)."},"max_per_sort":{"type":["integer","null"],"description":"Maximum negatives per sort (default: 5).","minimum":0},"seed":{"type":["integer","null"],"format":"int64","description":"Random seed for reproducibility (default: 42).","minimum":0},"target_sorts":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Target sort IDs to generate negatives for."}}},"GenerateNegativesResponse":{"type":"object","description":"Response from enhanced negative generation.","required":["negatives","count"],"properties":{"count":{"type":"integer","description":"Total negatives generated.","minimum":0},"negatives":{"type":"array","items":{"$ref":"#/components/schemas/NegativeExampleDto"},"description":"Generated negative examples."}}},"GenerateOntologyRequest":{"type":"object","description":"Request body for ontology generation.","required":["prompt"],"properties":{"answers":{"type":["object","null"],"description":"Answers to clarification questions (2nd call).","additionalProperties":{"type":"string"},"propertyNames":{"type":"string"}},"prompt":{"type":"string","description":"The user's task description."},"session_id":{"type":["string","null"],"description":"Session ID for multi-turn clarification."},"tenant_id":{"type":["string","null"],"format":"uuid","description":"Tenant ID (overridden by AuthContext header)."}}},"GenerateOntologyResponse":{"oneOf":[{"type":"object","description":"LLM needs more information.","required":["questions","understood","session_id","status"],"properties":{"questions":{"type":"array","items":{"$ref":"#/components/schemas/OntologyClarificationQuestionDto"}},"session_id":{"type":"string"},"status":{"type":"string","enum":["needs_clarification"]},"understood":{"type":"object"}}},{"type":"object","description":"Generation complete.","required":["scenario","generation_time_ms","existing_sorts_count","status"],"properties":{"existing_sorts_count":{"type":"integer","minimum":0},"generation_time_ms":{"type":"integer","format":"int64","minimum":0},"scenario":{"type":"object"},"status":{"type":"string","enum":["complete"]}}}],"description":"Response for ontology generation -- either needs clarification or complete."},"GenerateSyntheticDataRequest":{"type":"object","description":"Request to generate synthetic training data.","properties":{"enable_enhanced_negatives":{"type":"boolean","description":"Whether to enable enhanced negative generation (default: true)."},"enable_format_diversity":{"type":"boolean","description":"Whether to include multi-format diversity (default: true)."},"enable_forward_chaining":{"type":"boolean","description":"Whether to amplify with forward chaining (default: true)."},"enable_statistical_sampling":{"type":"boolean","description":"Whether to enable statistical sampling from extraction distributions (default: true)."},"enable_verbalization":{"type":"boolean","description":"Whether to enable verbalization of generated terms (default: true)."},"generate_negatives":{"type":"boolean","description":"Whether to generate hard negative examples (default: true)."},"max_forward_chain_iterations":{"type":["integer","null"],"description":"Maximum forward chaining iterations (default: 50).","minimum":0},"max_negatives_per_sort":{"type":["integer","null"],"description":"Maximum enhanced negatives per sort (default: 5).","minimum":0},"max_solutions_per_goal":{"type":["integer","null"],"description":"Maximum solutions from backward chaining per goal (default: 10).","minimum":0},"max_terms_per_sort":{"type":["integer","null"],"description":"Maximum terms to generate per sort (default: 100).","minimum":0},"min_certainty":{"type":["number","null"],"format":"double","description":"Minimum certainty degree for generated terms (0.0-1.0, default: 0.5)."},"real_ratio":{"type":["number","null"],"format":"double","description":"Real/synthetic data mixing ratio (default: 0.62 real)."},"seed":{"type":["integer","null"],"format":"int64","description":"Random seed for reproducibility (default: 42).","minimum":0},"target_sorts":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Target sort IDs to generate data for. If empty, generates for all active sorts."},"verbalization_strategy":{"type":["string","null"],"description":"Verbalization strategy (default: \"SchemaGuided\").\nOptions: \"Template\", \"SchemaGuided\", \"SortEmbedding\", \"Narrative\"."}}},"GenerateSyntheticDataResponse":{"type":"object","description":"Response from synthetic data generation.","required":["examples","report","mixing_stats","synthetic_terms_count","training_pairs_count","enhanced_negatives_count","diversity_filtered_count"],"properties":{"calibration_report":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/CalibrationReportDto","description":"P4: Calibration report (if enabled)."}]},"dataset_statistics":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/DatasetStatisticsDto","description":"P3: Enhanced dataset statistics (if enabled)."}]},"diversity_filtered_count":{"type":"integer","description":"P2: Number of terms filtered by diversity checking.","minimum":0},"enhanced_dataset_jsonl":{"type":["string","null"],"description":"P3: Enhanced dataset JSONL export (if built)."},"enhanced_negatives":{"type":"array","items":{"$ref":"#/components/schemas/NegativeExampleDto"},"description":"Enhanced negative examples with provenance."},"enhanced_negatives_count":{"type":"integer","description":"Number of enhanced negative examples generated.","minimum":0},"examples":{"type":"array","items":{"$ref":"#/components/schemas/TrainingExampleDto"},"description":"Serialized training examples ready for JSONL export."},"mixing_stats":{"$ref":"#/components/schemas/DataMixingStatsDto","description":"Data mixing statistics."},"report":{"$ref":"#/components/schemas/GenerationReportDto","description":"Generation report with per-strategy statistics."},"round_trip_result":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/VerifyRoundTripResponse","description":"P2: Round-trip verification result (if enabled)."}]},"synthetic_terms_count":{"type":"integer","description":"Number of synthetic terms generated (before format expansion).","minimum":0},"training_pairs_count":{"type":"integer","description":"Number of training pairs created (all formats).","minimum":0},"verbalizations":{"type":"array","items":{"$ref":"#/components/schemas/VerbalizationResultDto"},"description":"Verbalized text for generated terms."}}},"GenerationPromptRequest":{"type":"object","description":"Request to generate a verbalization prompt for LLM-based text generation.","required":["term_id"],"properties":{"schema_sort_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Sort IDs to include in the schema context."},"term_id":{"type":"string","format":"uuid","description":"Term ID to generate a prompt for."}}},"GenerationPromptResponse":{"type":"object","description":"Response with a generation prompt.","required":["stable_prefix","dynamic_content","full_prompt"],"properties":{"dynamic_content":{"type":"string","description":"Dynamic content (specific entity to verbalize)."},"full_prompt":{"type":"string","description":"Full composed prompt."},"stable_prefix":{"type":"string","description":"Stable prefix (cacheable across batch calls)."}}},"GenerationReportDto":{"type":"object","description":"Generation statistics report.","required":["sorts_targeted","terms_generated","by_method","negatives_generated","validated_count","validation_failures","forward_chained_count"],"properties":{"by_method":{"type":"object","description":"Counts per generation method.","additionalProperties":{"type":"integer","minimum":0},"propertyNames":{"type":"string"}},"forward_chained_count":{"type":"integer","description":"Number of forward-chained derived facts.","minimum":0},"negatives_generated":{"type":"integer","description":"Number of negative examples generated.","minimum":0},"sorts_targeted":{"type":"integer","description":"Number of sorts targeted.","minimum":0},"terms_generated":{"type":"integer","description":"Total terms generated.","minimum":0},"validated_count":{"type":"integer","description":"Number of terms that passed validation.","minimum":0},"validation_failures":{"type":"integer","description":"Number of validation failures.","minimum":0}}},"GetAgentStateRequest":{"type":"object","description":"Request to get agent state.","required":["agent_id","tenant_id"],"properties":{"agent_id":{"type":"string","format":"uuid","description":"Agent ID"},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"}}},"GetAgentStateResponse":{"type":"object","description":"Response with agent state.","required":["agent"],"properties":{"agent":{"$ref":"#/components/schemas/AgentStateDto","description":"Agent state"}}},"GetBindingsRequest":{"type":"object","description":"Request to get current bindings","properties":{"term_ids":{"type":"array","items":{"type":"string"},"description":"Optional list of term IDs to get; if empty, return all"}}},"GetCausalModelResponse":{"type":"object","description":"Response with the causal model","required":["variables","edges","total_relations"],"properties":{"edges":{"type":"array","items":{"$ref":"#/components/schemas/CausalEdgeDto"},"description":"All causal edges"},"total_relations":{"type":"integer","description":"Total number of causal relationships","minimum":0},"variables":{"type":"array","items":{"type":"string"},"description":"All variables in the model"}}},"GetEpisodeStatsRequest":{"type":"object","description":"Request to get episode statistics.","required":["tenant_id","agent_id"],"properties":{"agent_id":{"type":"string","format":"uuid","description":"Agent ID"},"goal_id":{"type":["string","null"],"format":"uuid","description":"Optional goal filter"},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"}}},"GetEquivalenceClassesResponse":{"type":"object","description":"Response for equivalence classes query","required":["equivalence_classes","count"],"properties":{"count":{"type":"integer","description":"Total number of classes","minimum":0},"equivalence_classes":{"type":"array","items":{"$ref":"#/components/schemas/EquivalenceClass"},"description":"Groups of sorts that are equivalent under the fuzzy preorder"}}},"GetExtendedAgentStateResponse":{"type":"object","description":"Response with extended agent state.","required":["agent"],"properties":{"agent":{"$ref":"#/components/schemas/ExtendedAgentStateDto","description":"Extended agent state"}}},"GetFactsResponse":{"type":"object","description":"Response for getting facts.","required":["facts","count"],"properties":{"count":{"type":"integer","description":"Total count","minimum":0},"facts":{"type":"array","items":{"$ref":"#/components/schemas/PsiTermDto"},"description":"List of facts"}}},"GetHtnMethodsRequest":{"type":"object","description":"Request to get HTN methods.","required":["tenant_id","agent_id"],"properties":{"agent_id":{"type":"string","format":"uuid","description":"Agent ID"},"task_sort":{"type":["string","null"],"format":"uuid","description":"Optional filter by task sort"},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"}}},"GetHtnMethodsResponse":{"type":"object","description":"Response with HTN methods.","required":["methods","count"],"properties":{"count":{"type":"integer","description":"Total count","minimum":0},"methods":{"type":"array","items":{"$ref":"#/components/schemas/HtnMethodDto"},"description":"Methods"}}},"GetInboxRequest":{"type":"object","description":"Request to get an agent's inbox.","required":["tenant_id","agent_id"],"properties":{"agent_id":{"type":"string","format":"uuid","description":"Agent ID"},"include_read":{"type":"boolean","description":"Whether to include read messages"},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"}}},"GetInboxResponse":{"type":"object","description":"Response with inbox messages.","required":["messages","unread_count","total_count"],"properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/InboxMessageDto"},"description":"Messages (sorted by priority, then timestamp)"},"total_count":{"type":"integer","description":"Total count","minimum":0},"unread_count":{"type":"integer","description":"Unread count","minimum":0}}},"GetMembershipsRequest":{"type":"object","description":"Request to get community memberships for a term","required":["term_id","tenant_id"],"properties":{"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"},"term_id":{"type":"string","format":"uuid","description":"Term ID to query"}}},"GetMembershipsResponse":{"type":"object","description":"Response with community memberships","required":["term_id","memberships"],"properties":{"memberships":{"type":"array","items":{"$ref":"#/components/schemas/MembershipDto"},"description":"Communities the term belongs to (with membership info)"},"term_id":{"type":"string","format":"uuid","description":"Term ID"}}},"GetPreorderDegreeRequest":{"type":"object","description":"Request to get preorder degree between two sorts","required":["sort1_id","sort2_id"],"properties":{"sort1_id":{"type":"string","format":"uuid","description":"First sort ID"},"sort2_id":{"type":"string","format":"uuid","description":"Second sort ID"}}},"GetPreorderDegreeResponse":{"type":"object","description":"Response for preorder degree query\n\nPer Definition IV.5 (Milanese & Pasi 2024):\n≾̇ = ((≾̃ .− ∼) ⊍ ≤)⁺","required":["sort1_id","sort2_id","degree"],"properties":{"degree":{"type":"number","format":"double","description":"Preorder degree ∈ [0,1]\n- 1.0 = subsumption (sort1 ≤ sort2)\n- 0.0 < x < 1.0 = reachable via similarity-subsumption chain\n- 0.0 = not reachable"},"sort1_id":{"type":"string","format":"uuid","description":"Source sort ID"},"sort2_id":{"type":"string","format":"uuid","description":"Target sort ID"}}},"GetResiduationsRequest":{"type":"object","description":"Request to get residuations for a term","required":["session_id","term_id"],"properties":{"session_id":{"type":"string"},"term_id":{"type":"string"}}},"GetResiduationsResponse":{"type":"object","description":"Response with residuation details","required":["term_id","residuations"],"properties":{"residuations":{"type":"array","items":{"$ref":"#/components/schemas/ResiduationDetailDto"}},"term_id":{"type":"string"}}},"GetScenarioResponse":{"type":"object","description":"Response for GET /api/v1/scenarios/:id — retrieve a stored scenario.","required":["scenario_id","prompt","scenario","created_at","sorts_created","beliefs_created","rules_created","constraints_created","guard_constraints_created","temporal_constraints_created","webhook_actions_created"],"properties":{"agent_id":{"type":["string","null"],"description":"Agent TermId (if an agent was created)."},"beliefs_created":{"type":"integer","description":"Number of beliefs created during materialization.","minimum":0},"constraints_created":{"type":"integer","description":"Number of generic constraints created during materialization.","minimum":0},"created_at":{"type":"integer","format":"int64","description":"Unix timestamp of creation."},"guard_constraints_created":{"type":"integer","description":"Number of guard constraints created during materialization.","minimum":0},"prompt":{"type":"string","description":"Original user prompt."},"rules_created":{"type":"integer","description":"Number of rules created during materialization.","minimum":0},"scenario":{"description":"Full generated scenario (JSON object)."},"scenario_id":{"type":"string","description":"Unique scenario identifier."},"sorts_created":{"type":"integer","description":"Number of sorts created during materialization.","minimum":0},"temporal_constraints_created":{"type":"integer","description":"Number of temporal constraints created during materialization.","minimum":0},"webhook_actions_created":{"type":"integer","description":"Number of webhook actions created during materialization.","minimum":0}}},"GetSortSimilarityRequest":{"type":"object","description":"Request to get direct sort similarity","required":["sort1_id","sort2_id"],"properties":{"sort1_id":{"type":"string","format":"uuid","description":"First sort ID"},"sort2_id":{"type":"string","format":"uuid","description":"Second sort ID"}}},"GetSortSimilarityResponse":{"type":"object","description":"Response for direct sort similarity","required":["sort1_id","sort2_id","degree"],"properties":{"degree":{"type":"number","format":"double","description":"Direct similarity degree ∼(s₁, s₂) ∈ [0,1] (symmetric)"},"sort1_id":{"type":"string","format":"uuid","description":"First sort ID"},"sort2_id":{"type":"string","format":"uuid","description":"Second sort ID"}}},"GetStoreTermRequest":{"type":"object","description":"Request to get a term's details","required":["term_id"],"properties":{"term_id":{"type":"string"}}},"GetStoreTermResponse":{"type":"object","description":"Response with term details","required":["term_id","sort_id","features","is_variable"],"properties":{"bound_to":{"type":["string","null"]},"features":{"type":"object","additionalProperties":{"type":"object"},"propertyNames":{"type":"string"}},"is_variable":{"type":"boolean"},"sort_id":{"type":"string"},"term_id":{"type":"string"}}},"GlbLubComputationTrace":{"type":"object","description":"Response for GLB/LUB computation trace","required":["operation","sort1","sort2","cache_hit","synthetic_created","steps"],"properties":{"cache_hit":{"type":"boolean","description":"Whether the result was from cache"},"graph":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/VisualizationGraphDto","description":"Visualization graph with highlighted path"}]},"operation":{"$ref":"#/components/schemas/GlbLubOperation","description":"The requested operation"},"result":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/SortSummaryDto","description":"Result sort (if found)"}]},"sort1":{"$ref":"#/components/schemas/SortSummaryDto","description":"First input sort"},"sort2":{"$ref":"#/components/schemas/SortSummaryDto","description":"Second input sort"},"steps":{"type":"array","items":{"$ref":"#/components/schemas/GlbLubTraceStep"},"description":"Computation steps"},"synthetic_created":{"type":"boolean","description":"Whether a synthetic sort was created"}}},"GlbLubOperation":{"type":"string","description":"GLB/LUB operation type","enum":["glb","lub"]},"GlbLubTraceRequest":{"type":"object","description":"Request for GLB/LUB computation trace","required":["sort1_id","sort2_id","operation"],"properties":{"generate_dot":{"type":"boolean","description":"Whether to generate DOT output with trace highlighted"},"operation":{"$ref":"#/components/schemas/GlbLubOperation","description":"Operation type (GLB or LUB)"},"sort1_id":{"type":"string","format":"uuid","description":"First sort ID"},"sort2_id":{"type":"string","format":"uuid","description":"Second sort ID"}}},"GlbLubTraceStep":{"type":"object","description":"A step in the GLB/LUB computation trace","required":["step","description","involved_sorts","created_synthetic"],"properties":{"created_synthetic":{"type":"boolean","description":"Whether this step created a synthetic sort"},"description":{"type":"string","description":"Description of the step"},"involved_sorts":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Sort IDs involved in this step"},"step":{"type":"integer","description":"Step number","minimum":0}}},"GlobalAssignRequest":{"type":"object","description":"Request for global assignment","required":["session_id","variable_name","value"],"properties":{"session_id":{"type":"string"},"value":{"$ref":"#/components/schemas/AssignValueDto"},"variable_name":{"type":"string"}}},"GlobalAssignResponse":{"type":"object","description":"Response from global assignment","required":["variable_name"],"properties":{"previous_value":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/AssignValueDto"}]},"variable_name":{"type":"string"}}},"GlobalGetRequest":{"type":"object","description":"Request to get global variable","required":["session_id","variable_name"],"properties":{"session_id":{"type":"string"},"variable_name":{"type":"string"}}},"GlobalGetResponse":{"oneOf":[{"type":"object","required":["value","status"],"properties":{"status":{"type":"string","enum":["found"]},"value":{"$ref":"#/components/schemas/AssignValueDto"}}},{"type":"object","required":["variable_name","status"],"properties":{"status":{"type":"string","enum":["not_found"]},"variable_name":{"type":"string"}}}],"description":"Response from global get"},"GlobalIncrementRequest":{"type":"object","description":"Request for global increment","required":["session_id","variable_name"],"properties":{"session_id":{"type":"string"},"variable_name":{"type":"string"}}},"GlobalIncrementResponse":{"type":"object","description":"Response from global increment","required":["variable_name","new_value"],"properties":{"new_value":{"type":"integer","format":"int64"},"variable_name":{"type":"string"}}},"GoalDto":{"type":"object","description":"Goal DTO representation.\n\nSupports both `sort_name` (human-friendly) and `sort_id` (efficient).\nIf both are provided, `sort_id` takes precedence.","required":["sort"],"properties":{"features":{"type":"object","description":"Features as key-value pairs (raw JSON values)","additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"propertyNames":{"type":"string"}},"sort":{"type":"string","description":"Sort name for the goal (for human-friendly input)\nKept as \"sort\" for backward compatibility with existing clients"},"sort_id":{"type":["string","null"],"format":"uuid","description":"Sort ID (optional, takes precedence over sort name if provided)"}}},"GoalEvaluationResultDto":{"type":"object","description":"Evaluation result for a released goal","required":["goal","satisfied","confidence","explanation","evaluated_values"],"properties":{"confidence":{"type":"number","format":"double","description":"Confidence/degree of the result (0.0 to 1.0)"},"evaluated_values":{"type":"array","items":{"$ref":"#/components/schemas/EvaluatedValueDto"},"description":"The values that were used in the evaluation"},"explanation":{"type":"string","description":"Human-readable explanation of the evaluation"},"goal":{"$ref":"#/components/schemas/ResiduationGoalDto","description":"The goal that was evaluated"},"satisfied":{"type":"boolean","description":"Whether the condition was satisfied"}}},"GoalResiduationRequest":{"type":"object","description":"Request for goal-level residuation analysis.\n\nGiven a goal sort and the sorts already available as evidence,\nanalyse the rule base to find which antecedent sorts are still\nmissing (residuated) for rules that could prove the goal.","required":["goal_sort_name"],"properties":{"available_sorts":{"type":"array","items":{"type":"string"},"description":"Sort names already available as evidence"},"goal_sort_name":{"type":"string","description":"The head sort name of the goal to analyse"},"max_results":{"type":["integer","null"],"description":"Maximum number of residuated entries to return (sorted by info_gain).\nWhen `None` or `0`, all entries are returned.","minimum":0}}},"GoalResiduationResponse":{"type":"object","description":"Response from goal-level residuation analysis.","required":["entries","rules_analysed","computation_time_ms"],"properties":{"computation_time_ms":{"type":"integer","format":"int64","description":"Computation time in milliseconds","minimum":0},"entries":{"type":"array","items":{"$ref":"#/components/schemas/ResiduatedEntry"},"description":"Residuated entries, sorted by info_gain descending"},"rules_analysed":{"type":"integer","description":"Total number of rules analysed for the goal sort","minimum":0}}},"GoalStackEntryDto":{"type":"object","description":"A goal stack entry","required":["index","goal"],"properties":{"goal":{"$ref":"#/components/schemas/ExecutionGoalDto","description":"Goal at this stack position (discriminated by 'type' field)"},"index":{"type":"integer","minimum":0}}},"GoalStackResponse":{"type":"object","description":"Response with current goal stack state","required":["goals","size"],"properties":{"goals":{"type":"array","items":{"$ref":"#/components/schemas/GoalStackEntryDto"}},"size":{"type":"integer","minimum":0}}},"GoalSummaryDto":{"type":"object","description":"Summary information about a saved goal.\n\nTRUE HOMOICONICITY: Goals are first-class Ψ-terms that can be persisted,\nlisted, and reused across sessions.","required":["goal_id","clause_count"],"properties":{"clause_count":{"type":"integer","description":"Number of clauses in the goal","minimum":0},"created_at":{"type":["string","null"],"description":"When the goal was created (if available)"},"goal_id":{"type":"string","format":"uuid","description":"The goal's unique TermId"},"min_degree":{"type":["number","null"],"format":"double","description":"Minimum certainty threshold (if set)"}}},"GraphEdgeDto":{"type":"object","description":"An edge connecting two nodes","required":["id","source","target","edge_type"],"properties":{"color":{"type":["string","null"],"description":"Color of the edge (hex string)"},"curvature":{"type":["number","null"],"format":"double","description":"Curvature for curved edges (0.0 = straight, 1.0 = max curve)"},"edge_type":{"$ref":"#/components/schemas/EdgeTypeDto","description":"Type of edge"},"id":{"type":"string","description":"Unique identifier for this edge"},"label":{"type":["string","null"],"description":"Optional edge label"},"properties":{"type":"object","description":"Additional properties","additionalProperties":{"type":"string"},"propertyNames":{"type":"string"}},"source":{"type":"string","description":"Source node ID"},"target":{"type":"string","description":"Target node ID"},"weight":{"type":["number","null"],"format":"double","description":"Weight of the edge (for weighted graphs)"}}},"GraphMetadataDto":{"type":"object","description":"Metadata about a visualization graph","required":["node_count","edge_count","hyperedge_count","is_directed"],"properties":{"description":{"type":["string","null"],"description":"Description of what this graph represents"},"edge_count":{"type":"integer","description":"Total number of edges","minimum":0},"extra":{"type":"object","description":"Additional metadata","additionalProperties":{"type":"string"},"propertyNames":{"type":"string"}},"hyperedge_count":{"type":"integer","description":"Total number of hyperedges","minimum":0},"is_directed":{"type":"boolean","description":"Whether the graph is directed"},"node_count":{"type":"integer","description":"Total number of nodes","minimum":0},"title":{"type":["string","null"],"description":"Title of the graph"}}},"GraphNodeDto":{"type":"object","description":"A node in the visualization graph","required":["id","label","node_type"],"properties":{"color":{"type":["string","null"],"description":"Color of the node (hex string)"},"entity_id":{"type":["string","null"],"format":"uuid","description":"Optional entity ID this node represents"},"id":{"type":"string","description":"Unique identifier for this node"},"label":{"type":"string","description":"Display label for the node"},"level":{"type":["integer","null"],"format":"int32","description":"Level in hierarchy (for lattice visualization)","minimum":0},"node_type":{"$ref":"#/components/schemas/NodeTypeDto","description":"Type of node"},"properties":{"type":"object","description":"Additional properties","additionalProperties":{"type":"string"},"propertyNames":{"type":"string"}},"size":{"type":["number","null"],"format":"double","description":"Size of the node (for rendering)"}}},"GreatestSortsResponse":{"type":"object","description":"Response with greatest sorts (most general types)","required":["tenant_id","greatest_sorts"],"properties":{"greatest_sorts":{"type":"array","items":{"$ref":"#/components/schemas/SortInfoDto"}},"tenant_id":{"type":"string","format":"uuid"}}},"GroundTruthEntry":{"type":"object","description":"A single ground truth entry for E2E training.","required":["term_id","expected"],"properties":{"expected":{"type":"number","format":"float","description":"Expected label: 1.0 = should be derived, 0.0 = should not be derived."},"term_id":{"type":"string","format":"uuid","description":"The term ID of the fact (UUID)."}}},"GroundedSchemaResponse":{"type":"object","description":"Response from grounded NL schema generation.","required":["query_tools","write_tools","inference_tools","ontology_summary","system_prompt"],"properties":{"inference_tools":{"type":"integer","description":"Number of inference tools.","minimum":0},"ontology_summary":{"type":"string","description":"Human-readable ontology summary."},"query_tools":{"type":"integer","description":"Number of query tools generated.","minimum":0},"system_prompt":{"type":"string","description":"System prompt for LLM grounding."},"write_tools":{"type":"integer","description":"Number of write tools generated.","minimum":0}}},"GroundingStatsDto":{"type":"object","description":"Statistics for entity grounding (linking to external ontologies)","required":["entities_grounded","entities_ungrounded","entities_ambiguous","entities_skipped","grounding_time_ms"],"properties":{"entities_ambiguous":{"type":"integer","description":"Number of ambiguous groundings (multiple candidates found)","minimum":0},"entities_grounded":{"type":"integer","description":"Number of entities successfully grounded to ontology IDs","minimum":0},"entities_skipped":{"type":"integer","description":"Number of entities where grounding was skipped (disabled for sort)","minimum":0},"entities_ungrounded":{"type":"integer","description":"Number of entities that could not be grounded","minimum":0},"grounding_time_ms":{"type":"integer","format":"int64","description":"Grounding processing time in milliseconds","minimum":0}}},"GuardDto":{"oneOf":[{"type":"object","required":["var","value","type"],"properties":{"type":{"type":"string","enum":["GreaterThan"]},"value":{"$ref":"#/components/schemas/FunctionValueDto"},"var":{"type":"string"}}},{"type":"object","required":["var","value","type"],"properties":{"type":{"type":"string","enum":["LessThan"]},"value":{"$ref":"#/components/schemas/FunctionValueDto"},"var":{"type":"string"}}},{"type":"object","required":["var","value","type"],"properties":{"type":{"type":"string","enum":["Equal"]},"value":{"$ref":"#/components/schemas/FunctionValueDto"},"var":{"type":"string"}}},{"type":"object","required":["guards","type"],"properties":{"guards":{"type":"array","items":{"$ref":"#/components/schemas/GuardDto"}},"type":{"type":"string","enum":["And"]}}},{"type":"object","required":["guards","type"],"properties":{"guards":{"type":"array","items":{"$ref":"#/components/schemas/GuardDto"}},"type":{"type":"string","enum":["Or"]}}}],"description":"Guard condition for clause selection"},"HomoiconicSubstitutionDto":{"type":"object","description":"A substitution as a list of bindings.\n\nIn homoiconic style, substitutions map TermId → TermId.","required":["bindings"],"properties":{"bindings":{"type":"array","items":{"$ref":"#/components/schemas/BindingDto"},"description":"List of variable bindings"}}},"HorizonDto":{"type":"object","description":"Discovered horizon with score.","required":["horizon","score","confidence"],"properties":{"confidence":{"type":"number","format":"double"},"horizon":{"type":"integer","minimum":0},"score":{"type":"number","format":"double"}}},"HtnMethodDto":{"type":"object","description":"An HTN decomposition method.","required":["method_id","task_pattern","subtasks","success_count","failure_count"],"properties":{"failure_count":{"type":"integer","format":"int64","description":"Failure count"},"method_id":{"type":"string","format":"uuid","description":"Method ID"},"subtasks":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Subtask sequence"},"success_count":{"type":"integer","format":"int64","description":"Success count"},"task_pattern":{"type":"string","format":"uuid","description":"Task pattern"}}},"HyperedgeDto":{"type":"object","description":"A hyperedge connecting multiple nodes","required":["id","nodes","ordered","hyperedge_type"],"properties":{"color":{"type":["string","null"],"description":"Color of the hyperedge (hex string)"},"hyperedge_type":{"$ref":"#/components/schemas/HyperedgeTypeDto","description":"Type of hyperedge"},"id":{"type":"string","description":"Unique identifier for this hyperedge"},"label":{"type":["string","null"],"description":"Display label for the hyperedge"},"nodes":{"type":"array","items":{"type":"string"},"description":"IDs of all nodes connected by this hyperedge"},"ordered":{"type":"boolean","description":"Whether the nodes are ordered"},"properties":{"type":"object","description":"Additional properties","additionalProperties":{"type":"string"},"propertyNames":{"type":"string"}},"source_term_id":{"type":["string","null"],"format":"uuid","description":"Optional source term ID"}}},"HyperedgeTypeDto":{"oneOf":[{"type":"string","enum":["term_features"]},{"type":"string","enum":["constraint_variables"]},{"type":"string","enum":["unification_result"]},{"type":"object","required":["custom"],"properties":{"custom":{"type":"string"}}}],"description":"Hyperedge type"},"HypergraphRequest":{"type":"object","description":"Request for OSF term hypergraph visualization","required":["root_term_id"],"properties":{"generate_dot":{"type":"boolean","description":"Whether to generate DOT output"},"include_hyperedges":{"type":"boolean","description":"Whether to include hyperedges"},"include_relations":{"type":"boolean","description":"Whether to include relation Psi-terms as intermediate hypergraph nodes"},"max_depth":{"type":"integer","format":"int32","description":"Maximum depth to traverse","minimum":0},"root_term_id":{"type":"string","format":"uuid","description":"Root term ID to start from"},"s_threshold":{"type":"number","format":"double","description":"S-threshold for s-connected components (0.0 = no filtering)"}}},"HypergraphResponse":{"type":"object","description":"Response for hypergraph visualization","required":["graph","degree_distribution","stats"],"properties":{"components":{"type":"array","items":{"$ref":"#/components/schemas/ComponentDto"},"description":"S-connected components (if s_threshold > 0)"},"degree_distribution":{"$ref":"#/components/schemas/DegreeDistributionDto","description":"Degree distribution"},"graph":{"$ref":"#/components/schemas/VisualizationGraphDto","description":"The visualization graph"},"stats":{"$ref":"#/components/schemas/HypergraphStats","description":"Statistics"}}},"HypergraphStats":{"type":"object","description":"Statistics about the hypergraph","required":["total_terms","total_features","total_coreferences","component_count"],"properties":{"component_count":{"type":"integer","description":"Number of connected components","minimum":0},"total_coreferences":{"type":"integer","description":"Total number of coreferences","minimum":0},"total_features":{"type":"integer","description":"Total number of features","minimum":0},"total_terms":{"type":"integer","description":"Total number of terms","minimum":0}}},"ImageExtractedEntityDto":{"type":"object","description":"An entity extracted from a visual element in the image.","required":["local_id","sort","confidence","features","mentions"],"properties":{"confidence":{"type":"number","format":"double","description":"Confidence score (0.0-1.0)"},"features":{"type":"object","description":"Features extracted for this entity (key → value)","additionalProperties":{},"propertyNames":{"type":"string"}},"local_id":{"type":"string","description":"Local ID within the extraction (e.g., \"e1\", \"e2\")"},"mentions":{"type":"array","items":{"type":"string"},"description":"Text mentions/labels found in the image for this entity"},"sort":{"type":"string","description":"Sort name (type) assigned to this entity"}}},"ImageExtractedRelationDto":{"type":"object","description":"A relation extracted from visual connections in the image (arrows, lines, containment).","required":["source","relation","target","confidence"],"properties":{"confidence":{"type":"number","format":"double","description":"Confidence score (0.0-1.0)"},"relation":{"type":"string","description":"Relation type (e.g., \"connects_to\", \"part_of\", \"depends_on\")"},"source":{"type":"string","description":"Source entity local ID"},"target":{"type":"string","description":"Target entity local ID"}}},"ImageExtractionStatsDto":{"type":"object","description":"Statistics for the image extraction operation.","required":["entities_extracted","relations_extracted","sorts_created","sorts_reused","processing_time_ms"],"properties":{"entities_extracted":{"type":"integer","description":"Number of entities extracted","minimum":0},"processing_time_ms":{"type":"integer","description":"Processing time in milliseconds","minimum":0},"relations_extracted":{"type":"integer","description":"Number of relations extracted","minimum":0},"sorts_created":{"type":"integer","description":"Number of new sorts created","minimum":0},"sorts_reused":{"type":"integer","description":"Number of existing sorts reused","minimum":0}}},"ImageInputDto":{"type":"object","description":"Image input for multimodal TRIZ analysis","required":["data","mime"],"properties":{"data":{"type":"string","description":"Base64-encoded image data"},"description":{"type":"string","description":"Optional description of the image"},"mime":{"type":"string","description":"MIME type (e.g., \"image/png\", \"image/jpeg\")"}}},"ImageSuggestedSortDto":{"type":"object","description":"A new sort (type) suggested by the vision LLM based on visual patterns.","required":["name","features"],"properties":{"features":{"type":"array","items":{"type":"string"},"description":"Feature names suggested for this sort"},"name":{"type":"string","description":"Sort name (may have \"NEW_\" prefix stripped)"},"rationale":{"type":["string","null"],"description":"Rationale for why this sort was suggested"}}},"ImpasseDto":{"type":"object","description":"Impasse DTO.","required":["type","goal_id","description"],"properties":{"description":{"type":"string","description":"Description"},"goal_id":{"type":"string","format":"uuid","description":"Goal that caused impasse"},"subgoal_id":{"type":["string","null"],"format":"uuid","description":"Resolution subgoal (if generated)"},"type":{"type":"string","description":"Type of impasse (serializes as \"type\" in JSON)"}}},"ImplicationDto":{"type":"object","description":"A confirmed implication (feature name pairs).","required":["premise","conclusion"],"properties":{"conclusion":{"type":"array","items":{"type":"string"},"description":"Feature names forming the conclusion"},"premise":{"type":"array","items":{"type":"string"},"description":"Feature names forming the premise"}}},"ImpliesRequest":{"type":"object","description":"Request for implies (A -> B)","required":["session_id","antecedent","consequent"],"properties":{"antecedent":{"type":"object"},"consequent":{"type":"object"},"session_id":{"type":"string"}}},"ImpliesResponse":{"type":"object","description":"Response from implies","required":["result","antecedent_succeeded"],"properties":{"antecedent_succeeded":{"type":"boolean"},"consequent_succeeded":{"type":["boolean","null"]},"result":{"type":"boolean","description":"True if implication holds (antecedent fails OR consequent succeeds)"}}},"ImportModuleRequest":{"type":"object","description":"Request to import a module","required":["session_id","importer_module","imported_module"],"properties":{"alias":{"type":["string","null"],"description":"Optional alias for the import"},"imported_module":{"type":"string","description":"Module to import"},"importer_module":{"type":"string","description":"Module doing the import"},"session_id":{"type":"string"}}},"ImportModuleResponse":{"type":"object","description":"Response from import","required":["importer_module","imported_module","success"],"properties":{"imported_module":{"type":"string"},"importer_module":{"type":"string"},"success":{"type":"boolean"}}},"ImportOwlRequest":{"type":"object","description":"Request to import an OWL/RDF ontology into the sort hierarchy.","required":["rdf_xml"],"properties":{"rdf_xml":{"type":"string","description":"OWL/RDF XML content to import."}}},"ImportOwlResponse":{"type":"object","description":"Response from an OWL ontology import.","required":["sorts_created","relations_discovered","reified_sorts_created"],"properties":{"reified_sorts_created":{"type":"array","items":{"type":"string"},"description":"Names of reified sorts created (many-to-many with attributes)."},"relations_discovered":{"type":"integer","description":"Number of relations discovered from OWL object properties.","minimum":0},"sorts_created":{"type":"array","items":{"type":"string"},"description":"Names of sorts created from OWL classes."}}},"ImportSnapshotQuery":{"type":"object","description":"Query parameters for the import endpoint.","properties":{"name":{"type":["string","null"],"description":"Optional name override for the imported snapshot."}}},"InboxMessageDto":{"type":"object","description":"A message in the inbox.","required":["message_id","from_agent_id","content","priority","timestamp","read"],"properties":{"content":{"$ref":"#/components/schemas/JsonValue","description":"Message content (arbitrary JSON)"},"from_agent_id":{"type":"string","format":"uuid","description":"Sender agent ID"},"message_id":{"type":"string","format":"uuid","description":"Message ID"},"priority":{"type":"integer","format":"int64","description":"Priority"},"read":{"type":"boolean","description":"Whether the message has been read"},"timestamp":{"type":"integer","format":"int64","description":"Timestamp"}}},"IncompleteDocumentDto":{"type":"object","description":"Document that is incomplete and can be resumed","required":["document_id","resume_from_chunk"],"properties":{"document_id":{"type":"string","description":"Document identifier"},"resume_from_chunk":{"type":"integer","description":"Chunk index to resume from","minimum":0}}},"IndexSortsResponse":{"type":"object","required":["indexed_count","elapsed_ms"],"properties":{"elapsed_ms":{"type":"integer","format":"int64","minimum":0},"indexed_count":{"type":"integer","minimum":0}}},"IngestDocumentBatchRequest":{"type":"object","description":"Request to ingest multiple documents\n\nTenant ID is provided via the `X-Tenant-Id` header.","required":["documents","owner_id"],"properties":{"documents":{"type":"array","items":{"$ref":"#/components/schemas/DocumentBatchItem"},"description":"List of documents to ingest"},"ingestion_config":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/IngestionConfigDto","description":"Markdown ingestion configuration (passed through)"}]},"ocr_config":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/OcrConfigDto","description":"OCR/parsing configuration (applies to all documents)"}]},"owner_id":{"type":"string","format":"uuid","description":"Owner ID (user who owns the ingested data)"}}},"IngestDocumentBatchResponse":{"type":"object","description":"Response from batch document ingestion","required":["success","results","total_time_ms","successful_count","failed_count"],"properties":{"failed_count":{"type":"integer","description":"Number of failed documents","minimum":0},"results":{"type":"array","items":{"$ref":"#/components/schemas/DocumentBatchResultDto"},"description":"Results for each document"},"session_id":{"type":["string","null"],"format":"uuid","description":"Session ID for tracking and resumption (if session tracking is enabled)\nUse this ID with /api/v1/ingest/sessions/{id} endpoints to check status or resume"},"success":{"type":"boolean","description":"Overall success (all documents succeeded)"},"successful_count":{"type":"integer","description":"Number of successful documents","minimum":0},"total_time_ms":{"type":"integer","description":"Total processing time in milliseconds","minimum":0}}},"IngestDocumentRequest":{"type":"object","description":"Request to ingest a document (PDF, DOCX, etc.)\n\nTenant ID is provided via the `X-Tenant-Id` header.","required":["document","owner_id"],"properties":{"document":{"$ref":"#/components/schemas/DocumentSource","description":"Document source (base64 or URL)"},"document_type":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/DocumentType","description":"Document type hint (auto-detected if not provided)"}]},"ingestion_config":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/IngestionConfigDto","description":"Markdown ingestion configuration (passed through to markdown pipeline)"}]},"ocr_config":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/OcrConfigDto","description":"OCR/parsing configuration"}]},"owner_id":{"type":"string","format":"uuid","description":"Owner ID (user who owns the ingested data)"}}},"IngestDocumentResponse":{"type":"object","description":"Response from document ingestion","required":["success","parse_stats","metadata","ingestion_stats"],"properties":{"error":{"type":["string","null"],"description":"Error message if parsing failed"},"ingestion_stats":{"$ref":"#/components/schemas/IngestionStatsDto","description":"Markdown ingestion statistics (from the markdown pipeline)"},"metadata":{"$ref":"#/components/schemas/ParsedDocumentMetadataDto","description":"Document metadata"},"parse_stats":{"$ref":"#/components/schemas/DocumentParseStatsDto","description":"Document parsing statistics"},"pending_review":{"type":"array","items":{"$ref":"#/components/schemas/PendingReviewDto"},"description":"Entities that need human review"},"session_id":{"type":["string","null"],"format":"uuid","description":"Session ID for tracking and resumption (if session tracking is enabled)\nUse this ID with /api/v1/ingest/sessions/{id} endpoints to check status or resume"},"success":{"type":"boolean","description":"Whether the entire operation was successful"}}},"IngestFromSourceRequest":{"type":"object","description":"Request to ingest data from a registered source.","required":["owner_id"],"properties":{"batch_size":{"type":"integer","description":"Batch size for fetching from source (default: 1000)","minimum":0},"max_records_per_type":{"type":["integer","null"],"description":"Max records per type (None = all)","minimum":0},"owner_id":{"type":"string","format":"uuid","description":"Owner ID (user who owns the ingested data)"},"records_per_document":{"type":"integer","description":"Records per rendered document (controls LLM chunk size, default: 20)","minimum":0},"type_filter":{"type":["array","null"],"items":{"type":"string"},"description":"Which types/tables to ingest (None = all)"}}},"IngestFromSourceResponse":{"type":"object","description":"Response from structured data ingestion.","required":["success","source_id","source_type","stats"],"properties":{"errors":{"type":"array","items":{"type":"string"},"description":"Errors encountered during ingestion"},"source_id":{"type":"string","description":"Source identifier"},"source_type":{"type":"string","description":"Source type"},"stats":{"$ref":"#/components/schemas/StructuredIngestionStatsDto","description":"Ingestion statistics"},"success":{"type":"boolean","description":"Whether ingestion was successful"}}},"IngestMarkdownBatchRequest":{"type":"object","description":"Request to ingest multiple markdown documents\n\nTenant ID is provided via the `X-Tenant-Id` header.","required":["documents","owner_id"],"properties":{"config":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/IngestionConfigDto","description":"Optional configuration overrides"}]},"documents":{"type":"array","items":{"$ref":"#/components/schemas/MarkdownDocumentDto"},"description":"List of documents to ingest"},"owner_id":{"type":"string","format":"uuid","description":"Owner ID (user who owns the ingested data)"}}},"IngestMarkdownRequest":{"type":"object","description":"Request to ingest markdown content\n\nTenant ID is provided via the `X-Tenant-Id` header.","required":["content","owner_id"],"properties":{"config":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/IngestionConfigDto","description":"Optional configuration overrides"}]},"content":{"type":"string","description":"The markdown content to ingest"},"owner_id":{"type":"string","format":"uuid","description":"Owner ID (user who owns the ingested data)"}}},"IngestRdfRequest":{"type":"object","description":"Request to ingest RDF/OWL data","required":["content","format"],"properties":{"compute_embeddings":{"type":"boolean","description":"Whether to compute and store text embeddings for each ingested term.\n\nDefault `true` because downstream extraction relies on embeddings.\nSet to `false` only for opt-in fast structural-only ingest."},"content":{"type":"string","description":"RDF content in Turtle, N-Triples, or RDF/XML format"},"format":{"$ref":"#/components/schemas/RdfFormatDto","description":"Format of the RDF content"},"parse_ontology":{"type":"boolean","description":"Whether to also parse OWL ontology from the content"},"parse_shacl":{"type":"boolean","description":"Whether to also parse SHACL shapes from the content"}}},"IngestRdfResponse":{"type":"object","description":"Response from RDF ingestion (sync mode, HTTP 201).","required":["sorts_created","terms_created","shapes_parsed","term_ids","sort_names"],"properties":{"shapes_parsed":{"type":"integer","description":"Number of SHACL shapes parsed","minimum":0},"sort_names":{"type":"array","items":{"type":"string"},"description":"Names of created sorts"},"sorts_created":{"type":"integer","description":"Number of sorts created from OWL ontology","minimum":0},"term_ids":{"type":"array","items":{"type":"string"},"description":"IDs of created terms"},"terms_created":{"type":"integer","description":"Number of terms created from RDF data","minimum":0}}},"IngestStepRequest":{"type":"object","description":"Request to ingest a single step into a live oversight session.","required":["step"],"properties":{"step":{"$ref":"#/components/schemas/TrajectoryStepDto","description":"The trajectory step to ingest"}}},"IngestionConfigDto":{"type":"object","description":"Configuration for ingestion","properties":{"auto_create_sorts":{"type":"boolean","description":"Whether to automatically create new sorts for unrecognized entity types"},"batch_size":{"type":"integer","description":"Batch size for parallel processing","minimum":0},"deduplication_threshold":{"type":"number","format":"double","description":"Confidence threshold for deduplication (0.0 - 1.0)"},"document_id":{"type":["string","null"],"description":"Optional document ID for tracking sort provenance\nUsed in SortOrigin::LlmExtracted to track which document triggered sort creation"},"domain_instructions":{"type":"array","items":{"type":"string"},"description":"Domain-specific instructions for LLM extraction.\nThese are injected into the extraction prompt to guide the LLM toward\ndomain-relevant concepts. Example:\n- \"This content is from a training about sexual education.\"\n- \"Extract concepts specifically relevant to this domain.\""},"enable_description_consolidation":{"type":"boolean","description":"Enable cross-chunk description consolidation.\nMerges multiple descriptions of the same entity into one concise description.\nDefault: true"},"enable_entity_filtering":{"type":"boolean","description":"Enable post-extraction entity filtering.\nRemoves structurally invalid entities (pure punctuation, repeated chars, placeholders).\nDefault: true"},"enable_evidence_enrichment":{"type":"boolean","description":"Enable LLM-based evidence enrichment with statistical features.\nAfter evidence terms are derived, makes one LLM call to extract\nstatistical measures (p-value, HR, CI, sample size, study design)\nand attach them as features on evidence terms.\nDefault: false"},"enable_focused_extraction":{"type":"boolean","description":"Enable focused extraction prompts.\nWhen schema discovery found types, uses a simplified prompt asking only\nfor entities and relations (no sorts/axioms/equivalences).\nDefault: true"},"enable_llm_coreference":{"type":"boolean","description":"Enable LLM-based coreference resolution for hard cases.\nWhen true, after structural deduplication the pipeline runs parallel\nper-pair LLM calls to resolve ambiguous coreferences (e.g.,\n\"Stanley Reed\" vs \"Justice Reed\"). Adds LLM calls proportional to the\nnumber of candidate pairs — violates the 0-LLM-token guarantee for the\nLocalNer strategy, so disabled by default. Opt in to improve entity\ndeduplication quality at the cost of extra LLM calls.\nDefault: false"},"enable_schema_discovery":{"type":"boolean","description":"Enable schema discovery before extraction.\nSamples the document to discover entity/relation types before per-chunk extraction.\nAdds one extra LLM call but improves extraction precision.\nDefault: true"},"enable_zero_degree_filtering":{"type":"boolean","description":"Enable zero-degree entity removal.\nRemoves entities not referenced by any relation (only when entity filtering is enabled).\nDefault: false"},"evidence_derivation_config":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/EvidenceDerivationConfigDto","description":"Configuration for deriving evidence terms from relational features.\nWhen set, entities with Reference features (from NER relations) automatically\nget linked evidence terms created, enabling OSFKB evidence assessment."}]},"extract_relations":{"type":"boolean","description":"Whether to extract relations between entities"},"extraction_strategy":{"$ref":"#/components/schemas/ExtractionStrategyDto","description":"Extraction strategy -- an internally tagged object with a `\"type\"` discriminator.\n\nVariants:\n- `{\"type\": \"llm\"}` -- LLM for all extraction (default, most capable)\n- `{\"type\": \"local_ner\"}` -- local NER model like GLiNER2 (fast, no API costs)\n- `{\"type\": \"hybrid\", \"ner_confidence_threshold\": 0.8}` -- NER first, LLM fallback\n- `{\"type\": \"schema_guided\", ...}` -- NER + pattern-based, LLM only when needed\n- `{\"type\": \"adaptive\", \"fallback\": {...}}` -- auto-select based on learned patterns"},"force_extraction_strategy":{"type":"boolean","description":"When true, skip the auto-upgrade from Llm→LocalNer even if NER is available.\nUsed for A/B comparison tests. Default: false."},"max_schema_tokens":{"type":"integer","description":"Maximum tokens for schema context passed to LLM","minimum":0},"ner_confidence_threshold":{"type":"number","format":"float","description":"NER confidence threshold (only used when extraction_strategy is \"local_ner\" or \"hybrid\")\nEntities below this threshold will be discarded (local_ner) or sent to LLM (hybrid)\nDefault: 0.5"},"ner_entity_labels":{"type":"array","items":{"type":"string"},"description":"Entity labels for NER extraction (optional, derives from schema if empty)\nExample: [\"Person\", \"Organization\", \"Location\", \"Drug\", \"Disease\"]"},"ner_relation_confidence_threshold":{"type":"number","format":"float","description":"NER relation confidence threshold (0.0 - 1.0)\nRelations below this threshold will be discarded\nDefault: 0.5"},"ner_relation_labels":{"type":"array","items":{"type":"string"},"description":"Relation labels for NER relation extraction (optional)\nUsed when extraction_strategy is \"local_ner\" with extract_relations=true\nExample: [\"works_at\", \"located_in\", \"founded\", \"ceo_of\"]\nIf empty, default relations are used: works_at, located_in, part_of, etc."},"reject_anonymized_references":{"type":"boolean","description":"Reject anonymized reference patterns from case studies.\nFilters patterns like \"Monsieur X\", \"société A\", \"pays B\", \"Company A\".\nOnly active when entity filtering is enabled.\nDefault: true"},"skip_fingerprint":{"type":"boolean","description":"Skip fingerprint check (force re-ingestion)\nWhen true, the document will be re-ingested even if it was previously\ningested with the same content. Useful for re-extracting with different\nsettings or after schema changes."},"skip_relation_completion":{"type":"boolean","description":"Skip the post-extraction LLM relation completion step.\nWhen true, skips the O(sort_pairs) LLM calls that find additional relations\nbetween entities after per-chunk extraction. Useful when the LLM API is slow\nor when relations from per-chunk extraction are sufficient.\nDefault: false"}}},"IngestionSessionResponse":{"type":"object","description":"Response from starting an ingestion session","required":["session_id","status","total_documents","processed_documents","created_at","updated_at"],"properties":{"created_at":{"type":"string","format":"date-time","description":"When session was created"},"processed_documents":{"type":"integer","description":"Documents that have been processed","minimum":0},"session_id":{"type":"string","format":"uuid","description":"Unique session identifier"},"status":{"$ref":"#/components/schemas/IngestionSessionStatusDto","description":"Current status of the session"},"total_documents":{"type":"integer","description":"Total documents in session","minimum":0},"updated_at":{"type":"string","format":"date-time","description":"When session was last updated"}}},"IngestionSessionStatusDto":{"type":"string","description":"Session status enum","enum":["active","paused","complete","failed"]},"IngestionStatsDto":{"type":"object","description":"Ingestion statistics","required":["chunks_processed","chunks_failed","entities_extracted","relations_extracted","relations_integrated","sorts_created","sorts_reused","entities_created","entities_merged","entities_pending_review","references_resolved","references_unresolved","processing_time_ms","term_ids","sort_names"],"properties":{"alignment_stats":{"$ref":"#/components/schemas/AlignmentStatsDto","description":"Source text alignment statistics (entity-to-source mapping quality)"},"chunks_failed":{"type":"integer","description":"Number of chunks that failed extraction","minimum":0},"chunks_processed":{"type":"integer","description":"Number of text chunks processed","minimum":0},"community_stats":{"$ref":"#/components/schemas/CommunityStatsDto","description":"Community detection statistics (GraphRAG-style clustering)"},"entities_created":{"type":"integer","description":"Number of new entities created","minimum":0},"entities_extracted":{"type":"integer","description":"Number of entities extracted from text","minimum":0},"entities_filtered_low_quality":{"type":"integer","description":"Number of entities filtered out due to low-quality names","minimum":0},"entities_merged":{"type":"integer","description":"Number of entities merged (deduplicated)","minimum":0},"entities_pending_review":{"type":"integer","description":"Number of entities pending human review","minimum":0},"entity_merge_audit":{"type":"array","items":{"$ref":"#/components/schemas/EntityMergeAuditDto"},"description":"Audit trail for substring-based entity merges (surface-form coreference).\nE.g., \"Brown v. Board\" merged into \"Brown v. Board of Education of Topeka\"."},"estimated_cost_usd":{"type":["number","null"],"format":"double","description":"Estimated USD cost of LLM API calls (if model pricing is available)"},"failed_chunks":{"type":"array","items":{"$ref":"#/components/schemas/ChunkFailureDto"},"description":"Details of failed chunks (first 5)"},"grounding_stats":{"$ref":"#/components/schemas/GroundingStatsDto","description":"Entity grounding statistics (linking to external ontologies)"},"model":{"type":["string","null"],"description":"LLM model used for extraction (e.g., \"claude-3-5-haiku-20241022\")"},"pipeline_quality":{"$ref":"#/components/schemas/PipelineQualityStatsDto","description":"Pipeline quality statistics (inference rules, validation, feedback loop)"},"processing_time_ms":{"type":"integer","description":"Processing time in milliseconds","minimum":0},"references_resolved":{"type":"integer","description":"Number of references resolved","minimum":0},"references_unresolved":{"type":"integer","description":"Number of unresolved references (residuated - waiting for more information)","minimum":0},"relations_extracted":{"type":"integer","description":"Number of relations extracted from text","minimum":0},"relations_integrated":{"type":"integer","description":"Number of relations integrated as features on entities","minimum":0},"relations_orphaned":{"type":"integer","description":"Number of suspended relations that remained unresolved (orphaned)","minimum":0},"relations_resumed":{"type":"integer","description":"Number of suspended relations successfully resumed when endpoints became available","minimum":0},"relations_suspended":{"type":"integer","description":"Number of relations suspended (endpoints not yet available)","minimum":0},"sort_names":{"type":"array","items":{"type":"string"},"description":"Names of created/reused sorts"},"sorts_created":{"type":"integer","description":"Number of new sorts created","minimum":0},"sorts_reused":{"type":"integer","description":"Number of existing sorts reused","minimum":0},"term_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"IDs of created/updated terms"},"token_usage":{"$ref":"#/components/schemas/TokenUsageDto","description":"Token usage from LLM API calls during this ingestion"}}},"IntegratedCycleOutcomeDto":{"type":"object","description":"Outcome of an integrated cognitive cycle.","required":["perceptions_processed","sensor_percepts_processed","desires_considered","intentions_committed","goals_achieved","goals_failed","actions_executed","impasses_handled","subgoals_generated","episodes_recorded","utilities_updated","prediction_errors","drive_goals_generated","sort_suggestions","similarity_pairs_learned","success_rate"],"properties":{"actions_executed":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Actions executed"},"cognitive_mode":{"type":["string","null"],"description":"Cognitive mode selected by System M meta-control (when enabled).\nOne of: \"Explore\", \"Exploit\", \"Observe\", \"Consolidate\", or null if meta-control disabled."},"desires_considered":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Desires considered"},"drive_goals_generated":{"type":"integer","format":"int32","description":"Number of drive-based goals generated (Gap 15)","minimum":0},"episodes_recorded":{"type":"integer","description":"Episodes recorded","minimum":0},"focus":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/AttentionTargetDto","description":"What the agent focused on"}]},"goals_achieved":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Goals achieved"},"goals_failed":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Goals failed"},"impasses_handled":{"type":"array","items":{"$ref":"#/components/schemas/ImpasseDto"},"description":"Impasses encountered"},"intentions_committed":{"type":"array","items":{"$ref":"#/components/schemas/IntentionDto"},"description":"Intentions committed (with plans)"},"perceptions_processed":{"type":"integer","description":"Number of KB changes perceived","minimum":0},"prediction_errors":{"type":"array","items":{"$ref":"#/components/schemas/PredictionErrorDto"},"description":"Prediction errors observed"},"rl_policy_active":{"type":"boolean","description":"Whether the RL policy influenced this cycle's decisions.\nTrue when enable_rl_policy is set and Q-values were found in the knowledge base."},"rl_transitions_processed":{"type":"integer","description":"Number of Q-value updates performed from rl_transition terms.","minimum":0},"sensor_percepts_processed":{"type":"integer","description":"Number of sensor percepts processed from external sensor ports","minimum":0},"similarity_pairs_learned":{"type":"integer","format":"int32","description":"Number of sort similarity pairs learned during maintenance (Gap 5)","minimum":0},"sort_suggestions":{"type":"array","items":{"$ref":"#/components/schemas/SortSuggestionDto"},"description":"Sort suggestions from autonomous sort learning"},"subgoals_generated":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Subgoals generated"},"success_rate":{"type":"number","format":"double","description":"Success rate"},"utilities_updated":{"type":"integer","description":"Rule utilities updated","minimum":0}}},"IntegratedEngineConfigDto":{"type":"object","description":"Configuration for the integrated cognitive engine.","properties":{"enable_agent_messaging":{"type":"boolean","description":"Enable inter-agent messaging","default":true},"enable_episodic_memory":{"type":"boolean","description":"Enable episodic memory recording","default":true},"enable_htn_decomposition":{"type":"boolean","description":"Enable HTN goal decomposition","default":true},"enable_meta_cognition":{"type":"boolean","description":"Enable meta-cognitive rule learning","default":true},"enable_meta_control":{"type":"boolean","description":"Enable meta-control: System M dynamically selects cognitive modes\n(Explore/Exploit/Observe/Consolidate) based on meta-signals.","default":false},"enable_plan_library":{"type":"boolean","description":"Enable plan library lookup","default":true},"enable_rl_policy":{"type":"boolean","description":"Enable RL policy: agent uses Q-values from rl_transition Psi-terms for action selection.\nWhen true, the agent reads trained Q-values from the shared TermStore (populated by\nRL training) to guide cognitive decisions. Requires prior RL training on the same tenant.","default":false},"enable_simulation":{"type":"boolean","description":"Enable mental simulation before execution","default":true},"maintenance_interval":{"type":"integer","description":"Interval (in cycles) for meta-cognitive maintenance (0 = disabled)","default":10,"minimum":0},"max_goals_per_cycle":{"type":"integer","description":"Maximum goals to pursue per cycle","default":3,"minimum":0},"max_impasse_depth":{"type":"integer","description":"Maximum subgoal depth for impasse handling","default":5,"minimum":0},"min_plan_success_rate":{"type":"number","format":"double","description":"Minimum plan success rate to reuse","default":0.5},"simulation_confidence_threshold":{"type":"number","format":"double","description":"Minimum confidence for plan simulation","default":0.6},"surprise_threshold":{"type":"number","format":"double","description":"Surprise threshold for triggering learning","default":0.5}}},"IntegrationGroupDto":{"type":"object","description":"A group of entities that can be integrated","required":["match_key","entities","group_similarity"],"properties":{"entities":{"type":"array","items":{"$ref":"#/components/schemas/RowMatchDto"},"description":"Entities in this group"},"group_similarity":{"type":"number","format":"double","description":"Overall similarity within the group"},"match_key":{"type":"object","description":"Matching feature values (the \"join key\" values)","additionalProperties":{},"propertyNames":{"type":"string"}},"merged_entity_id":{"type":["string","null"],"format":"uuid","description":"ID of newly created merged entity (if create_merged was true)"},"merged_features":{"type":["object","null"],"description":"Merged features (if create_merged was true)","additionalProperties":{},"propertyNames":{"type":"string"}}}},"IntegrityResponse":{"type":"object","required":["verified","entries_checked"],"properties":{"entries_checked":{"type":"integer","minimum":0},"first_broken_at":{"type":["string","null"]},"verified":{"type":"boolean"}}},"IntentionDto":{"type":"object","description":"BDI Intention DTO.","required":["id","goal_id","plan","current_step","commitment_strength"],"properties":{"commitment_strength":{"type":"number","format":"double","description":"Commitment strength"},"current_step":{"type":"integer","description":"Current step in plan","minimum":0},"goal_id":{"type":"string","format":"uuid","description":"Goal being pursued"},"goal_sort":{"type":["string","null"],"description":"Sort name of the goal being pursued"},"id":{"type":"string","format":"uuid","description":"Intention ID"},"plan":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Plan (sequence of action term IDs)"},"status":{"type":"string","description":"Intention status (active, completed, dropped)","default":"active"}}},"InterventionObservationRequest":{"type":"object","required":["variable","value","changed_variables","unchanged_variables"],"properties":{"changed_variables":{"type":"array","items":{"type":"string"},"description":"Variables that changed after intervention"},"unchanged_variables":{"type":"array","items":{"type":"string"},"description":"Variables that did not change"},"value":{"type":"string","description":"Value the variable was set to"},"variable":{"type":"string","description":"Variable that was intervened on"}}},"InterventionObservationResponse":{"type":"object","required":["success","resolved_edges","remaining_uncertain_count","message"],"properties":{"message":{"type":"string","description":"Message"},"remaining_uncertain_count":{"type":"integer","description":"Remaining uncertain edges","minimum":0},"resolved_edges":{"type":"array","items":{"type":"array","items":false,"prefixItems":[{"type":"string"},{"type":"string"}]},"description":"Edges that were resolved by this intervention"},"success":{"type":"boolean","description":"Success flag"}}},"InterventionRecommendationDto":{"type":"object","required":["variable","expected_information_gain","edges_resolved_count","reason"],"properties":{"edges_resolved_count":{"type":"integer","description":"Number of edges this would resolve","minimum":0},"expected_information_gain":{"type":"number","format":"double","description":"Expected information gain"},"reason":{"type":"string","description":"Reason for recommendation"},"variable":{"type":"string","description":"Variable to intervene on"}}},"InterventionRequest":{"type":"object","description":"Request to apply a do-calculus intervention","required":["variable","value","query_variable"],"properties":{"query_variable":{"type":"string","description":"Query to evaluate after intervention"},"value":{"description":"The value to set the variable to"},"variable":{"type":"string","description":"The variable to intervene on"}}},"InterventionResponse":{"type":"object","description":"Response for intervention","required":["success","intervened_variable","intervention_value","disabled_rules_count","explanation"],"properties":{"disabled_rules_count":{"type":"integer","description":"Rules that were disabled by the intervention","minimum":0},"explanation":{"type":"string","description":"Explanation of the intervention effect"},"intervened_variable":{"type":"string","description":"The intervened variable"},"intervention_value":{"description":"The intervention value"},"query_result":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/QueryResultDto","description":"The query result after intervention"}]},"success":{"type":"boolean","description":"Whether the intervention was successful"}}},"InvokeActionRequest":{"type":"object","description":"Request to invoke a registered external action.\n\nCreates an action Ψ-term with the provided inputs,\nsends a webhook, and residuates on unbound outputs.","required":["tenant_id","action_name"],"properties":{"action_name":{"type":"string","description":"Name of the action to invoke"},"inputs":{"type":"object","description":"Input values for the action","additionalProperties":{},"propertyNames":{"type":"string"}},"tenant_id":{"type":"string","format":"uuid","description":"Tenant context"}}},"InvokeActionResponse":{"type":"object","description":"Response after invoking an action.","required":["invocation_id","term_id","status","callback_url","demons_attached","message"],"properties":{"callback_url":{"type":"string","description":"URL for the external system to POST completion to"},"demons_attached":{"type":"integer","description":"Number of demons attached for residuation","minimum":0},"invocation_id":{"type":"string","description":"Unique invocation ID (used for callback)"},"message":{"type":"string","description":"Confirmation message"},"status":{"type":"string","description":"Current status (always \"pending\" after invocation)"},"term_id":{"type":"string","format":"uuid","description":"The Ψ-term ID created for this action"}}},"IsSubtypeResponse":{"type":"object","description":"Response for subtype check","required":["is_subtype"],"properties":{"is_subtype":{"type":"boolean","description":"Whether the first sort is a subtype of the second"}}},"IterationMetricDto":{"type":"object","description":"Per-iteration metrics from differentiable FC.","required":["iteration","active_rules","max_attention","entropy","new_facts","mean_weight"],"properties":{"active_rules":{"type":"integer","minimum":0},"entropy":{"type":"number","format":"double"},"iteration":{"type":"integer","minimum":0},"max_attention":{"type":"number","format":"double"},"mean_weight":{"type":"number","format":"double"},"new_facts":{"type":"integer","minimum":0}}},"JsonValue":{"oneOf":[{"type":"string","description":"String value"},{"type":"integer","format":"int64","description":"Integer value"},{"type":"number","format":"double","description":"Floating-point number"},{"type":"boolean","description":"Boolean value"},{"type":"null","description":"Null value (maps to Uninstantiated)"},{"type":"array","items":{"$ref":"#/components/schemas/JsonValue"},"description":"Array of values"},{"type":"object","description":"Nested object (serialized to string)"}],"title":"JsonValue","description":"Raw JSON value. Accepts: string, integer, number, boolean, null, array of values, or nested object. Converted to domain Value type."},"JudgeConfigDto":{"type":"object","description":"Optional configuration overrides for the judge pipeline.","properties":{"enable_certificate":{"type":["boolean","null"],"description":"Whether to generate cryptographic certificate for safe verdicts"},"enable_faithfulness":{"type":["boolean","null"],"description":"Whether to enable faithfulness/deception detection"},"max_refinement_rounds":{"type":["integer","null"],"description":"Maximum refinement rounds (0 = single pass)","minimum":0},"min_safety_score":{"type":["number","null"],"format":"double","description":"Minimum safety score to consider safe (0.0-1.0, default: 0.8)"},"tnorm_strategy":{"type":["string","null"],"description":"T-norm strategy for composing layer scores: \"min\", \"product\", or \"lukasiewicz\""}}},"KbChangeDto":{"oneOf":[{"type":"object","description":"A new term was created","required":["term_id","sort_id","type"],"properties":{"sort_id":{"type":"string","format":"uuid"},"term_id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["TermCreated"]}}},{"type":"object","description":"A feature was bound","required":["term_id","feature","type"],"properties":{"feature":{"type":"string"},"term_id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["FeatureBound"]}}},{"type":"object","description":"A sort was narrowed","required":["term_id","old_sort","new_sort","type"],"properties":{"new_sort":{"type":"string","format":"uuid"},"old_sort":{"type":"string","format":"uuid"},"term_id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["SortNarrowed"]}}},{"type":"object","description":"Coreference established","required":["term1","term2","type"],"properties":{"term1":{"type":"string","format":"uuid"},"term2":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["Coreference"]}}}],"description":"KB change notification DTO."},"KbChangeType":{"type":"string","description":"Type of KB change.","enum":["added","updated","deleted","feature_modified"]},"LatticeStats":{"type":"object","description":"Statistics about the lattice","required":["total_sorts","root_sorts","leaf_sorts","synthetic_sorts","max_depth","multiple_inheritance_count"],"properties":{"leaf_sorts":{"type":"integer","description":"Number of leaf sorts (no children)","minimum":0},"max_depth":{"type":"integer","description":"Maximum depth of the hierarchy","minimum":0},"multiple_inheritance_count":{"type":"integer","description":"Number of sorts with multiple parents (multiple inheritance)","minimum":0},"root_sorts":{"type":"integer","description":"Number of root sorts (no parents)","minimum":0},"synthetic_sorts":{"type":"integer","description":"Number of synthetic sorts","minimum":0},"total_sorts":{"type":"integer","description":"Total number of sorts","minimum":0}}},"LatticeVisualizationRequest":{"type":"object","description":"Request for lattice (sort hierarchy) visualization","properties":{"generate_dot":{"type":"boolean","description":"Whether to generate DOT output"},"include_synthetic":{"type":"boolean","description":"Whether to include synthetic sorts (GLB/LUB created)"},"layout_algorithm":{"$ref":"#/components/schemas/LayoutAlgorithmDto","description":"Layout algorithm preference"},"layout_direction":{"$ref":"#/components/schemas/LayoutDirectionDto","description":"Layout direction preference"},"max_depth":{"type":["integer","null"],"format":"int32","description":"Maximum depth to traverse (default: unlimited)","minimum":0},"root_sort_id":{"type":["string","null"],"format":"uuid","description":"Optional root sort ID to start from"}}},"LatticeVisualizationResponse":{"type":"object","description":"Response for lattice visualization","required":["graph","stats"],"properties":{"graph":{"$ref":"#/components/schemas/VisualizationGraphDto","description":"The visualization graph"},"stats":{"$ref":"#/components/schemas/LatticeStats","description":"Statistics about the lattice"}}},"LayerResultDto":{"type":"object","description":"Per-layer verification result.","required":["layer","score","facts_checked","facts_satisfied","facts_violated","facts_residuated"],"properties":{"facts_checked":{"type":"integer","description":"Number of facts checked in this layer","minimum":0},"facts_residuated":{"type":"integer","description":"Number of facts pending (residuated)","minimum":0},"facts_satisfied":{"type":"integer","description":"Number of facts that passed","minimum":0},"facts_violated":{"type":"integer","description":"Number of facts that failed","minimum":0},"layer":{"type":"string","description":"Layer name (e.g., \"L0_format\", \"L6_resource\")"},"residuated_fact_ids":{"type":"array","items":{"type":"string"},"description":"Term IDs of residuated (pending) facts — what's still suspended"},"score":{"type":"number","format":"double","description":"Layer satisfaction score (0.0-1.0)"},"violation_descriptions":{"type":"array","items":{"type":"string"},"description":"Human-readable descriptions of each violation in this layer"}}},"LayerResultSummaryDto":{"type":"object","description":"Summary of a single verification layer result.","required":["layer","score","facts_checked","facts_satisfied"],"properties":{"facts_checked":{"type":"integer","description":"Number of facts checked","minimum":0},"facts_satisfied":{"type":"integer","description":"Number of facts satisfied","minimum":0},"layer":{"type":"string","description":"Layer name (e.g., \"L0_format\", \"L3_tool_contract\")"},"score":{"type":"number","format":"double","description":"Layer satisfaction score (0.0 to 1.0)"}}},"LayoutAlgorithmDto":{"oneOf":[{"type":"string","enum":["force_directed"]},{"type":"string","enum":["sugiyama"]},{"type":"string","enum":["circular"]},{"type":"string","enum":["grid"]},{"type":"string","enum":["radial"]},{"type":"object","required":["custom"],"properties":{"custom":{"type":"string"}}}],"description":"Layout algorithm hint"},"LayoutDirectionDto":{"type":"string","description":"Layout direction hint","enum":["top_bottom","bottom_top","left_right","right_left"]},"LayoutHintsDto":{"type":"object","description":"Layout hints for rendering","required":["algorithm"],"properties":{"algorithm":{"$ref":"#/components/schemas/LayoutAlgorithmDto","description":"Preferred layout algorithm"},"clusters":{"type":"object","description":"Cluster definitions","additionalProperties":{"type":"array","items":{"type":"string"}},"propertyNames":{"type":"string"}},"direction":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/LayoutDirectionDto","description":"Direction for hierarchical layouts"}]},"level_spacing":{"type":["number","null"],"format":"double","description":"Level spacing for hierarchical layouts (pixels)"},"node_spacing":{"type":["number","null"],"format":"double","description":"Node spacing (pixels)"}}},"LayoutModeDto":{"oneOf":[{"type":"object","required":["columns","type"],"properties":{"columns":{"type":"integer","format":"int32","minimum":0},"type":{"type":"string","enum":["grid"]}}},{"type":"object","required":["direction","type"],"properties":{"direction":{"type":"string"},"type":{"type":"string","enum":["flex"]}}},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["stack"]}}},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["tabs"]}}},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["split"]}}}],"description":"DTO for LayoutMode"},"LayoutSlotDto":{"type":"object","description":"DTO for LayoutSlot","required":["id","label"],"properties":{"id":{"type":"string"},"label":{"type":"string"}}},"LayoutSurfaceDto":{"type":"object","description":"DTO for LayoutSurface","required":["id","layout_mode","slots"],"properties":{"id":{"type":"string"},"layout_mode":{"$ref":"#/components/schemas/LayoutModeDto"},"slots":{"type":"array","items":{"$ref":"#/components/schemas/LayoutSlotDto"}}}},"LazyEvalRequest":{"type":"object","description":"Request to evaluate a term lazily","required":["session_id","term_id"],"properties":{"exclude_features":{"type":"array","items":{"type":"string"},"description":"Features to exclude from evaluation (non-strict arguments)"},"session_id":{"type":"string"},"term_id":{"type":"string"}}},"LazyEvalResponse":{"oneOf":[{"type":"object","required":["status","term_id"],"properties":{"status":{"type":"string","enum":["evaluated"]},"term_id":{"type":"string"}}},{"type":"object","required":["status","term_id"],"properties":{"status":{"type":"string","enum":["quoted"]},"term_id":{"type":"string"}}},{"type":"object","required":["status","term_ids"],"properties":{"status":{"type":"string","enum":["subterms_need_eval"]},"term_ids":{"type":"array","items":{"type":"string"}}}},{"type":"object","required":["status","function_term_id"],"properties":{"function_name":{"type":"string"},"function_term_id":{"type":"string"},"status":{"type":"string","enum":["needs_function_eval"]}}}],"title":"LazyEvalResponse","description":"Lazy evaluation result, discriminated by the 'status' field. Variants: evaluated, quoted, subterms_need_eval, needs_function_eval.","discriminator":{"propertyName":"status"}},"LearnFromCorrectionRequest":{"type":"object","description":"Request to learn from a user correction.","required":["tenant_id","agent_id","result_id","correct_pattern"],"properties":{"agent_id":{"type":"string","format":"uuid","description":"Agent ID"},"correct_pattern":{"type":"object","description":"The correct answer pattern (as Ψ-term features, raw JSON values)","additionalProperties":{"$ref":"#/components/schemas/JsonValue"},"propertyNames":{"type":"string"}},"correct_sort":{"type":["string","null"],"description":"Optional: The sort of the correct answer"},"result_id":{"type":"string","format":"uuid","description":"The result that was incorrect"},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"}}},"LearnFromCorrectionResponse":{"type":"object","description":"Response after learning from correction.","required":["correction_id","deprecated_rules","learning_event_id","message"],"properties":{"correction_id":{"type":"string","format":"uuid","description":"Created correction Ψ-term ID"},"deprecated_rules":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Rules deprecated by this correction"},"learning_event_id":{"type":"string","format":"uuid","description":"Learning event ID"},"message":{"type":"string","description":"Message"},"new_rule_id":{"type":["string","null"],"format":"uuid","description":"New rule created from correction"}}},"LearnPatternConfigDto":{"type":"object","description":"Configuration for pattern learning.","properties":{"max_recursion_depth":{"type":["integer","null"],"description":"Maximum recursion depth for evaluation. Default: 100","minimum":0},"min_examples":{"type":["integer","null"],"description":"Minimum examples required. Default: 3","minimum":0}}},"LearnPatternRequest":{"type":"object","description":"Request to learn a pattern from examples.","required":["name","examples"],"properties":{"config":{"$ref":"#/components/schemas/LearnPatternConfigDto","description":"Optional configuration."},"examples":{"type":"array","items":{"$ref":"#/components/schemas/TrainingExample"},"description":"Training examples (input, output pairs).\nAt least 3 examples are required."},"name":{"type":"string","description":"Name for this learning session."}}},"LearnPatternResponse":{"type":"object","description":"Response from pattern learning.","required":["success","examples_used","processing_time_ms"],"properties":{"error":{"type":["string","null"],"description":"Error message (if failed)."},"examples_used":{"type":"integer","description":"Number of examples used.","minimum":0},"pattern":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/LearnedPatternDto","description":"The learned pattern (if successful)."}]},"pattern_id":{"type":["string","null"],"description":"Pattern ID for subsequent evaluation calls."},"processing_time_ms":{"type":"integer","description":"Processing time in milliseconds.","minimum":0},"success":{"type":"boolean","description":"Whether learning succeeded."}}},"LearnSortSimilaritiesRequest":{"type":"object","description":"Request to learn sort similarities from behavioral data\n\nAnalyzes terms in the knowledge base to learn which sorts have similar\neffect distributions. Enables reasoning by analogy (bioisostere discovery).\n\n# Tenant Context\nThe tenant is determined from the `X-Tenant-Id` header.","required":["effect_feature"],"properties":{"effect_feature":{"type":"string","description":"Name of the numeric feature to analyze (e.g., \"potency\", \"ic50\", \"rating\")"},"min_samples":{"type":"integer","description":"Minimum number of samples required per sort (default: 5)","minimum":0},"min_similarity":{"type":"number","format":"double","description":"Minimum similarity threshold to record (0.0 to 1.0, default: 0.5)"}}},"LearnSortSimilaritiesResponse":{"type":"object","description":"Response for learning sort similarities","required":["learned_count","effect_feature","min_samples","min_similarity","message"],"properties":{"effect_feature":{"type":"string","description":"The feature that was analyzed"},"learned_count":{"type":"integer","description":"Number of sort similarity relationships learned","minimum":0},"message":{"type":"string","description":"Success message"},"min_samples":{"type":"integer","description":"Minimum samples threshold used","minimum":0},"min_similarity":{"type":"number","format":"double","description":"Minimum similarity threshold used"}}},"LearnedPatternDto":{"type":"object","description":"Learned pattern response.","required":["operation","input_feature","output_feature","base_case_inputs","confidence","description"],"properties":{"base_case_inputs":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Base case input values (e.g., [0] for factorial, [0, 1] for fibonacci)"},"confidence":{"type":"number","format":"double","description":"Confidence score (0.0 to 1.0)"},"description":{"type":"string","description":"Human-readable description of the learned pattern"},"input_feature":{"type":"string","description":"Input feature name"},"operation":{"$ref":"#/components/schemas/ArithmeticRecursionOpDto","description":"The detected arithmetic operation"},"output_feature":{"type":"string","description":"Output feature name"}}},"LearnedSimilarityDto":{"type":"object","description":"API representation of a learned similarity with review status","required":["sort1_id","sort2_id","degree","status","provenance","created_at","updated_at"],"properties":{"created_at":{"type":"string","description":"When this was created"},"degree":{"type":"number","format":"double","description":"Learned similarity degree ∈ [0, 1]"},"provenance":{"$ref":"#/components/schemas/LearnedSimilarityProvenanceDto","description":"Provenance information"},"sort1_id":{"type":"string","format":"uuid","description":"First sort ID (normalized order)"},"sort2_id":{"type":"string","format":"uuid","description":"Second sort ID (normalized order)"},"status":{"$ref":"#/components/schemas/LearnedSimilarityStatusDto","description":"Current status"},"updated_at":{"type":"string","description":"When this was last updated"}}},"LearnedSimilarityListResponse":{"type":"object","description":"Response for listing learned similarities","required":["similarities","count","pending_count","approved_count","conflicted_count"],"properties":{"approved_count":{"type":"integer","minimum":0},"conflicted_count":{"type":"integer","minimum":0},"count":{"type":"integer","description":"Total count","minimum":0},"pending_count":{"type":"integer","description":"Counts by status","minimum":0},"similarities":{"type":"array","items":{"$ref":"#/components/schemas/LearnedSimilarityDto"},"description":"List of learned similarities"}}},"LearnedSimilarityProvenanceDto":{"type":"object","description":"API representation of learned similarity provenance","required":["effect_feature","method","sort1_samples","sort2_samples"],"properties":{"confidence":{"type":["number","null"],"format":"double","description":"Statistical confidence (optional)"},"effect_feature":{"type":"string","description":"Feature used to compute similarity"},"method":{"type":"string","description":"Method used (Bhattacharyya, Correlation, Combined)"},"sort1_samples":{"type":"integer","description":"Sample count for sort1","minimum":0},"sort2_samples":{"type":"integer","description":"Sample count for sort2","minimum":0},"source":{"type":["string","null"],"description":"Source description (optional)"}}},"LearnedSimilarityStatusDto":{"oneOf":[{"type":"object","description":"Pending review","required":["learned_at","type"],"properties":{"learned_at":{"type":"string"},"type":{"type":"string","enum":["Proposed"]}}},{"type":"object","description":"Approved by a reviewer","required":["approved_by","approved_at","type"],"properties":{"approved_at":{"type":"string"},"approved_by":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["Approved"]}}},{"type":"object","description":"Rejected by a reviewer","required":["rejected_by","rejected_at","reason","type"],"properties":{"reason":{"type":"string"},"rejected_at":{"type":"string"},"rejected_by":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["Rejected"]}}},{"type":"object","description":"Conflicts with expert-defined similarity","required":["expert_degree","learned_degree","conflict_description","type"],"properties":{"conflict_description":{"type":"string"},"expert_degree":{"type":"number","format":"double"},"learned_degree":{"type":"number","format":"double"},"type":{"type":"string","enum":["Conflicted"]}}}],"description":"API representation of learned similarity status"},"LeastSortsResponse":{"type":"object","description":"Response with least sorts (most specific types)","required":["tenant_id","least_sorts"],"properties":{"least_sorts":{"type":"array","items":{"$ref":"#/components/schemas/SortInfoDto"}},"tenant_id":{"type":"string","format":"uuid"}}},"ListActionReviewsResponse":{"type":"object","description":"Response for listing pending action reviews","required":["items","total","page","page_size","has_more"],"properties":{"has_more":{"type":"boolean","description":"Whether there are more pages"},"items":{"type":"array","items":{"$ref":"#/components/schemas/PendingActionReviewDto"},"description":"List of actions pending review"},"page":{"type":"integer","description":"Current page","minimum":0},"page_size":{"type":"integer","description":"Page size","minimum":0},"total":{"type":"integer","description":"Total count (for pagination)","minimum":0}}},"ListAuditEntriesResponse":{"type":"object","required":["entries","total","page","page_size"],"properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/AuditEntryDto"}},"page":{"type":"integer","minimum":0},"page_size":{"type":"integer","minimum":0},"total":{"type":"integer","minimum":0}}},"ListBindingsResponse":{"type":"object","description":"Response listing all sort-table bindings.","required":["bindings"],"properties":{"bindings":{"type":"array","items":{"$ref":"#/components/schemas/BindingSummaryDto"},"description":"Active sort-table bindings."}}},"ListConversationsResponseDto":{"type":"object","description":"Response for listing conversations.","required":["conversations"],"properties":{"conversations":{"type":"array","items":{"$ref":"#/components/schemas/ConversationSummaryDto"}}}},"ListEvalFunctionsRequest":{"type":"object","description":"Request to list available functions","properties":{"category":{"type":["string","null"],"description":"Optional category filter"}}},"ListEvalFunctionsResponse":{"type":"object","description":"Response with available functions","required":["functions"],"properties":{"functions":{"type":"array","items":{"$ref":"#/components/schemas/EvalFunctionInfoDto"}}}},"ListExternalActionsResponse":{"type":"object","description":"Response listing all registered external actions for a tenant.","required":["tenant_id","actions","total"],"properties":{"actions":{"type":"array","items":{"$ref":"#/components/schemas/ExternalActionSummaryDto"},"description":"List of registered actions"},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"},"total":{"type":"integer","description":"Total count","minimum":0}}},"ListGoalsResponse":{"type":"object","description":"Response for listing saved goals.\n\nTRUE HOMOICONICITY: Goals are Ψ-terms persisted to PostgreSQL.\nThis endpoint returns all goals for the authenticated tenant.","required":["goals","count"],"properties":{"count":{"type":"integer","description":"Total number of goals","minimum":0},"goals":{"type":"array","items":{"$ref":"#/components/schemas/GoalSummaryDto"},"description":"List of saved goals"}}},"ListIncompleteDocumentsResponse":{"type":"object","description":"List of incomplete documents in a session","required":["session_id","incomplete_documents","total"],"properties":{"incomplete_documents":{"type":"array","items":{"$ref":"#/components/schemas/IncompleteDocumentDto"},"description":"Documents that need to be resumed"},"session_id":{"type":"string","format":"uuid","description":"Session ID"},"total":{"type":"integer","description":"Total count","minimum":0}}},"ListIngestionSessionsResponse":{"type":"object","description":"List of ingestion sessions","required":["sessions","total"],"properties":{"sessions":{"type":"array","items":{"$ref":"#/components/schemas/IngestionSessionResponse"},"description":"List of sessions"},"total":{"type":"integer","description":"Total count","minimum":0}}},"ListPatternsResponse":{"type":"object","description":"Response for listing patterns.","required":["count","patterns"],"properties":{"count":{"type":"integer","description":"Number of patterns.","minimum":0},"patterns":{"type":"array","items":{"$ref":"#/components/schemas/PatternSummaryDto"},"description":"Pattern summaries."}}},"ListPendingInvocationsResponse":{"type":"object","description":"Response listing pending invocations for a tenant.","required":["tenant_id","invocations","total_pending"],"properties":{"invocations":{"type":"array","items":{"$ref":"#/components/schemas/PendingInvocationDto"},"description":"List of pending invocations"},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"},"total_pending":{"type":"integer","description":"Total pending count","minimum":0}}},"ListPendingReviewsResponse":{"type":"object","description":"Response for listing pending reviews","required":["items","total","page","page_size","has_more"],"properties":{"has_more":{"type":"boolean","description":"Whether there are more pages"},"items":{"type":"array","items":{"$ref":"#/components/schemas/PendingReviewEntityDto"},"description":"List of entities pending review"},"page":{"type":"integer","description":"Current page","minimum":0},"page_size":{"type":"integer","description":"Page size","minimum":0},"total":{"type":"integer","description":"Total count (for pagination)","minimum":0}}},"ListPreferencesResponseDto":{"type":"object","description":"Response for listing preferences.","required":["preferences"],"properties":{"preferences":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceDto"}}}},"ListScenariosResponse":{"type":"object","description":"Response for GET /api/v1/scenarios — list all scenarios.","required":["scenarios","total"],"properties":{"scenarios":{"type":"array","items":{"$ref":"#/components/schemas/ScenarioSummaryDto"},"description":"List of scenario summaries, sorted by most recent first."},"total":{"type":"integer","description":"Total number of scenarios.","minimum":0}}},"ListSnapshotsResponse":{"type":"object","description":"Response for the list snapshots endpoint.","required":["snapshots"],"properties":{"snapshots":{"type":"array","items":{"$ref":"#/components/schemas/SnapshotResponse"},"description":"All snapshots across all tenants, ordered by creation time (newest first)."}}},"ListSourcesResponse":{"type":"object","description":"Response listing registered sources.","required":["sources","total"],"properties":{"sources":{"type":"array","items":{"$ref":"#/components/schemas/SourceSummaryDto"},"description":"List of registered source summaries"},"total":{"type":"integer","description":"Total count","minimum":0}}},"ListSymbolsRequest":{"type":"object","description":"Request to list module symbols","required":["session_id","module_name"],"properties":{"include_all_visible":{"type":"boolean","description":"If true, include inherited and imported symbols"},"module_name":{"type":"string"},"session_id":{"type":"string"}}},"ListSymbolsResponse":{"type":"object","description":"Response with module symbols","required":["module_name","symbols"],"properties":{"module_name":{"type":"string"},"symbols":{"type":"array","items":{"$ref":"#/components/schemas/SymbolDto"}}}},"ListTemplatesResponseDto":{"type":"object","description":"Response for listing templates.","required":["templates"],"properties":{"templates":{"type":"array","items":{"$ref":"#/components/schemas/QueryTemplateDto"}}}},"ListTenantsResponse":{"type":"object","description":"Response for the list-tenants endpoint.","required":["tenants"],"properties":{"tenants":{"type":"array","items":{"$ref":"#/components/schemas/TenantInfo"},"description":"All tenants that have data in the system"}}},"LiteralInputDto":{"type":"object","description":"A literal for NAF queries - a term with optional negation.\n\nIn TRUE HOMOICONICITY, literals are terms with an optional negation flag.\nThis replaces the legacy LiteralDto which used OsfClauseDto.","required":["term"],"properties":{"negated":{"type":"boolean","description":"If true, this literal is negated (negation as failure)"},"term":{"$ref":"#/components/schemas/TermInputDto","description":"The clause/term to prove or negate"}}},"MarkChoicePointRequest":{"type":"object","description":"Request to mark a choice point","properties":{"description":{"type":["string","null"],"description":"Optional description for the choice point"}}},"MarkMessagesReadRequest":{"type":"object","description":"Request to mark messages as read.","required":["tenant_id","agent_id"],"properties":{"agent_id":{"type":"string","format":"uuid","description":"Agent ID"},"message_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Message IDs to mark as read (empty = mark all)"},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"}}},"MarkMessagesReadResponse":{"type":"object","description":"Response after marking messages as read.","required":["marked_count","message"],"properties":{"marked_count":{"type":"integer","description":"Number of messages marked as read","minimum":0},"message":{"type":"string","description":"Message"}}},"MarkPendingRequest":{"type":"object","description":"Request to mark a residuation as pending","required":["session_id","term_id","operation_type"],"properties":{"operation_type":{"type":"string"},"session_id":{"type":"string"},"term_id":{"type":"string"}}},"MarkPendingResponse":{"type":"object","description":"Response after marking pending","required":["marked","term_id","operation_type"],"properties":{"marked":{"type":"boolean"},"operation_type":{"type":"string"},"term_id":{"type":"string"}}},"MarkRuleStoreRequest":{"type":"object","description":"Request to mark a rule store checkpoint"},"MarkRuleStoreResponse":{"type":"object","description":"Response with checkpoint marker","required":["marker_index"],"properties":{"marker_index":{"type":"integer","minimum":0}}},"MarkTermStoreRequest":{"type":"object","description":"Request to mark a choice point for backtracking"},"MarkTermStoreResponse":{"type":"object","description":"Response with marker info","required":["marker_index","trail_length"],"properties":{"marker_index":{"type":"integer","minimum":0},"trail_length":{"type":"integer","minimum":0}}},"MarkdownDocumentDto":{"type":"object","description":"A single markdown document for batch ingestion","required":["document_id","content"],"properties":{"content":{"type":"string","description":"The markdown content"},"document_id":{"type":"string","description":"Unique document identifier (for tracking)"},"metadata":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/DocumentMetadataDto","description":"Optional metadata about the document"}]}}},"MatchedEntityDto":{"type":"object","description":"A matched entity from pure OSF search","required":["term_id","sort_id","match_degree","community_id","features"],"properties":{"community_id":{"type":"string","format":"uuid","description":"Community this entity belongs to"},"features":{"type":"object","description":"Key features as strings","additionalProperties":{"type":"string"},"propertyNames":{"type":"string"}},"match_degree":{"type":"number","format":"double","description":"Match degree (0.0-1.0)"},"match_reason":{"type":["string","null"],"description":"Why this entity matched"},"name":{"type":["string","null"],"description":"Human-readable name (if available)"},"sort_id":{"type":"string","format":"uuid","description":"Sort ID"},"term_id":{"type":"string","format":"uuid","description":"Term ID"}}},"MaterializationSummaryDto":{"type":"object","description":"Summary of materialization results.","required":["sorts_created","sort_names","beliefs_created","rules_created","goal_created","constraints_created","guard_constraints_created","temporal_constraints_created","webhook_actions_created","tool_registrations_created","curriculum_stages_created","groundings_created","warnings"],"properties":{"beliefs_created":{"type":"integer","description":"Number of belief Psi-terms created.","minimum":0},"constraints_created":{"type":"integer","description":"Number of generic constraint terms created.","minimum":0},"curriculum_stages_created":{"type":"integer","description":"Number of curriculum stage terms created.","minimum":0},"goal_created":{"type":"boolean","description":"Whether a goal was created."},"groundings_created":{"type":"integer","description":"Number of grounding annotation terms created.","minimum":0},"guard_constraints_created":{"type":"integer","description":"Number of guard constraint terms created.","minimum":0},"rules_created":{"type":"integer","description":"Number of rules registered for inference.","minimum":0},"sort_names":{"type":"array","items":{"type":"string"},"description":"Names of sorts created."},"sorts_created":{"type":"integer","description":"Number of sorts created in the hierarchy.","minimum":0},"temporal_constraints_created":{"type":"integer","description":"Number of temporal constraint terms created.","minimum":0},"tool_registrations_created":{"type":"integer","description":"Number of tool registrations created.","minimum":0},"warnings":{"type":"array","items":{"type":"string"},"description":"Warnings from materialization (e.g., unknown parent sorts, skipped features)."},"webhook_actions_created":{"type":"integer","description":"Number of webhook action terms created.","minimum":0}}},"MathFunctionRequest":{"type":"object","description":"Request for math function","required":["session_id","function","args"],"properties":{"args":{"type":"array","items":{"type":["number","null"],"format":"double"},"description":"Arguments (some may be uninstantiated for bidirectional solving)"},"function":{"$ref":"#/components/schemas/MathFunctionType"},"session_id":{"type":"string"}}},"MathFunctionResponse":{"oneOf":[{"type":"object","description":"Operation succeeded","required":["result","status"],"properties":{"result":{"$ref":"#/components/schemas/MathResultDto"},"status":{"type":"string","enum":["success"]}}},{"type":"object","description":"Need to residuate","required":["term_ids","status"],"properties":{"status":{"type":"string","enum":["residuate"]},"term_ids":{"type":"array","items":{"type":"string"}}}},{"type":"object","description":"Domain error","required":["message","status"],"properties":{"message":{"type":"string"},"status":{"type":"string","enum":["domain_error"]}}},{"type":"object","description":"Constraint failed","required":["status"],"properties":{"status":{"type":"string","enum":["fail"]}}}],"description":"Response from math function"},"MathFunctionType":{"type":"string","description":"Math function types","enum":["sqrt","pow","sin","cos","tan","asin","acos","atan","atan2","sinh","cosh","tanh","asinh","acosh","atanh","exp","log","log10","floor","ceiling","round","truncate","abs","sign","pi","e","deg_to_rad","rad_to_deg"]},"MathResultDto":{"oneOf":[{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["integer"]},"value":{"type":"integer","format":"int64"}}},{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["real"]},"value":{"type":"number","format":"double"}}}],"description":"Math result (can be integer or real)"},"MeetPreservationDto":{"type":"object","description":"Meet-preservation verification sub-DTO.","required":["total_glb_pairs","pairs_within_tolerance","max_deviation","mean_deviation","violation_count"],"properties":{"max_deviation":{"type":"number","format":"double","description":"Maximum L2 deviation."},"mean_deviation":{"type":"number","format":"double","description":"Mean L2 deviation."},"pairs_within_tolerance":{"type":"integer","description":"Pairs within tolerance.","minimum":0},"total_glb_pairs":{"type":"integer","description":"Number of GLB pairs checked.","minimum":0},"violation_count":{"type":"integer","description":"Number of violations.","minimum":0}}},"MembershipDto":{"type":"object","description":"Membership information","required":["community_id","degree","level"],"properties":{"community_id":{"type":"string","format":"uuid","description":"Community ID"},"community_title":{"type":["string","null"],"description":"Community title (from report)"},"degree":{"type":"number","format":"double","description":"Membership degree (0.0 - 1.0, based on connectivity)"},"level":{"type":"integer","description":"Community level","minimum":0}}},"MergeEntityRequest":{"type":"object","description":"Request to merge entity with existing term","required":["review_id","target_term_id"],"properties":{"conflict_resolution":{"$ref":"#/components/schemas/ConflictResolution","description":"How to handle conflicting features"},"review_id":{"type":"string","format":"uuid","description":"The review ID to merge"},"target_term_id":{"type":"string","format":"uuid","description":"Target term ID to merge with"}}},"MetaSortsResponse":{"type":"object","description":"Response containing all meta sort IDs.\n\nClients need these IDs to create terms with built-in sorts like\n`guard_constraint`, `variable`, etc. This enables TRUE HOMOICONICITY\nwhere everything is referenced by ID, not by name.","required":["thing","variable","constraint","guard_constraint","allen_constraint","sort_constraint","equality_constraint","disequality_constraint","feature_constraint","clause","rule","goal","substitution","arithmetic_constraint","negation","entailment","disentailment","cut","findall_constraint","bagof_constraint","setof_constraint","aggregate_constraint","if_then_else_constraint","once_constraint","forall_constraint","call_constraint","plus_constraint","minus_constraint","times_constraint","div_constraint","mod_constraint","abs_constraint","max_constraint","min_constraint","between_constraint","succ_constraint","append_constraint","member_constraint","length_constraint","nth_constraint","reverse_constraint","last_constraint","real_constraint","real_plus_constraint","real_minus_constraint","real_times_constraint","real_div_constraint","real_le_constraint","real_ge_constraint","real_eq_constraint","real_between_constraint","real_abs_constraint","real_max_constraint","real_min_constraint","real_labeling_constraint","sat_constraint","sat_clause","sat_variable_sort","sat_literal","sat_assumption","sat_conflict","sat_assert","sat_check_sat","sat_get_model","smt_constraint","smt_assert","smt_check_sat","smt_push","smt_pop","smt_get_model","smt_get_proof","string_constraint","str_concat_constraint","str_length_constraint","str_contains_constraint","str_prefix_constraint","str_suffix_constraint","str_substr_constraint","str_replace_constraint","str_to_int_constraint","str_from_int_constraint","str_regex_match_constraint","str_labeling_constraint","regex_constraint","re_literal_constraint","re_concat_constraint","re_union_constraint","re_star_constraint","re_range_constraint","bv_constraint","bv_and_constraint","bv_or_constraint","bv_xor_constraint","bv_not_constraint","bv_add_constraint","bv_sub_constraint","bv_mul_constraint","bv_udiv_constraint","bv_shl_constraint","bv_lshr_constraint","bv_ashr_constraint","bv_concat_constraint","bv_extract_constraint","bv_ult_constraint","bv_slt_constraint","bv_labeling_constraint","array_constraint","array_select_constraint","array_store_constraint","array_const_constraint","array_ext_constraint","nla_constraint","nla_power_constraint","nla_polynomial_constraint","nla_labeling_constraint","fp_constraint","fp_add_constraint","fp_sub_constraint","fp_mul_constraint","fp_div_constraint","fp_sqrt_constraint","fp_eq_constraint","fp_lt_constraint","fp_to_real_constraint","fp_is_nan_constraint","datatype_constraint","dt_constructor_constraint","dt_selector_constraint","dt_tester_constraint","dt_update_constraint","optimization_constraint","minimize_objective","maximize_objective","soft_constraint","pareto_objective","lexicographic_objective","objective_result","tactic","simplify_tactic","cnf_tactic","nnf_tactic","propagate_values_tactic","solve_eqs_tactic","bit_blast_tactic","fourier_motzkin_tactic","tseitin_tactic","tactic_combinator","then_tactic","par_or_tactic","if_tactic","repeat_tactic","probe","num_vars_probe","depth_probe","qe_constraint","qe_exists","qe_forall","qe_eliminate","certified_proof","proof_step","proof_certificate","drat_clause","resolution_step","theory_lemma_proof","pdr_model_check","pdr_frame","pdr_cube","pdr_obligation","pdr_counterexample","pdr_transition","pdr_invariant"],"properties":{"abs_constraint":{"type":"string","format":"uuid","description":"Abs constraint (|X| = Y)"},"aggregate_constraint":{"type":"string","format":"uuid","description":"Aggregate constraint (count, sum, min, max, avg)"},"allen_constraint":{"type":"string","format":"uuid","description":"Allen temporal constraint sort (for interval relations: before, after, during, etc.)"},"append_constraint":{"type":"string","format":"uuid","description":"Append constraint ([A|B] = C)"},"arithmetic_constraint":{"type":"string","format":"uuid","description":"Arithmetic constraint (result = left_operand op right_operand)"},"array_const_constraint":{"type":"string","format":"uuid"},"array_constraint":{"type":"string","format":"uuid"},"array_ext_constraint":{"type":"string","format":"uuid"},"array_select_constraint":{"type":"string","format":"uuid"},"array_store_constraint":{"type":"string","format":"uuid"},"bagof_constraint":{"type":"string","format":"uuid","description":"Bagof constraint (collect solutions, fails if none)"},"between_constraint":{"type":"string","format":"uuid","description":"Between constraint (Low =< X =< High)"},"bit_blast_tactic":{"type":"string","format":"uuid"},"bv_add_constraint":{"type":"string","format":"uuid"},"bv_and_constraint":{"type":"string","format":"uuid"},"bv_ashr_constraint":{"type":"string","format":"uuid"},"bv_concat_constraint":{"type":"string","format":"uuid"},"bv_constraint":{"type":"string","format":"uuid"},"bv_extract_constraint":{"type":"string","format":"uuid"},"bv_labeling_constraint":{"type":"string","format":"uuid"},"bv_lshr_constraint":{"type":"string","format":"uuid"},"bv_mul_constraint":{"type":"string","format":"uuid"},"bv_not_constraint":{"type":"string","format":"uuid"},"bv_or_constraint":{"type":"string","format":"uuid"},"bv_shl_constraint":{"type":"string","format":"uuid"},"bv_slt_constraint":{"type":"string","format":"uuid"},"bv_sub_constraint":{"type":"string","format":"uuid"},"bv_udiv_constraint":{"type":"string","format":"uuid"},"bv_ult_constraint":{"type":"string","format":"uuid"},"bv_xor_constraint":{"type":"string","format":"uuid"},"call_constraint":{"type":"string","format":"uuid","description":"Call constraint (meta-call)"},"certified_proof":{"type":"string","format":"uuid"},"clause":{"type":"string","format":"uuid","description":"Clause sort (conjunction of constraints)"},"cnf_tactic":{"type":"string","format":"uuid"},"constraint":{"type":"string","format":"uuid","description":"Constraint base sort"},"cut":{"type":"string","format":"uuid","description":"Cut (commits to current choice point)"},"datatype_constraint":{"type":"string","format":"uuid"},"depth_probe":{"type":"string","format":"uuid"},"disentailment":{"type":"string","format":"uuid","description":"Disentailment constraint (antecedent -/-> consequent)"},"disequality_constraint":{"type":"string","format":"uuid","description":"Disequality constraint (X =/= Y)"},"div_constraint":{"type":"string","format":"uuid","description":"Div constraint (X / Y = Z)"},"drat_clause":{"type":"string","format":"uuid"},"dt_constructor_constraint":{"type":"string","format":"uuid"},"dt_selector_constraint":{"type":"string","format":"uuid"},"dt_tester_constraint":{"type":"string","format":"uuid"},"dt_update_constraint":{"type":"string","format":"uuid"},"entailment":{"type":"string","format":"uuid","description":"Entailment constraint (antecedent -> consequent)"},"equality_constraint":{"type":"string","format":"uuid","description":"Equality constraint (X .= Y)"},"feature_constraint":{"type":"string","format":"uuid","description":"Feature constraint (X.f .= Y)"},"findall_constraint":{"type":"string","format":"uuid","description":"Findall constraint (collect all solutions)"},"forall_constraint":{"type":"string","format":"uuid","description":"Forall constraint (universal quantification)"},"fourier_motzkin_tactic":{"type":"string","format":"uuid"},"fp_add_constraint":{"type":"string","format":"uuid"},"fp_constraint":{"type":"string","format":"uuid"},"fp_div_constraint":{"type":"string","format":"uuid"},"fp_eq_constraint":{"type":"string","format":"uuid"},"fp_is_nan_constraint":{"type":"string","format":"uuid"},"fp_lt_constraint":{"type":"string","format":"uuid"},"fp_mul_constraint":{"type":"string","format":"uuid"},"fp_sqrt_constraint":{"type":"string","format":"uuid"},"fp_sub_constraint":{"type":"string","format":"uuid"},"fp_to_real_constraint":{"type":"string","format":"uuid"},"goal":{"type":"string","format":"uuid","description":"Goal sort (what we're proving)"},"guard_constraint":{"type":"string","format":"uuid","description":"Guard constraint sort (for comparisons like <, >, <=, >=)"},"if_tactic":{"type":"string","format":"uuid"},"if_then_else_constraint":{"type":"string","format":"uuid","description":"If-then-else constraint"},"last_constraint":{"type":"string","format":"uuid","description":"Last constraint"},"length_constraint":{"type":"string","format":"uuid","description":"Length constraint (length(List) = N)"},"lexicographic_objective":{"type":"string","format":"uuid"},"max_constraint":{"type":"string","format":"uuid","description":"Max constraint (max(X, Y) = Z)"},"maximize_objective":{"type":"string","format":"uuid"},"member_constraint":{"type":"string","format":"uuid","description":"Member constraint (X in List)"},"min_constraint":{"type":"string","format":"uuid","description":"Min constraint (min(X, Y) = Z)"},"minimize_objective":{"type":"string","format":"uuid"},"minus_constraint":{"type":"string","format":"uuid","description":"Minus constraint (X - Y = Z)"},"mod_constraint":{"type":"string","format":"uuid","description":"Mod constraint (X mod Y = Z)"},"negation":{"type":"string","format":"uuid","description":"Negation as failure (not(clause))"},"nla_constraint":{"type":"string","format":"uuid"},"nla_labeling_constraint":{"type":"string","format":"uuid"},"nla_polynomial_constraint":{"type":"string","format":"uuid"},"nla_power_constraint":{"type":"string","format":"uuid"},"nnf_tactic":{"type":"string","format":"uuid"},"nth_constraint":{"type":"string","format":"uuid","description":"Nth constraint (nth element of list)"},"num_vars_probe":{"type":"string","format":"uuid"},"objective_result":{"type":"string","format":"uuid"},"once_constraint":{"type":"string","format":"uuid","description":"Once constraint (succeed at most once)"},"optimization_constraint":{"type":"string","format":"uuid"},"par_or_tactic":{"type":"string","format":"uuid"},"pareto_objective":{"type":"string","format":"uuid"},"pdr_counterexample":{"type":"string","format":"uuid"},"pdr_cube":{"type":"string","format":"uuid"},"pdr_frame":{"type":"string","format":"uuid"},"pdr_invariant":{"type":"string","format":"uuid"},"pdr_model_check":{"type":"string","format":"uuid"},"pdr_obligation":{"type":"string","format":"uuid"},"pdr_transition":{"type":"string","format":"uuid"},"plus_constraint":{"type":"string","format":"uuid","description":"Plus constraint (X + Y = Z)"},"probe":{"type":"string","format":"uuid"},"proof_certificate":{"type":"string","format":"uuid"},"proof_step":{"type":"string","format":"uuid"},"propagate_values_tactic":{"type":"string","format":"uuid"},"qe_constraint":{"type":"string","format":"uuid"},"qe_eliminate":{"type":"string","format":"uuid"},"qe_exists":{"type":"string","format":"uuid"},"qe_forall":{"type":"string","format":"uuid"},"re_concat_constraint":{"type":"string","format":"uuid"},"re_literal_constraint":{"type":"string","format":"uuid"},"re_range_constraint":{"type":"string","format":"uuid"},"re_star_constraint":{"type":"string","format":"uuid"},"re_union_constraint":{"type":"string","format":"uuid"},"real_abs_constraint":{"type":"string","format":"uuid","description":"Real absolute value: |arg| = result"},"real_between_constraint":{"type":"string","format":"uuid","description":"Real between: lower <= var <= upper"},"real_constraint":{"type":"string","format":"uuid","description":"Parent sort for all real/rational constraints"},"real_div_constraint":{"type":"string","format":"uuid","description":"Real division: dividend / divisor = result"},"real_eq_constraint":{"type":"string","format":"uuid","description":"Real equality: left = right"},"real_ge_constraint":{"type":"string","format":"uuid","description":"Real greater-equal: left >= right"},"real_labeling_constraint":{"type":"string","format":"uuid","description":"Real labeling: solve collected real constraints"},"real_le_constraint":{"type":"string","format":"uuid","description":"Real less-equal: left <= right"},"real_max_constraint":{"type":"string","format":"uuid","description":"Real maximum: max(left, right) = result"},"real_min_constraint":{"type":"string","format":"uuid","description":"Real minimum: min(left, right) = result"},"real_minus_constraint":{"type":"string","format":"uuid","description":"Real subtraction: left - right = result"},"real_plus_constraint":{"type":"string","format":"uuid","description":"Real addition: left + right = result"},"real_times_constraint":{"type":"string","format":"uuid","description":"Real multiplication: coefficient * variable = result"},"regex_constraint":{"type":"string","format":"uuid"},"repeat_tactic":{"type":"string","format":"uuid"},"resolution_step":{"type":"string","format":"uuid"},"reverse_constraint":{"type":"string","format":"uuid","description":"Reverse constraint"},"rule":{"type":"string","format":"uuid","description":"Rule sort (head :- body)"},"sat_assert":{"type":"string","format":"uuid","description":"SAT assert: add a clause to the solver"},"sat_assumption":{"type":"string","format":"uuid","description":"SAT assumption: assumed literal for incremental solving"},"sat_check_sat":{"type":"string","format":"uuid","description":"SAT check-sat: run the CDCL solver"},"sat_clause":{"type":"string","format":"uuid","description":"SAT clause: a disjunction of literals"},"sat_conflict":{"type":"string","format":"uuid","description":"SAT conflict: learned clause from conflict analysis"},"sat_constraint":{"type":"string","format":"uuid","description":"Parent sort for all SAT constraints"},"sat_get_model":{"type":"string","format":"uuid","description":"SAT get-model: retrieve the satisfying assignment"},"sat_literal":{"type":"string","format":"uuid","description":"SAT literal: variable with polarity"},"sat_variable_sort":{"type":"string","format":"uuid","description":"SAT variable sort"},"setof_constraint":{"type":"string","format":"uuid","description":"Setof constraint (collect unique sorted solutions)"},"simplify_tactic":{"type":"string","format":"uuid"},"smt_assert":{"type":"string","format":"uuid","description":"SMT assert: add a formula to the SMT solver"},"smt_check_sat":{"type":"string","format":"uuid","description":"SMT check-sat: run the DPLL(T) solver"},"smt_constraint":{"type":"string","format":"uuid","description":"SMT constraint: parent sort for all SMT constraints"},"smt_get_model":{"type":"string","format":"uuid","description":"SMT get-model: retrieve the SMT model"},"smt_get_proof":{"type":"string","format":"uuid","description":"SMT get-proof: retrieve the proof of unsatisfiability"},"smt_pop":{"type":"string","format":"uuid","description":"SMT pop: pop an assertion scope"},"smt_push":{"type":"string","format":"uuid","description":"SMT push: push an assertion scope"},"soft_constraint":{"type":"string","format":"uuid"},"solve_eqs_tactic":{"type":"string","format":"uuid"},"sort_constraint":{"type":"string","format":"uuid","description":"Sort constraint (X : S)"},"str_concat_constraint":{"type":"string","format":"uuid"},"str_contains_constraint":{"type":"string","format":"uuid"},"str_from_int_constraint":{"type":"string","format":"uuid"},"str_labeling_constraint":{"type":"string","format":"uuid"},"str_length_constraint":{"type":"string","format":"uuid"},"str_prefix_constraint":{"type":"string","format":"uuid"},"str_regex_match_constraint":{"type":"string","format":"uuid"},"str_replace_constraint":{"type":"string","format":"uuid"},"str_substr_constraint":{"type":"string","format":"uuid"},"str_suffix_constraint":{"type":"string","format":"uuid"},"str_to_int_constraint":{"type":"string","format":"uuid"},"string_constraint":{"type":"string","format":"uuid"},"substitution":{"type":"string","format":"uuid","description":"Substitution sort (variable bindings)"},"succ_constraint":{"type":"string","format":"uuid","description":"Succ constraint (successor: S = X + 1)"},"tactic":{"type":"string","format":"uuid"},"tactic_combinator":{"type":"string","format":"uuid"},"then_tactic":{"type":"string","format":"uuid"},"theory_lemma_proof":{"type":"string","format":"uuid"},"thing":{"type":"string","format":"uuid","description":"The root \"thing\" sort (top of hierarchy)"},"times_constraint":{"type":"string","format":"uuid","description":"Times constraint (X * Y = Z)"},"tseitin_tactic":{"type":"string","format":"uuid"},"variable":{"type":"string","format":"uuid","description":"Variable sort - unbound terms"}}},"MissingInfoDto":{"type":"object","description":"Information about what's missing from a query","required":["kind","description","priority"],"properties":{"description":{"type":"string","description":"Human-readable description"},"kind":{"type":"string","description":"Kind of missing information"},"priority":{"type":"integer","format":"int32","description":"Priority (lower = more important)","minimum":0}}},"ModifyActionRequest":{"type":"object","description":"Request to modify and approve an action","required":["review_id","modified_params"],"properties":{"modified_params":{"type":"object","description":"Modified input parameters (will override suggested params)","additionalProperties":{},"propertyNames":{"type":"string"}},"notes":{"type":["string","null"],"description":"Optional notes about the modification"},"review_id":{"type":"string","format":"uuid","description":"The review ID to modify"}}},"ModularArithRequest":{"type":"object","description":"Request for modular arithmetic","required":["operation","arg1","arg2"],"properties":{"arg1":{"type":"integer","format":"int64"},"arg2":{"type":"integer","format":"int64"},"operation":{"$ref":"#/components/schemas/ModularOperationType"}}},"ModularArithResponse":{"type":"object","description":"Response from modular arithmetic","required":["result"],"properties":{"result":{"type":"integer","format":"int64"}}},"ModularOperationType":{"type":"string","description":"Modular arithmetic operations","enum":["mod","gcd","lcm"]},"MonadicFactDto":{"type":"object","description":"A monadic fact with depth and confidence.","required":["term_id","sort_name","derivation_depth","confidence","is_given"],"properties":{"confidence":{"type":"number","format":"double"},"derivation_depth":{"type":"integer","format":"int32","minimum":0},"is_given":{"type":"boolean"},"sort_name":{"type":"string"},"term_id":{"type":"string","format":"uuid"}}},"MonadicFixpointRequest":{"type":"object","description":"Request for monadic fixpoint (Phase 3).","properties":{"max_iterations":{"type":"integer","format":"int32","description":"Maximum T∘μ iterations (default: 50).","minimum":0}}},"MonadicFixpointResponse":{"type":"object","description":"Response for monadic fixpoint.","required":["facts","iterations","fixpoint_reached","given_count","derived_count","max_depth","elapsed_ms"],"properties":{"derived_count":{"type":"integer","description":"Number of derived facts.","minimum":0},"elapsed_ms":{"type":"integer","format":"int64","description":"Elapsed time in milliseconds.","minimum":0},"facts":{"type":"array","items":{"$ref":"#/components/schemas/MonadicFactDto"},"description":"Monadic facts at fixpoint."},"fixpoint_reached":{"type":"boolean","description":"Whether the fixpoint was reached."},"given_count":{"type":"integer","description":"Number of given (initial) facts.","minimum":0},"iterations":{"type":"integer","description":"Number of T∘μ iterations.","minimum":0},"max_depth":{"type":"integer","format":"int32","description":"Maximum derivation depth.","minimum":0}}},"MotivationStateDto":{"type":"object","description":"Full motivation state DTO combining drives, deficits, and curiosity.","required":["drives","deficits","curiosity_targets"],"properties":{"curiosity_targets":{"type":"array","items":{"$ref":"#/components/schemas/CuriosityTargetDto"},"description":"Curiosity targets sorted by exploration priority"},"deficits":{"type":"array","items":{"$ref":"#/components/schemas/DriveDeficitDto"},"description":"Current drive deficits (drives below baseline)"},"dominant_drive":{"type":["string","null"],"description":"The dominant drive type (highest deficit urgency), if any"},"drives":{"type":"array","items":{"$ref":"#/components/schemas/DriveDto"},"description":"Active drives"}}},"NafProveRequest":{"type":"object","description":"Request for NAF-enabled backward chaining.\n\nNAF (Negation as Failure) extends backward chaining with:\n- Positive literals: must succeed\n- Negative literals: must fail (closed-world assumption)","properties":{"goal_id":{"type":["string","null"],"format":"uuid","description":"Load a previously saved NAF goal by ID.\nEither `literals` or `goal_id` must be provided, but not both."},"literals":{"type":"array","items":{"$ref":"#/components/schemas/LiteralInputDto"},"description":"Literals to prove (conjunction with negation support).\nEither `literals` or `goal_id` must be provided, but not both."},"max_depth":{"type":"integer","description":"Maximum proof depth","default":100,"minimum":0},"max_solutions":{"type":"integer","description":"Maximum number of solutions","default":1000,"minimum":0},"save_goal":{"type":"boolean","description":"If true, save the goal for later reuse (returns goal_id in response).\nOnly applies when `literals` is provided (not when loading via goal_id)."},"timeout_ms":{"type":["integer","null"],"format":"int64","description":"Wall-clock timeout in milliseconds. The proof search stops after this\nduration and returns whatever solutions have been found so far.\nDefault: 30000 (30 seconds). Set to 0 or null to disable.","default":30000,"minimum":0}}},"NafRequest":{"type":"object","description":"Request for negation as failure","required":["session_id","goal"],"properties":{"goal":{"type":"object"},"session_id":{"type":"string"}}},"NafResponse":{"type":"object","description":"Response from negation as failure","required":["result"],"properties":{"result":{"type":"boolean","description":"True if goal failed (negation succeeded)"}}},"NamespaceDto":{"type":"object","description":"Namespace DTO","required":["id","path","name","visibility","tags"],"properties":{"description":{"type":["string","null"],"description":"Description"},"id":{"type":"string","format":"uuid","description":"Unique identifier"},"name":{"type":"string","description":"Name (last segment)"},"parent_id":{"type":["string","null"],"format":"uuid","description":"Parent namespace ID"},"path":{"type":"string","description":"Full path (e.g., \"org.acme.engineering\")"},"tags":{"type":"array","items":{"type":"string"},"description":"Tags"},"visibility":{"$ref":"#/components/schemas/VisibilityDto","description":"Visibility level"}}},"NamespaceListResponse":{"type":"object","description":"List of namespaces response","required":["namespaces","count"],"properties":{"count":{"type":"integer","minimum":0},"namespaces":{"type":"array","items":{"$ref":"#/components/schemas/NamespaceDto"}}}},"NamespaceResponse":{"type":"object","description":"Single namespace response","required":["namespace"],"properties":{"namespace":{"$ref":"#/components/schemas/NamespaceDto"}}},"NegativeExampleDto":{"type":"object","description":"A generated negative example with provenance.","required":["term_id","sort_id","strategy","explanation","rejection_reason"],"properties":{"explanation":{"type":"string","description":"Human-readable explanation of why this is negative."},"rejection_reason":{"type":"string","description":"The rejection reason category."},"sort_id":{"type":"string","format":"uuid","description":"The sort this negative was generated against."},"strategy":{"type":"string","description":"The strategy used to generate this negative."},"term_id":{"type":"string","format":"uuid","description":"The term ID of the negative example."}}},"NetworkStatusDto":{"type":"string","description":"Task network status.","enum":["pending","executing","completed","failed"]},"NeuroSymbolicStatusResponse":{"type":"object","description":"Response for the neuro-symbolic status endpoint.","required":["enabled"],"properties":{"enabled":{"type":"boolean","description":"Whether the neuro-symbolic subsystem is enabled."},"status":{"type":["object","null"],"description":"Full status snapshot (None if disabled)."}}},"NlQueryMode":{"type":"string","description":"Translation mode for NL queries","enum":["llm","constraint","cognitive","triz"]},"NlQueryRequest":{"type":"object","description":"Natural language query request","required":["query","tenant_id"],"properties":{"confirm_session":{"type":["boolean","null"],"description":"Optional: confirm a TRIZ session (triggers invention pipeline)"},"conversation_history":{"type":["array","null"],"items":{"$ref":"#/components/schemas/ConversationTurnDto"},"description":"Optional conversation history for context (llm mode only)"},"exclude_domains":{"type":["array","null"],"items":{"type":"string"},"description":"Optional: domain names to exclude from results"},"focus_proposal":{"type":["integer","null"],"description":"Optional: focus on a specific proposal index (0-based) for refinement","minimum":0},"images":{"type":["array","null"],"items":{"$ref":"#/components/schemas/ImageInputDto"},"description":"Optional images for multimodal TRIZ analysis (base64-encoded)"},"mode":{"$ref":"#/components/schemas/NlQueryMode","description":"Translation mode: \"llm\" (default), \"constraint\", or \"cognitive\""},"query":{"type":"string","description":"The natural language question"},"session_id":{"type":["string","null"],"format":"uuid","description":"Optional session ID for cognitive mode (persists agent learning across queries)"},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID for the query"}}},"NlQueryResponse":{"type":"object","description":"Natural language query response","required":["success","query","mode","results"],"properties":{"agent_id":{"type":["string","null"],"format":"uuid","description":"Agent ID used for cognitive mode (for session continuity)"},"cognitive_summary":{"type":["string","null"],"description":"Cognitive cycle summary (E2E completion: NL response from Ψ-term results)"},"error":{"type":["string","null"],"description":"Error message if failed"},"explanation":{"type":["string","null"],"description":"Explanation from LLM/model"},"generated_osf":{"type":["string","null"],"description":"Generated OSF query (for debugging, llm mode)"},"mode":{"$ref":"#/components/schemas/NlQueryMode","description":"Mode used for translation"},"novelty_scores":{"type":["array","null"],"items":{},"description":"Novelty scores for inventive proposals"},"query":{"type":"string","description":"Original query"},"results":{"type":"array","items":{"$ref":"#/components/schemas/NlQueryResultItem"},"description":"Results from query execution"},"structured_problem":{"description":"Structured problem from TRIZ session (for user confirmation)"},"success":{"type":"boolean","description":"Whether the query was successful"},"tool_call":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ToolCallInfo","description":"Tool call info (constraint mode)"}]},"triz_session_status":{"type":["string","null"],"description":"TRIZ session status (for multi-turn refinement)"}}},"NlQueryResultItem":{"type":"object","description":"Result item from NL query","required":["id","sort_name","features"],"properties":{"features":{"type":"object","description":"Features as key-value pairs","additionalProperties":{},"propertyNames":{"type":"string"}},"id":{"type":"string","format":"uuid","description":"Term ID"},"sort_name":{"type":"string","description":"Sort name"}}},"NodeTypeDto":{"oneOf":[{"type":"string","enum":["sort"]},{"type":"string","enum":["synthetic_sort"]},{"type":"string","enum":["root_sort"]},{"type":"string","enum":["bottom_sort"]},{"type":"string","enum":["constraint"]},{"type":"string","enum":["fd_variable"]},{"type":"string","enum":["term"]},{"type":"string","enum":["feature"]},{"type":"string","enum":["reference"]},{"type":"string","enum":["residuated_term"]},{"type":"string","enum":["trigger"]},{"type":"string","enum":["relation"]},{"type":"object","required":["custom"],"properties":{"custom":{"type":"string"}}}],"description":"Node type in the graph"},"NumberFormatDto":{"type":"object","description":"Number format options","properties":{"precision":{"type":["integer","null"],"description":"Precision for real numbers","minimum":0},"scientific":{"type":"boolean","description":"Use scientific notation"}}},"NumberToStringRequest":{"type":"object","description":"Request for int2str or real2str conversion","required":["value"],"properties":{"format":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/NumberFormatDto","description":"Optional format specifier (e.g., precision for reals)"}]},"value":{"$ref":"#/components/schemas/NumberValueDto"}}},"NumberToStringResponse":{"type":"object","description":"Response from number to string conversion","required":["result"],"properties":{"result":{"type":"string"}}},"NumberValueDto":{"oneOf":[{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["integer"]},"value":{"type":"integer","format":"int64"}}},{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["real"]},"value":{"type":"number","format":"double"}}}],"description":"Number value for conversion"},"OAuthStartResponse":{"type":"object","required":["auth_url"],"properties":{"auth_url":{"type":"string"}}},"ObserveMultiRequest":{"type":"object","required":["observations"],"properties":{"observations":{"type":"object","description":"Map of variable name to value","additionalProperties":{"type":"number","format":"double"},"propertyNames":{"type":"string"}}}},"ObserveMultiResponse":{"type":"object","required":["success","variables"],"properties":{"success":{"type":"boolean","description":"Success flag"},"variables":{"type":"array","items":{"type":"string"},"description":"Variables observed"}}},"ObservePairRequest":{"type":"object","required":["var_x","var_y","x","y"],"properties":{"var_x":{"type":"string","description":"First variable name"},"var_y":{"type":"string","description":"Second variable name"},"x":{"type":"number","format":"double","description":"Value for first variable"},"y":{"type":"number","format":"double","description":"Value for second variable"}}},"ObservePairResponse":{"type":"object","required":["success","count"],"properties":{"count":{"type":"integer","description":"Current observation count for this pair","minimum":0},"success":{"type":"boolean","description":"Success flag"}}},"ObserveSingleRequest":{"type":"object","required":["variable","value"],"properties":{"value":{"type":"number","format":"double","description":"Observed value"},"variable":{"type":"string","description":"Variable name"}}},"ObserveSingleResponse":{"type":"object","required":["success","count"],"properties":{"count":{"type":"integer","description":"Current observation count for this variable","minimum":0},"success":{"type":"boolean","description":"Success flag"}}},"OcrConfigDto":{"type":"object","description":"Configuration for document parsing (OCR)","properties":{"enable_fallback":{"type":"boolean","description":"Fall back to alternative parser on failure"},"extract_images":{"type":"boolean","description":"Extract embedded images"},"extract_tables":{"type":"boolean","description":"Extract tables as markdown"},"force_ocr":{"type":"boolean","description":"Force OCR even for text-based PDFs"},"languages":{"type":"array","items":{"type":"string"},"description":"Language hints for OCR (ISO 639-1 codes)"},"parser":{"$ref":"#/components/schemas/DocumentParser","description":"Primary parser to use"},"use_llm_enhancement":{"type":"boolean","description":"Use LLM to improve table/formula accuracy"}}},"OntologyClarificationQuestionDto":{"type":"object","description":"Clarification question DTO for the API response.","required":["id","question","field","type"],"properties":{"choices":{"type":["array","null"],"items":{"type":"string"}},"default":{"type":["string","null"]},"field":{"type":"string"},"id":{"type":"string"},"question":{"type":"string"},"type":{"type":"string"}}},"OntologyRagRequestDto":{"type":"object","description":"Request DTO for Ontology RAG query","required":["query_text","concept_sort_id"],"properties":{"concept_sort_id":{"type":"string","format":"uuid","description":"Sort ID for concept terms"},"concept_values":{"type":["object","null"],"description":"Optional: Map of concept_id → numeric value (e.g., mastery, score, confidence)\nThe interpretation of these values is domain-specific","additionalProperties":{"type":"number","format":"double"},"propertyNames":{"type":"string"}},"feature_config":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/FeatureConfigDto","description":"Feature configuration - allows caller to specify feature names\nIf not provided, uses defaults (requires, teaches, related, etc.)"}]},"include_dependents":{"type":"boolean","description":"Whether to include dependents (default: true)"},"include_prerequisites":{"type":"boolean","description":"Whether to include prerequisites (default: true)"},"include_related":{"type":"boolean","description":"Whether to include related concepts (default: true)"},"max_concepts":{"type":"integer","description":"Maximum concepts to retrieve (default: 10)","minimum":0},"min_degree":{"type":"number","format":"double","description":"Minimum similarity degree (0.0-1.0, default: 0.7)"},"query_text":{"type":"string","description":"The query text to search for"},"value_threshold":{"type":["number","null"],"format":"double","description":"Optional: Threshold for concept_values to flag items (e.g., gaps below threshold)"}}},"OntologyRagResponseDto":{"type":"object","description":"Response DTO for Ontology RAG query","required":["primary_concepts","prerequisites","dependents","related","stats"],"properties":{"dependents":{"type":"array","items":{"$ref":"#/components/schemas/DependentInfoDto"},"description":"Concepts that depend on primary concepts"},"prerequisites":{"type":"array","items":{"$ref":"#/components/schemas/PrerequisiteInfoDto"},"description":"Prerequisites of primary concepts"},"primary_concepts":{"type":"array","items":{"$ref":"#/components/schemas/ConceptMatchDto"},"description":"Primary concepts matching the query"},"related":{"type":"array","items":{"$ref":"#/components/schemas/RelatedInfoDto"},"description":"Related concepts (lateral exploration)"},"stats":{"$ref":"#/components/schemas/OntologyRagStatsDto","description":"Query statistics"}}},"OntologyRagStatsDto":{"type":"object","description":"Query stats DTO","required":["embedding_search_ms","feature_unification_ms","emergent_discovery_ms","terms_searched","terms_unified","emergent_discovered"],"properties":{"embedding_search_ms":{"type":"integer","format":"int64","minimum":0},"emergent_discovered":{"type":"integer","minimum":0},"emergent_discovery_ms":{"type":"integer","format":"int64","minimum":0},"feature_unification_ms":{"type":"integer","format":"int64","minimum":0},"terms_searched":{"type":"integer","minimum":0},"terms_unified":{"type":"integer","minimum":0}}},"OsfClauseDto":{"type":"object","title":"OsfClauseDto","description":"OSF clause containing a list of constraints. Used in inference rules as head/body clauses.","required":["constraints"],"properties":{"constraints":{"type":"array","items":{"$ref":"#/components/schemas/OsfConstraintDto"},"description":"List of OSF constraints"}}},"OsfConstraintDto":{"oneOf":[{"type":"object","required":["type","var","sort_id"],"properties":{"sort_id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["Sort"]},"var":{"type":"string"}}},{"type":"object","required":["type","var1","var2"],"properties":{"type":{"type":"string","enum":["Equality"]},"var1":{"type":"string"},"var2":{"type":"string"}}},{"type":"object","required":["type","var","feature","value"],"properties":{"feature":{"type":"string"},"type":{"type":"string","enum":["Feature"]},"value":{"$ref":"#/components/schemas/FeatureTargetDto"},"var":{"type":"string"}}},{"type":"object","required":["type","antecedent","consequent"],"properties":{"antecedent":{"$ref":"#/components/schemas/OsfClauseDto"},"confidence":{"type":"number","format":"double"},"consequent":{"$ref":"#/components/schemas/OsfClauseDto"},"type":{"type":"string","enum":["Entailment"]}}},{"type":"object","required":["type","antecedent","consequent"],"properties":{"antecedent":{"$ref":"#/components/schemas/OsfClauseDto"},"confidence":{"type":"number","format":"double"},"consequent":{"$ref":"#/components/schemas/OsfClauseDto"},"type":{"type":"string","enum":["Disentailment"]}}},{"type":"object","required":["type","result","op","operand1"],"properties":{"op":{"type":"string"},"operand1":{"type":"string"},"operand2":{"type":"string"},"result":{"type":"string"},"type":{"type":"string","enum":["Arithmetic"]}}},{"type":"object","required":["type","left","op","right"],"properties":{"left":{"type":"string"},"op":{"type":"string"},"right":{"type":"string"},"type":{"type":"string","enum":["Guard"]}}},{"type":"object","required":["type","var1","var2"],"properties":{"type":{"type":"string","enum":["Disequality"]},"var1":{"type":"string"},"var2":{"type":"string"}}},{"type":"object","required":["type","clause"],"properties":{"clause":{"$ref":"#/components/schemas/OsfClauseDto"},"type":{"type":"string","enum":["Negation"]}}},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["Cut"]}}},{"type":"object","required":["type","template","goal","results"],"properties":{"goal":{"$ref":"#/components/schemas/OsfClauseDto"},"results":{"type":"string"},"template":{"type":"string"},"type":{"type":"string","enum":["Findall"]}}},{"type":"object","required":["type","op","goal","result"],"properties":{"goal":{"$ref":"#/components/schemas/OsfClauseDto"},"op":{"type":"string"},"result":{"type":"string"},"type":{"type":"string","enum":["Aggregate"]},"var":{"type":"string"}}},{"type":"object","required":["type","condition","then_branch","else_branch"],"properties":{"condition":{"$ref":"#/components/schemas/OsfClauseDto"},"else_branch":{"$ref":"#/components/schemas/OsfClauseDto"},"then_branch":{"$ref":"#/components/schemas/OsfClauseDto"},"type":{"type":"string","enum":["IfThenElse"]}}},{"type":"object","required":["type","goal"],"properties":{"goal":{"$ref":"#/components/schemas/OsfClauseDto"},"type":{"type":"string","enum":["Once"]}}},{"type":"object","required":["type","template","goal","bag"],"properties":{"bag":{"type":"string"},"goal":{"$ref":"#/components/schemas/OsfClauseDto"},"template":{"type":"string"},"type":{"type":"string","enum":["Bagof"]}}},{"type":"object","required":["type","template","goal","set"],"properties":{"goal":{"$ref":"#/components/schemas/OsfClauseDto"},"set":{"type":"string"},"template":{"type":"string"},"type":{"type":"string","enum":["Setof"]}}},{"type":"object","required":["type","cond","action"],"properties":{"action":{"$ref":"#/components/schemas/OsfClauseDto"},"cond":{"$ref":"#/components/schemas/OsfClauseDto"},"type":{"type":"string","enum":["Forall"]}}},{"type":"object","required":["type","goal"],"properties":{"goal":{"$ref":"#/components/schemas/OsfClauseDto"},"type":{"type":"string","enum":["Call"]}}},{"type":"object","required":["type","clause"],"properties":{"clause":{"$ref":"#/components/schemas/OsfClauseDto"},"type":{"type":"string","enum":["Assert"]}}},{"type":"object","required":["type","clause"],"properties":{"clause":{"$ref":"#/components/schemas/OsfClauseDto"},"type":{"type":"string","enum":["Retract"]}}},{"type":"object","required":["type","term","copy"],"properties":{"copy":{"type":"string"},"term":{"$ref":"#/components/schemas/OsfClauseDto"},"type":{"type":"string","enum":["CopyTerm"]}}},{"type":"object","required":["type","var"],"properties":{"type":{"type":"string","enum":["Var"]},"var":{"type":"string"}}},{"type":"object","required":["type","term"],"properties":{"term":{"$ref":"#/components/schemas/OsfClauseDto"},"type":{"type":"string","enum":["Ground"]}}},{"type":"object","required":["type","element","list"],"properties":{"element":{"type":"string"},"list":{"type":"string"},"type":{"type":"string","enum":["Member"]}}},{"type":"object","required":["type","list1","list2","result"],"properties":{"list1":{"type":"string"},"list2":{"type":"string"},"result":{"type":"string"},"type":{"type":"string","enum":["Append"]}}},{"type":"object","required":["type","list","length"],"properties":{"length":{"type":"string"},"list":{"type":"string"},"type":{"type":"string","enum":["Length"]}}},{"type":"object","required":["type","index","list","element"],"properties":{"element":{"type":"string"},"index":{"type":"string"},"list":{"type":"string"},"type":{"type":"string","enum":["Nth0"]}}},{"type":"object","required":["type","list","reversed"],"properties":{"list":{"type":"string"},"reversed":{"type":"string"},"type":{"type":"string","enum":["Reverse"]}}},{"type":"object","required":["type","low","high","value"],"properties":{"high":{"type":"string"},"low":{"type":"string"},"type":{"type":"string","enum":["Between"]},"value":{"type":"string"}}},{"type":"object","required":["type","list","last"],"properties":{"last":{"type":"string"},"list":{"type":"string"},"type":{"type":"string","enum":["Last"]}}},{"type":"object","required":["type","x","s"],"properties":{"s":{"type":"string"},"type":{"type":"string","enum":["Succ"]},"x":{"type":"string"}}},{"type":"object","required":["type","x","y","z"],"properties":{"type":{"type":"string","enum":["Plus"]},"x":{"type":"string"},"y":{"type":"string"},"z":{"type":"string"}}},{"type":"object","required":["type","x","y","z"],"properties":{"type":{"type":"string","enum":["Minus"]},"x":{"type":"string"},"y":{"type":"string"},"z":{"type":"string"}}},{"type":"object","required":["type","x","y","z"],"properties":{"type":{"type":"string","enum":["Times"]},"x":{"type":"string"},"y":{"type":"string"},"z":{"type":"string"}}},{"type":"object","required":["type","x","y","z"],"properties":{"type":{"type":"string","enum":["Div"]},"x":{"type":"string"},"y":{"type":"string"},"z":{"type":"string"}}},{"type":"object","required":["type","x","y","z"],"properties":{"type":{"type":"string","enum":["ModConstraint"]},"x":{"type":"string"},"y":{"type":"string"},"z":{"type":"string"}}},{"type":"object","required":["type","x","abs"],"properties":{"abs":{"type":"string"},"type":{"type":"string","enum":["AbsConstraint"]},"x":{"type":"string"}}},{"type":"object","required":["type","x","y","max"],"properties":{"max":{"type":"string"},"type":{"type":"string","enum":["MaxConstraint"]},"x":{"type":"string"},"y":{"type":"string"}}},{"type":"object","required":["type","x","y","min"],"properties":{"min":{"type":"string"},"type":{"type":"string","enum":["MinConstraint"]},"x":{"type":"string"},"y":{"type":"string"}}},{"type":"object","required":["type","x","y","z"],"properties":{"type":{"type":"string","enum":["FuzzyPlus"]},"x":{"type":"string"},"y":{"type":"string"},"z":{"type":"string"}}},{"type":"object","required":["type","x","y","z"],"properties":{"type":{"type":"string","enum":["FuzzyMinus"]},"x":{"type":"string"},"y":{"type":"string"},"z":{"type":"string"}}},{"type":"object","required":["type","x","y","z"],"properties":{"type":{"type":"string","enum":["FuzzyTimes"]},"x":{"type":"string"},"y":{"type":"string"},"z":{"type":"string"}}},{"type":"object","required":["type","x","y","z"],"properties":{"type":{"type":"string","enum":["FuzzyDiv"]},"x":{"type":"string"},"y":{"type":"string"},"z":{"type":"string"}}},{"type":"object","required":["type","fuzzy_var","op","threshold"],"properties":{"fuzzy_var":{"type":"string"},"op":{"type":"string"},"threshold":{"type":"number","format":"double"},"type":{"type":"string","enum":["FuzzyGuard"]}}},{"type":"object","required":["type","list","sorted"],"properties":{"list":{"type":"string"},"sorted":{"type":"string"},"type":{"type":"string","enum":["Msort"]}}},{"type":"object","required":["type","list","flat"],"properties":{"flat":{"type":"string"},"list":{"type":"string"},"type":{"type":"string","enum":["Flatten"]}}},{"type":"object","required":["type","element","goal","list","included"],"properties":{"element":{"type":"string"},"goal":{"$ref":"#/components/schemas/OsfClauseDto"},"included":{"type":"string"},"list":{"type":"string"},"type":{"type":"string","enum":["Include"]}}},{"type":"object","required":["type","element","goal","list","excluded"],"properties":{"element":{"type":"string"},"excluded":{"type":"string"},"goal":{"$ref":"#/components/schemas/OsfClauseDto"},"list":{"type":"string"},"type":{"type":"string","enum":["Exclude"]}}},{"type":"object","required":["type","list","sorted"],"properties":{"list":{"type":"string"},"sorted":{"type":"string"},"type":{"type":"string","enum":["SortList"]}}},{"type":"object","required":["type","list","perm"],"properties":{"list":{"type":"string"},"perm":{"type":"string"},"type":{"type":"string","enum":["Permutation"]}}},{"type":"object","required":["type","element","list","rest"],"properties":{"element":{"type":"string"},"list":{"type":"string"},"rest":{"type":"string"},"type":{"type":"string","enum":["Select"]}}},{"type":"object","required":["type","list1","list2","result"],"properties":{"list1":{"type":"string"},"list2":{"type":"string"},"result":{"type":"string"},"type":{"type":"string","enum":["Subtract"]}}},{"type":"object","required":["type","list","sum"],"properties":{"list":{"type":"string"},"sum":{"type":"string"},"type":{"type":"string","enum":["SumList"]}}},{"type":"object","required":["type","index","list","element"],"properties":{"element":{"type":"string"},"index":{"type":"string"},"list":{"type":"string"},"type":{"type":"string","enum":["Nth1"]}}},{"type":"object","required":["type","name","args"],"properties":{"args":{"type":"array","items":{"type":"object","description":"JSON value"}},"name":{"type":"string"},"type":{"type":"string","enum":["Builtin"]}}}],"title":"OsfConstraintDto","description":"OSF constraint discriminated by the 'type' field. Variants: Sort, Equality, Feature, Entailment, Disentailment, Arithmetic, Guard, Disequality, Negation, Cut, Findall, Aggregate, IfThenElse, Once, Bagof, Setof, Forall, Call, Assert, Retract, CopyTerm, Var, Ground, Member, Append, Length, Nth0, Reverse, Between, Last, Succ, Plus, Minus, Times, Div, ModConstraint, AbsConstraint, MaxConstraint, MinConstraint, FuzzyPlus, FuzzyMinus, FuzzyTimes, FuzzyDiv, FuzzyGuard, Msort, Flatten, Include, Exclude, SortList, Permutation, Select, Subtract, SumList, Nth1, Builtin.","discriminator":{"propertyName":"type"}},"OsfSearchRequest":{"type":"object","description":"Request for pure OSF search\n\nThis performs structured search using only OSF operations (no LLM).\nReturns entities, discovered relations, and provenance information.\n\nKey differentiator from other search endpoints:\n- Discovers relations between matched entities automatically\n- Handles incomplete queries via residuation\n- Returns structured results with full provenance\n\n# Tenant Context\nThe tenant is determined from the `X-Tenant-Id` header.","required":["pattern"],"properties":{"collection_id":{"type":["string","null"],"format":"uuid","description":"Optional: filter by collection (if not provided, searches all collections)"},"enable_unification":{"type":"boolean","description":"Enable fuzzy unification for deeper relation discovery"},"max_entities":{"type":"integer","description":"Maximum number of entities to return (default: 100)","minimum":0},"min_match_degree":{"type":"number","format":"double","description":"Minimum match degree threshold (default: 0.0 = all matches)"},"namespace_id":{"type":["string","null"],"format":"uuid","description":"Optional: filter by namespace (if not provided, searches all namespaces)"},"pattern":{"$ref":"#/components/schemas/TermPatternDto","description":"Query pattern (sort and optional features)"},"term_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Optional: specific term IDs to search within (empty = all terms for tenant)"}}},"OsfSearchResponse":{"type":"object","description":"Response from pure OSF search","required":["entities","relations","stats"],"properties":{"entities":{"type":"array","items":{"$ref":"#/components/schemas/MatchedEntityDto"},"description":"Matched entities with provenance"},"relations":{"type":"array","items":{"$ref":"#/components/schemas/DiscoveredRelationDto"},"description":"Discovered relations between entities"},"stats":{"$ref":"#/components/schemas/OsfSearchStatsDto","description":"Search statistics"},"suspended":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/SuspendedQueryDto","description":"If query was incomplete, information about what's missing"}]}}},"OsfSearchStatsDto":{"type":"object","description":"Statistics from pure OSF search","required":["communities_searched","entities_matched","relations_discovered","inference_steps","duration_us"],"properties":{"communities_searched":{"type":"integer","description":"Number of communities searched","minimum":0},"duration_us":{"type":"integer","format":"int64","description":"Processing time in microseconds","minimum":0},"entities_matched":{"type":"integer","description":"Number of entities matched","minimum":0},"inference_steps":{"type":"integer","description":"Number of inference steps (if inference enabled)","minimum":0},"relations_discovered":{"type":"integer","description":"Number of relations discovered","minimum":0}}},"OsfqlErrorResponse":{"type":"object","description":"Error response for OSFQL execution failures.","required":["error_type","message"],"properties":{"error_type":{"type":"string","description":"Error type: \"parse\", \"compile\", or \"execution\"."},"message":{"type":"string","description":"Human-readable error message."}}},"OsfqlRequest":{"type":"object","description":"Request to execute an OSFQL program.","required":["query"],"properties":{"query":{"type":"string","description":"OSFQL program text (one or more statements separated by `;`).\n\n# Examples\n\n```text\nMATCH person(name: ?N, age: ?A) WHERE ?A > 18;\n```\n\n```text\nINSERT person(name: \"Alice\", age: 30);\nMATCH person(name: ?N);\n```"}}},"OsfqlResponse":{"type":"object","description":"Response from executing an OSFQL program.","required":["success","bindings","produced_term_ids","diagnostics","statement_count"],"properties":{"bindings":{"type":"array","items":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/OsfqlValueDto"},"propertyNames":{"type":"string"}},"description":"Variable bindings from MATCH queries."},"defined_sort_ids":{"type":"array","items":{"type":"string"},"description":"IDs of newly defined sorts (from DEFINE statements)."},"diagnostics":{"type":"array","items":{"type":"string"},"description":"Diagnostic messages from the execution pipeline."},"produced_term_ids":{"type":"array","items":{"type":"string"},"description":"IDs of produced/modified terms (from INSERT, DERIVE, etc.)."},"statement_count":{"type":"integer","description":"Number of statements executed.","minimum":0},"success":{"type":"boolean","description":"Whether the execution succeeded."}}},"OsfqlValueDto":{"oneOf":[{"type":"object","description":"Integer value.","required":["value","type"],"properties":{"type":{"type":"string","enum":["integer"]},"value":{"type":"integer","format":"int64","description":"Integer value."}}},{"type":"object","description":"Floating-point value.","required":["value","type"],"properties":{"type":{"type":"string","enum":["float"]},"value":{"type":"number","format":"double","description":"Floating-point value."}}},{"type":"object","description":"String value.","required":["value","type"],"properties":{"type":{"type":"string","enum":["string"]},"value":{"type":"string","description":"String value."}}},{"type":"object","description":"Boolean value.","required":["value","type"],"properties":{"type":{"type":"string","enum":["boolean"]},"value":{"type":"boolean","description":"Boolean value."}}},{"type":"object","description":"Reference to a term (by UUID).","required":["value","type"],"properties":{"type":{"type":"string","enum":["term_ref"]},"value":{"type":"string","description":"Reference to a term (by UUID)."}}}],"description":"A bound value in an OSFQL result."},"OutputFormatDto":{"type":"string","description":"Output format for the rendered context","enum":["yaml","markdown","json"]},"OversightAlertDto":{"type":"object","description":"An alert DTO for live oversight sessions.","required":["severity","layer","message","step_index"],"properties":{"agent_id":{"type":["string","null"],"description":"Agent ID responsible (for multi-agent systems)"},"layer":{"type":"string","description":"Verification layer that triggered the alert"},"message":{"type":"string","description":"Human-readable alert message"},"severity":{"type":"string","description":"Alert severity: \"info\", \"warning\", or \"critical\""},"step_index":{"type":"integer","description":"Index of the trajectory step that triggered the alert","minimum":0}}},"OversightWsParams":{"type":"object","description":"Parameters for WebSocket connection to oversight session event stream.","required":["session_id","tenant_id"],"properties":{"session_id":{"type":"string","description":"Session ID to subscribe to"},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID for isolation"}}},"ParsedDocumentMetadataDto":{"type":"object","description":"Metadata extracted from a parsed document","required":["page_count","word_count","document_type"],"properties":{"author":{"type":["string","null"],"description":"Document author"},"created_at":{"type":["string","null"],"description":"Creation date (ISO 8601)"},"document_type":{"$ref":"#/components/schemas/DocumentType","description":"Detected document type"},"language":{"type":["string","null"],"description":"Detected language (ISO 639-1)"},"page_count":{"type":"integer","description":"Number of pages","minimum":0},"source_filename":{"type":["string","null"],"description":"Original filename"},"title":{"type":["string","null"],"description":"Document title"},"word_count":{"type":"integer","description":"Word count in extracted text","minimum":0}}},"PartialCorrelationRequest":{"type":"object","required":["var_x","var_y","conditioning_set"],"properties":{"conditioning_set":{"type":"array","items":{"type":"string"},"description":"Conditioning set"},"var_x":{"type":"string","description":"First variable name"},"var_y":{"type":"string","description":"Second variable name"}}},"PartialCorrelationResponse":{"type":"object","required":["count","success"],"properties":{"count":{"type":"integer","description":"Number of observations","minimum":0},"partial_correlation":{"type":["number","null"],"format":"double","description":"Partial correlation coefficient"},"success":{"type":"boolean","description":"Success flag"}}},"PatternDto":{"oneOf":[{"type":"object","required":["name","type"],"properties":{"name":{"type":"string"},"type":{"type":"string","enum":["Variable"]}}},{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["Integer"]},"value":{"type":"integer","format":"int64"}}},{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["Real"]},"value":{"type":"number","format":"double"}}},{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["String"]},"value":{"type":"string"}}},{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["Boolean"]},"value":{"type":"boolean"}}},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["Wildcard"]}}}],"description":"Pattern for matching function arguments"},"PatternSummaryDto":{"type":"object","description":"Summary of a learned pattern.","required":["pattern_id","operation","confidence","base_case_inputs"],"properties":{"base_case_inputs":{"type":"array","items":{"type":"integer","format":"int64"},"description":"Base case inputs."},"confidence":{"type":"number","format":"double","description":"Confidence score."},"operation":{"$ref":"#/components/schemas/ArithmeticRecursionOpDto","description":"The arithmetic operation."},"pattern_id":{"type":"string","description":"Pattern ID."}}},"PendingActionReviewDto":{"type":"object","description":"An action pending review","required":["review_id","action_term_id","action_sort","suggested_params","confidence","reason","status","created_at","priority"],"properties":{"action_sort":{"type":"string","description":"Action type (e.g., \"llm_generate\", \"web_search\", \"file_write\")"},"action_term_id":{"type":"string","format":"uuid","description":"The action term ID"},"agent_id":{"type":["string","null"],"format":"uuid","description":"Agent ID that initiated the action (if applicable)"},"confidence":{"type":"number","format":"double","description":"Action confidence score (0.0 - 1.0)"},"created_at":{"type":"string","description":"When the review was created"},"deadline":{"type":["string","null"],"description":"Review deadline (if set)"},"goal_context_id":{"type":["string","null"],"format":"uuid","description":"Goal context ID that triggered this action"},"priority":{"type":"number","format":"double","description":"Computed priority score (0.0 - 1.0)"},"reason":{"$ref":"#/components/schemas/ActionReviewReasonDto","description":"Why this action requires review"},"review_id":{"type":"string","format":"uuid","description":"Unique review ID"},"status":{"$ref":"#/components/schemas/ActionReviewStatusDto","description":"Current status"},"suggested_params":{"type":"object","description":"Suggested input parameters for the action","additionalProperties":{},"propertyNames":{"type":"string"}}}},"PendingInvocationDto":{"type":"object","description":"Summary of a pending invocation.","required":["invocation_id","action_name","term_id","status","inputs","invoked_at","timeout_at"],"properties":{"action_name":{"type":"string","description":"Action name"},"inputs":{"type":"object","description":"Input values","additionalProperties":{},"propertyNames":{"type":"string"}},"invocation_id":{"type":"string","description":"Invocation ID"},"invoked_at":{"type":"string","description":"When invoked (ISO 8601)"},"status":{"type":"string","description":"Current status"},"term_id":{"type":"string","format":"uuid","description":"The Ψ-term ID"},"timeout_at":{"type":"string","description":"When it will timeout (ISO 8601)"}}},"PendingReviewDto":{"type":"object","description":"Entity pending human review","required":["entity_id","sort","candidates","reason"],"properties":{"candidates":{"type":"array","items":{"$ref":"#/components/schemas/CandidateMatchDto"},"description":"Candidate matches for deduplication"},"entity_id":{"type":"string","description":"Entity local identifier"},"reason":{"type":"string","description":"Reason why review is needed"},"sort":{"type":"string","description":"Entity sort name"}}},"PendingReviewEntityDto":{"type":"object","description":"An entity pending review","required":["review_id","entity_id","sort","features","confidence","reason","candidates","sort_suggestions","created_at"],"properties":{"alignment_status":{"type":["string","null"],"description":"Alignment status: \"exact\", \"fuzzy\", \"lesser\", or \"unaligned\""},"candidates":{"type":"array","items":{"$ref":"#/components/schemas/ReviewCandidateMatchDto"},"description":"Candidate matches for deduplication"},"char_interval":{"type":["array","null"],"items":{"type":"integer","minimum":0},"description":"Character interval in source text where entity was found (start, end)"},"confidence":{"type":"number","format":"double","description":"Extraction confidence score (0.0 - 1.0)"},"created_at":{"type":"string","description":"When the entity was extracted"},"entity_id":{"type":"string","description":"Entity local ID (from extraction)"},"features":{"type":"object","description":"Extracted features as key-value pairs","additionalProperties":{},"propertyNames":{"type":"string"}},"reason":{"$ref":"#/components/schemas/ReviewReason","description":"Why this entity needs review"},"review_id":{"type":"string","format":"uuid","description":"Unique review ID"},"sort":{"type":"string","description":"Extracted sort name"},"sort_suggestions":{"type":"array","items":{"$ref":"#/components/schemas/SortSuggestionDto"},"description":"Alternative sort suggestions"},"source_document":{"type":["string","null"],"description":"Document/chunk the entity was extracted from"},"source_text":{"type":["string","null"],"description":"Original text span that was extracted"}}},"PinInput":{"type":"object","description":"A pre-assigned `(agent, day, shift)` triple, optionally naming\nwhich role the pin covers.\n\nWhen the agent has **multiple roles that each match a role\nminimum** at the target slot, the caller MUST set [`PinInput::role`]\nto disambiguate. Otherwise the engine returns HTTP 400 — the\nsilent greedy-match that used to happen here could pick the\n\"wrong\" role and produce spurious infeasibility.\n\nRole semantics:\n * `None` — caller hasn't chosen. Valid only if the agent has at\n most one role matching this slot's role_mins.\n * `Some(\"any\")` — explicit request to route through the\n unroled pool; no role minimum is decremented.\n * `Some(role)` — force the pin to cover this role. Must be a\n role the agent possesses (HTTP 400 otherwise).","required":["agent_id","day","shift"],"properties":{"agent_id":{"type":"string"},"day":{"type":"integer","minimum":0},"role":{"type":["string","null"],"description":"Role the pin covers. See struct-level docs for the cases."},"shift":{"type":"integer","minimum":0}}},"PipelineQualityStatsDto":{"type":"object","description":"Pipeline quality statistics from validation gates and feedback loop","required":["inference_rules_total","inference_rules_filtered_low_confidence","inference_rules_invalid_scope_sort","inference_rules_applied","relations_from_inference_rules","inference_relations_deduped","axioms_deduplicated","entities_validated","fully_valid","entities_sort_corrected","entities_rejected","incomplete_entities","inconsistent_sorts","forward_chaining_issues","feedback_axioms_learned","feedback_pipeline_adjustments","dynamic_config_entity_threshold","dynamic_config_relation_threshold","hybrid_intra_batch_deduped","pattern_rules_persisted","inference_iterations","relations_inferred"],"properties":{"axioms_deduplicated":{"type":"integer","description":"Axioms deduplicated by content key across chunks","minimum":0},"dynamic_config_entity_threshold":{"type":"number","format":"double","description":"Dynamic entity confidence threshold based on KB maturity"},"dynamic_config_relation_threshold":{"type":"number","format":"double","description":"Dynamic relation confidence threshold based on KB maturity"},"entities_rejected":{"type":"integer","description":"Entities rejected by validation","minimum":0},"entities_sort_corrected":{"type":"integer","description":"Entities auto-corrected to a better sort","minimum":0},"entities_validated":{"type":"integer","description":"Entities that passed validation","minimum":0},"feedback_axioms_learned":{"type":"integer","description":"Axioms learned from entity feature patterns","minimum":0},"feedback_pipeline_adjustments":{"type":"integer","description":"Pipeline threshold adjustments applied by dynamic config","minimum":0},"forward_chaining_issues":{"type":"integer","description":"Total quality issues from forward chaining","minimum":0},"fully_valid":{"type":"integer","description":"Entities fully valid (all constraints pass)","minimum":0},"hybrid_intra_batch_deduped":{"type":"integer","description":"LLM entities deduped against NER entities by normalized name in hybrid mode","minimum":0},"incomplete_entities":{"type":"integer","description":"Entities missing required features","minimum":0},"inconsistent_sorts":{"type":"integer","description":"Entities with incompatible sort assignments","minimum":0},"inference_iterations":{"type":"integer","description":"Number of forward-chaining iterations executed.","minimum":0},"inference_relations_deduped":{"type":"integer","description":"Relations from inference rules deduplicated against existing","minimum":0},"inference_rules_applied":{"type":"integer","description":"Inference rules successfully applied (expanded to relations)","minimum":0},"inference_rules_filtered_low_confidence":{"type":"integer","description":"Inference rules filtered due to low confidence","minimum":0},"inference_rules_invalid_scope_sort":{"type":"integer","description":"Inference rules with scope_sort not found among entities","minimum":0},"inference_rules_total":{"type":"integer","description":"Total inference rules extracted across all chunks","minimum":0},"pattern_rules_persisted":{"type":"integer","description":"Pattern rules generated from co-occurrence analysis.\nThese are homoiconic Ψ-term rules persisted to the term store.","minimum":0},"relations_from_inference_rules":{"type":"integer","description":"Total relations generated from inference rule expansion","minimum":0},"relations_inferred":{"type":"integer","description":"Total relations derived by forward chaining.","minimum":0}}},"PlanMatchDto":{"type":"object","description":"A matching plan from the library.","required":["template_id","match_score","success_rate","use_count","actions"],"properties":{"actions":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Action sequence"},"match_score":{"type":"number","format":"double","description":"Match score (0.0-1.0)"},"success_rate":{"type":"number","format":"double","description":"Historical success rate"},"template_id":{"type":"string","format":"uuid","description":"Plan template ID"},"use_count":{"type":"integer","format":"int64","description":"Number of times used"}}},"PositionalArgumentDto":{"type":"object","description":"A positional argument","required":["position","value"],"properties":{"position":{"type":"integer","minimum":0},"value":{"$ref":"#/components/schemas/ExecutionValueDto"}}},"PredictEffectRequest":{"allOf":[{"$ref":"#/components/schemas/QueryTerm","description":"Query term (by ID or inline with sort_id + features)"},{"type":"object","required":["effect_var"],"properties":{"conformal":{"type":["number","null"],"format":"double","description":"Optional conformal coverage (e.g., 0.9 for 90% coverage). If set, std_dev is inflated\nby the empirical quantile of normalized residuals from matching sources."},"effect_var":{"type":"string","description":"Name of the feature containing the FuzzyNumber effect to aggregate"},"gating":{"type":["string","null"],"description":"Gating method: None (default fuzzy), or \"learned\" for metric-gated similarity"},"min_degree":{"type":"number","format":"double","description":"Minimum similarity degree for matching terms (0.0 to 1.0)"},"robust":{"type":"boolean","description":"Use robust aggregation (Student‑t/Huber) to downweight outliers"},"similarity_mode":{"type":"string","description":"String similarity strategy:\n- \"fast\": Exact → Normalized → Jaccard only (NO embeddings) - fastest\n- \"hybrid\": Exact → Normalized → Jaccard → Embeddings (default)\n- \"semantic\": Exact → Normalized → Embeddings (skip Jaccard) - most accurate for NL","example":"hybrid"}}}],"description":"Request for term-based effect prediction"},"PredictEffectResponse":{"type":"object","description":"Response from effect prediction","required":["success","degree","sources_merged","proof_trace","query_time_ms"],"properties":{"all_effects":{"type":"object","description":"ALL effects as FuzzyNumbers (multi-parameter drug design)\nKeys: effect_potency, effect_lipophilicity, effect_metabolic_stability, etc.","additionalProperties":{"$ref":"#/components/schemas/EffectDto"},"propertyNames":{"type":"string"}},"degree":{"type":"number","format":"double","description":"Combined confidence/degree from Bayesian merging"},"description":{"type":["string","null"],"description":"Transformation description"},"effect":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/EffectDto","description":"Primary effect (backward compatibility - typically potency/ΔpIC50)"}]},"proof_trace":{"type":"array","items":{"type":"string"},"description":"Explanation trace for debugging"},"query_time_ms":{"type":"integer","description":"Query execution time in milliseconds","minimum":0},"source":{"type":["string","null"],"description":"Source description (e.g., literature reference)"},"sources_merged":{"type":"integer","description":"Number of source terms merged","minimum":0},"success":{"type":"boolean","description":"Whether prediction was successful"}}},"PredictFromDiscoveryRequest":{"type":"object","description":"Request to predict effect for a query point.","required":["discovery_sort_id","current_values"],"properties":{"current_values":{"type":"object","description":"Current feature values.","additionalProperties":{"type":"number","format":"double"},"propertyNames":{"type":"string"}},"discovery_sort_id":{"type":"string","format":"uuid","description":"The root sort ID from discovery."},"min_similarity":{"type":"number","format":"double","description":"Minimum similarity for matching."},"top_k":{"type":"integer","description":"Number of similar terms to consider.","minimum":0}}},"PredictFromDiscoveryResponse":{"type":"object","description":"Response from prediction.","required":["success","predictions","similar_terms","avg_similarity","query_time_ms"],"properties":{"avg_similarity":{"type":"number","format":"double","description":"Average similarity degree."},"predictions":{"type":"object","description":"Predicted effects by horizon.","additionalProperties":{"$ref":"#/components/schemas/EffectPredictionDto"},"propertyNames":{"type":"string"}},"query_time_ms":{"type":"integer","description":"Query time in milliseconds.","minimum":0},"similar_terms":{"type":"integer","description":"Number of similar terms found.","minimum":0},"success":{"type":"boolean"}}},"PredictPreferencesRequest":{"type":"object","description":"Request to predict preference scores for candidates","required":["user_id","sort_id","candidate_ids"],"properties":{"candidate_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"sort_id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"}}},"PredictPreferencesResponse":{"type":"object","description":"Response with preference predictions","required":["predictions"],"properties":{"predictions":{"type":"array","items":{"$ref":"#/components/schemas/PreferencePrediction"}}}},"PredictionErrorDto":{"type":"object","description":"Prediction error DTO.","required":["goal_id","predicted","actual","error_magnitude","is_surprise"],"properties":{"actual":{"type":"string","description":"Actual outcome"},"error_magnitude":{"type":"number","format":"double","description":"Error magnitude (0.0 to 1.0)"},"goal_id":{"type":"string","format":"uuid","description":"Goal that was predicted on"},"is_surprise":{"type":"boolean","description":"Whether this was a \"surprise\" (error > threshold)"},"predicted":{"type":"string","description":"Predicted outcome"}}},"PreferenceDto":{"type":"object","description":"A user preference.","required":["key","value","confidence","learned_from_count"],"properties":{"confidence":{"type":"number","format":"double","description":"Confidence level (0.0 to 1.0)."},"key":{"type":"string","description":"Preference key (e.g., \"preferred_view:employee\")."},"learned_from_count":{"type":"integer","format":"int64","description":"Number of events this preference was learned from."},"scope":{"type":["string","null"],"description":"Scope (e.g., sort name)."},"value":{"type":"string","description":"Preference value."}}},"PreferenceInput":{"type":"object","description":"A soft preference: bias the optimizer toward (or against) assigning\n`agent_id` to cell `(day, shift)`.\n\n`score` contributes to the objective when the cell is assigned in\nthe chosen schedule. Positive values pull the optimizer toward\nthe cell; negative values push it away. Preferences targeting a\npinned cell, an agent with a day-off on `day`, or an agent\notherwise blocked from the slot are silently ignored — the\ncorresponding decision edge does not exist in the reduced flow\ngraph.","required":["agent_id","day","shift","score"],"properties":{"agent_id":{"type":"string"},"day":{"type":"integer","minimum":0},"score":{"type":"integer","format":"int64","description":"Score contributed by this assignment to the optimizer's\nobjective. Positive = preferred, negative = avoided."},"shift":{"type":"integer","minimum":0}}},"PreferencePrediction":{"type":"object","description":"Prediction result for a single term","required":["term_id","score"],"properties":{"score":{"type":"number","format":"double"},"term_id":{"type":"string","format":"uuid"}}},"PrerequisiteInfoDto":{"type":"object","description":"Prerequisite info DTO","required":["concept_id","canonical_name","depth","path","below_threshold","evidence"],"properties":{"below_threshold":{"type":"boolean","description":"Whether value is below threshold (if both provided)"},"canonical_name":{"type":"string"},"concept_id":{"type":"string"},"depth":{"type":"integer","minimum":0},"evidence":{"$ref":"#/components/schemas/EvidenceSourceDto"},"path":{"type":"array","items":{"type":"string"}},"value":{"type":["number","null"],"format":"double","description":"Value from concept_values if provided"}}},"ProducedSampleDto":{"type":"object","description":"Produced-sample summary for REST.","required":["index","strategy_name","generated_text","mechanical_accepted","mechanical_violations","semantic_verdict","complexity_score","accepted"],"properties":{"accepted":{"type":"boolean","description":"Final pipeline decision."},"complexity_score":{"type":"number","format":"double","description":"Structural-complexity score for the sample."},"generated_text":{"type":"string","description":"Generated text from the LLM."},"index":{"type":"integer","description":"0-indexed position in `samples`.","minimum":0},"mechanical_accepted":{"type":"boolean","description":"Mechanical critic verdict (`accepted` + violation list)."},"mechanical_violations":{"type":"array","items":{"$ref":"#/components/schemas/CriticViolationDto"},"description":"Mechanical violations (kind + feature_path + reason)."},"semantic_verdict":{"type":"string","description":"Semantic critic verdict: `\"accept\" | \"reject\" | \"uncertain\" | \"skipped\"`."},"strategy_name":{"type":"string","description":"Strategy that generated the sample."}}},"ProofDto":{"type":"object","title":"ProofDto","description":"A proof tree node showing how a goal was proven. Contains goal_term_id, optional rule_term_id, subproofs (recursive), substitution, and certainty.","required":["goal_term_id","substitution","certainty"],"properties":{"certainty":{"type":"number"},"goal_term_id":{"type":"string","format":"uuid"},"rule_term_id":{"type":"string","format":"uuid"},"subproofs":{"type":"array","items":{"$ref":"#/components/schemas/ProofDto"},"description":"Child proof nodes (recursive)"},"substitution":{"$ref":"#/components/schemas/HomoiconicSubstitutionDto"}}},"ProofNodeDto":{"type":"object","description":"A node in the causal proof tree","required":["id","step_type","rule_name","explanation","children","depth"],"properties":{"certainty":{"type":["number","null"],"format":"double","description":"Certainty at this step"},"children":{"type":"array","items":{"type":"string"},"description":"Child node IDs"},"depth":{"type":"integer","description":"Depth in the proof tree","minimum":0},"explanation":{"type":"string","description":"Human-readable explanation"},"id":{"type":"string","description":"Unique identifier for this node"},"parent_id":{"type":["string","null"],"description":"Parent node ID (if any)"},"rule_name":{"type":"string","description":"Rule name or constraint that justified this step"},"step_type":{"type":"string","description":"Type of proof step"}}},"ProofStatisticsDto":{"type":"object","description":"Proof tree statistics","required":["total_nodes","rules_applied","max_depth"],"properties":{"duration_ms":{"type":["integer","null"],"format":"int64","description":"Duration in milliseconds","minimum":0},"max_depth":{"type":"integer","description":"Maximum depth reached","minimum":0},"rules_applied":{"type":"integer","description":"Number of rules applied","minimum":0},"total_nodes":{"type":"integer","description":"Total nodes in proof","minimum":0}}},"ProofTraceDto":{"type":"object","title":"ProofTraceDto","description":"A failed proof trace with causal chain. Explains WHY a constraint failed, the proof depth, and nested causes.","required":["goal_term_ids","failure_reason","failure_details","depth","suggestions"],"properties":{"depth":{"type":"integer","description":"Depth at which failure occurred in the proof tree"},"failure_details":{"type":"string","description":"Detailed reason description"},"failure_point":{"type":"string","description":"The specific term where failure occurred (if applicable)"},"failure_reason":{"type":"string","description":"Why the proof failed (human-readable classification)"},"goal_term_ids":{"type":"array","items":{"type":"string"},"description":"The goal terms that couldn't be proved"},"parent":{"$ref":"#/components/schemas/ProofTraceDto"},"suggestions":{"type":"array","items":{"$ref":"#/components/schemas/FixSuggestionDto"},"description":"Suggested fixes from the proof engine"}}},"ProofTraceNodeDto":{"type":"object","required":["id","node_type","label"],"properties":{"children":{"type":"array","items":{"$ref":"#/components/schemas/ProofTraceNodeDto"}},"confidence":{"type":"number"},"detail":{"type":"string"},"id":{"type":"string"},"label":{"type":"string"},"node_type":{"type":"string"},"rule":{"type":"string"}}},"ProposedFactorDto":{"type":"object","description":"A proposed factor of variation.","required":["name","description"],"properties":{"description":{"type":"string","description":"One-sentence description."},"name":{"type":"string","description":"Factor name (snake_case, becomes a candidate sort local name)."}}},"ProvenanceDto":{"type":"object","description":"A single provenance entry mapping a citation to a source fact.","required":["source_fact_id","description","location"],"properties":{"description":{"type":"string","description":"Human-readable description of the source."},"location":{"type":"string","description":"Location in the generated text (e.g., \"chars:42-46\")."},"source_fact_id":{"type":"string","format":"uuid","description":"The source fact ID."}}},"ProvenanceTagDto":{"type":"object","description":"Provenance tag for a derived fact from tagged forward chaining.\nMaps a derived fact (by index) to its probabilistic confidence score.","required":["fact_index","confidence"],"properties":{"confidence":{"type":"number","format":"double","description":"Confidence score from the probabilistic provenance semiring [0.0, 1.0].\nComputed via noisy-OR accumulation of rule certainties."},"fact_index":{"type":"integer","description":"Index into the `derived_facts` array in `ForwardChainResponse`.","minimum":0}}},"ProvideFeedbackRequest":{"type":"object","description":"Request to provide feedback on agent results.\n\nThis enables user corrections and preferences to be learned by the agent.\nAll feedback is stored as Ψ-terms for full homoiconicity.","required":["tenant_id","agent_id","result_id","rating"],"properties":{"agent_id":{"type":"string","format":"uuid","description":"Agent ID"},"correction":{"type":["string","null"],"description":"Optional: User's correction (natural language - will be converted to Ψ-term)"},"preference":{"type":["string","null"],"description":"Optional: User preference expressed (natural language - will be converted to Ψ-term)"},"rating":{"type":"integer","format":"int32","description":"Rating: -1 (wrong), 0 (neutral), +1 (correct/helpful)"},"result_id":{"type":"string","format":"uuid","description":"The result/goal being rated"},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"}}},"ProvideFeedbackResponse":{"type":"object","description":"Response after providing feedback.","required":["feedback_id","updated_rules","message"],"properties":{"feedback_id":{"type":"string","format":"uuid","description":"Created feedback Ψ-term ID"},"learned_rule_id":{"type":["string","null"],"format":"uuid","description":"Any new rule learned from correction"},"message":{"type":"string","description":"Message"},"updated_rules":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Rules whose utility was updated"}}},"PsiTermDto":{"type":"object","description":"Universal Ψ-term representation for API responses.\n\nThis is the ONLY type used for term responses in a truly homoiconic API.\nThe `sort_name` field indicates what kind of term this is:\n\n- `\"goal\"` - A query goal with `clauses` feature\n- `\"clause\"` - A logical clause with `constraints` and optional `when`\n- `\"constraint.*\"` - Various constraint types (sort, feature, equality, etc.)\n- `\"variable\"` - A logic variable with optional `_name`\n- Any domain sort (person, document, etc.)","required":["term_id","sort_id","sort_name","features","display"],"properties":{"display":{"type":"string","description":"Human-readable display string"},"features":{"type":"object","description":"Features map - structure depends on sort\n\nCommon patterns:\n- goal: `{clauses: [Uuid], min_degree?: f64}`\n- clause: `{constraints: [Uuid], when?: [Uuid], certainty?: f64}`\n- constraint.sort: `{var: Uuid, sort_id: Uuid}`\n- variable: `{_name?: String}`","additionalProperties":{"$ref":"#/components/schemas/FeatureValueDto"},"propertyNames":{"type":"string"}},"sort_id":{"type":"string","format":"uuid","description":"Sort ID (for programmatic use)"},"sort_name":{"type":"string","description":"Sort name (human-readable, e.g., \"person\", \"goal\", \"clause\")"},"term_id":{"type":"string","format":"uuid","description":"Unique identifier for this term"}}},"PushGoalRequest":{"type":"object","description":"Request to push a goal onto the stack","required":["goal"],"properties":{"goal":{"$ref":"#/components/schemas/ExecutionGoalDto","description":"Goal to push (discriminated by 'type' field)"}}},"PushGoalResponse":{"type":"object","description":"Response after pushing a goal","required":["stack_size","goal_id"],"properties":{"goal_id":{"type":"integer","minimum":0},"stack_size":{"type":"integer","minimum":0}}},"QueryByCollectionPathRequest":{"type":"object","description":"Request to query terms by collection path pattern","required":["namespace_id","path_prefix","include_descendants"],"properties":{"include_descendants":{"type":"boolean","description":"Whether to include terms from descendant collections"},"namespace_id":{"type":"string","format":"uuid","description":"Namespace ID"},"path_prefix":{"type":"string","description":"Path prefix to match (e.g., \"/projects/alpha\")"}}},"QueryInCollectionRequest":{"type":"object","description":"Request to query terms in a collection","required":["namespace_id","collection_id","include_descendants"],"properties":{"collection_id":{"type":"string","format":"uuid","description":"Collection ID to query"},"include_descendants":{"type":"boolean","description":"Whether to include terms from descendant collections"},"namespace_id":{"type":"string","format":"uuid","description":"Namespace ID"}}},"QueryResultDto":{"type":"object","description":"Query result after intervention","required":["values","certainties"],"properties":{"certainties":{"type":"array","items":{"type":"number","format":"double"},"description":"Associated probabilities/certainties"},"values":{"type":"array","items":{},"description":"Possible values for the query variable"}}},"QueryTemplateDto":{"type":"object","description":"A query template stored as a ψ-term.","required":["id","sort_name","intent","osfql_pattern","usage_count","is_user_created"],"properties":{"description":{"type":["string","null"],"description":"Optional user-provided description."},"id":{"type":"string","description":"Template ID (TermId UUID)."},"intent":{"type":"string","description":"Intent type (query, create, etc.)."},"is_user_created":{"type":"boolean","description":"Whether the user created this template manually."},"last_used":{"type":["string","null"],"description":"RFC3339 timestamp of last use."},"osfql_pattern":{"type":"string","description":"The OSFQL pattern."},"sort_name":{"type":"string","description":"Primary sort queried."},"usage_count":{"type":"integer","format":"int32","description":"How many times this pattern was reused.","minimum":0}}},"QueryTerm":{"oneOf":[{"type":"object","description":"Use existing term by ID","required":["term_id","type"],"properties":{"term_id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["by_id"]}}},{"type":"object","description":"Provide term inline","required":["sort_id","features","type"],"properties":{"features":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ValueDto"},"propertyNames":{"type":"string"}},"sort_id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["inline"]}}}],"description":"Query term specification"},"QueueMetricsResponse":{"type":"object","description":"Queue metrics response","required":["queue_depth","documents","circuit_breaker_state","worker_count"],"properties":{"active_workers":{"type":["integer","null"],"format":"int32","description":"Number of workers currently processing a task","minimum":0},"avg_wait_time_ms":{"type":["integer","null"],"format":"int64","description":"Average time a task waited in queue before dequeue (ms)","minimum":0},"circuit_breaker_state":{"type":"string","description":"Circuit breaker state for LLM ingestion"},"documents":{"$ref":"#/components/schemas/DocumentStatusCounts","description":"Document counts by status"},"estimated_queue_time_ms":{"type":["integer","null"],"format":"int64","description":"Estimated time to drain the current queue (ms)","minimum":0},"max_wait_time_ms":{"type":["integer","null"],"format":"int64","description":"Maximum wait time observed in current window (ms)","minimum":0},"queue_depth":{"type":"integer","description":"Number of tasks waiting in the queue channel","minimum":0},"throughput_per_minute":{"type":["number","null"],"format":"double","description":"Tasks completed per minute (throughput)"},"worker_count":{"type":"integer","format":"int32","description":"Number of configured workers","minimum":0},"worker_utilization_pct":{"type":["number","null"],"format":"float","description":"Worker utilization percentage (0.0 - 100.0)"}}},"RdfFormatDto":{"type":"string","description":"RDF format DTO","enum":["turtle","n_triples","rdf_xml","json_ld"]},"ReExtractRequest":{"type":"object","description":"Request to re-extract entities from a document","required":["document_id","tenant_id"],"properties":{"document_id":{"type":"string","description":"Document ID to re-extract from"},"extraction_strategy":{"type":["string","null"],"description":"Use different extraction strategy"},"focus_sorts":{"type":["array","null"],"items":{"type":"string"},"description":"Focus on specific sorts"},"instructions":{"type":["string","null"],"description":"Specific prompt/instructions for extraction"},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"}}},"ReExtractResponse":{"type":"object","description":"Response from re-extraction","required":["entities_extracted","entities_changed","pending_review_count"],"properties":{"entities_changed":{"type":"integer","description":"Number of entities that differ from previous extraction","minimum":0},"entities_extracted":{"type":"integer","description":"Number of new entities extracted","minimum":0},"pending_review_count":{"type":"integer","description":"New pending review items created","minimum":0}}},"RecallEpisodesRequest":{"type":"object","description":"Request to recall similar episodes.","required":["tenant_id","agent_id","goal_id"],"properties":{"agent_id":{"type":"string","format":"uuid","description":"Agent ID"},"context":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Context for similarity matching"},"goal_id":{"type":"string","format":"uuid","description":"Goal to find similar episodes for"},"max_results":{"type":"integer","description":"Maximum number of episodes to return","default":10,"minimum":0},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"}}},"RecallEpisodesResponse":{"type":"object","description":"Response with recalled episodes.","required":["episodes","count"],"properties":{"count":{"type":"integer","description":"Count","minimum":0},"episodes":{"type":"array","items":{"$ref":"#/components/schemas/RecalledEpisodeDto"},"description":"Episodes (sorted by similarity/recency)"}}},"RecalledEpisodeDto":{"type":"object","description":"An episode from memory with full details for recall.","required":["episode_id","goal_id","context","actions","outcome","reward","timestamp"],"properties":{"actions":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Actions taken"},"context":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Context"},"episode_id":{"type":"string","format":"uuid","description":"Episode ID"},"goal_id":{"type":"string","format":"uuid","description":"Goal"},"outcome":{"$ref":"#/components/schemas/EpisodeOutcomeDto","description":"Outcome"},"reward":{"type":"number","format":"double","description":"Reward"},"similarity":{"type":["number","null"],"format":"double","description":"Similarity score (if from recall_similar)"},"timestamp":{"type":"integer","format":"int64","description":"Timestamp"}}},"RecordEpisodeRequest":{"type":"object","description":"Request to record an episode.","required":["tenant_id","agent_id","goal_id","actions","outcome","reward"],"properties":{"actions":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Actions taken"},"agent_id":{"type":"string","format":"uuid","description":"Agent ID"},"context":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Context term IDs"},"goal_id":{"type":"string","format":"uuid","description":"Goal that was pursued"},"outcome":{"$ref":"#/components/schemas/EpisodeOutcomeDto","description":"Outcome (success/failure/partial)"},"reward":{"type":"number","format":"double","description":"Reward value"},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"}}},"RecordEpisodeResponse":{"type":"object","description":"Response after recording an episode.","required":["episode_id","message"],"properties":{"episode_id":{"type":"string","format":"uuid","description":"Created episode ID"},"message":{"type":"string","description":"Message"}}},"RecordSelectionRequest":{"type":"object","description":"Request to record a user selection","required":["user_id","term_id"],"properties":{"term_id":{"type":"string","format":"uuid"},"user_id":{"type":"string","format":"uuid"}}},"RecordSelectionResponse":{"type":"object","description":"Response after recording a selection","required":["success","selection_count"],"properties":{"selection_count":{"type":"integer","minimum":0},"success":{"type":"boolean"}}},"RecoverStuckRequest":{"type":"object","description":"Request to recover stuck documents","properties":{"orphan_timeout_secs":{"type":"integer","format":"int64","description":"Timeout in seconds — documents in InProgress longer than this are considered stuck.\nDefaults to 300 (5 minutes) if not specified. Minimum: 60 seconds.","minimum":0}}},"RecoverStuckResponse":{"type":"object","description":"Response from recovering stuck documents","required":["recovered_count","document_ids"],"properties":{"document_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"recovered_count":{"type":"integer","minimum":0}}},"ReferencedTermSummary":{"type":"object","description":"Summary of a referenced term — display annotation for the API layer.\nThis is NOT part of the homoiconic ψ-term structure; it's a projection\nlike pretty-printing `person(employer => company(name => \"TechCorp\"))`\ninstead of `person(employer => #x3fa8)`.","required":["display_name","sort_name"],"properties":{"display_name":{"type":"string","description":"Human-readable display name extracted from the referenced term's features"},"sort_name":{"type":"string","description":"Sort name of the referenced term"}}},"ReflectionQueryRequest":{"type":"object","description":"Request for reflection query - query the agent's own rules.","required":["agent_id","tenant_id","query"],"properties":{"agent_id":{"type":"string","format":"uuid","description":"Agent ID"},"query":{"type":"string","description":"Query: what to reflect on (e.g., \"rules_with_certainty_above(0.8, ?R)\")"},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"}}},"ReflectionQueryResponse":{"type":"object","description":"Response from reflection query.","required":["count","matches","message"],"properties":{"count":{"type":"integer","description":"Number of matching rules/facts","minimum":0},"matches":{"type":"array","items":{"$ref":"#/components/schemas/JsonValue"},"description":"Matching items (raw JSON)"},"message":{"type":"string","description":"Message"}}},"RefuteRequestDto":{"type":"object","description":"Request to refute an implication with a counterexample.\n\nPOST /api/v1/analysis/attribute-exploration/{session_id}/refute","required":["label","features"],"properties":{"features":{"type":"array","items":{"type":"string"},"description":"Feature names that the counterexample possesses"},"label":{"type":"string","description":"Label for the counterexample object (e.g., entity name)"}}},"RefuteResponseDto":{"type":"object","description":"Response after refuting an implication.","required":["progress"],"properties":{"next_question":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ExplorationQuestionDto","description":"Next question (None if exploration is complete)"}]},"progress":{"$ref":"#/components/schemas/ExplorationProgressDto","description":"Current exploration progress"}}},"RegisterExternalActionRequest":{"type":"object","description":"Request to register a new external action type.\n\nThis creates a new sort in the hierarchy inheriting from `effect`,\nwith features for all inputs and outputs.","required":["name","tenant_id","webhook_url"],"properties":{"description":{"type":["string","null"],"description":"Description of what this action does"},"name":{"type":"string","description":"Unique name for this action (becomes the sort name)"},"optional_inputs":{"type":"object","description":"Optional input features with default values","additionalProperties":{},"propertyNames":{"type":"string"}},"outputs":{"type":"array","items":{"type":"string"},"description":"Output feature names (bound after callback)"},"required_inputs":{"type":"array","items":{"type":"string"},"description":"Required input feature names"},"tenant_id":{"type":"string","format":"uuid","description":"Tenant that owns this action"},"timeout_secs":{"type":["integer","null"],"format":"int64","description":"Timeout in seconds (default: 3600)","minimum":0},"webhook_secret":{"type":["string","null"],"description":"Secret for HMAC signature verification"},"webhook_url":{"type":"string","description":"URL to call when action is invoked"}}},"RegisterExternalActionResponse":{"type":"object","description":"Response after registering an external action.","required":["action_id","sort_id","name","message"],"properties":{"action_id":{"type":"string","description":"The generated action ID"},"message":{"type":"string","description":"Confirmation message"},"name":{"type":"string","description":"The action name"},"sort_id":{"type":"string","format":"uuid","description":"The sort ID created for this action"}}},"RegisterFunctionRequest":{"type":"object","description":"Request to register a user-defined function","required":["tenant_id","name","arity","clauses"],"properties":{"arity":{"type":"integer","minimum":0},"clauses":{"type":"array","items":{"$ref":"#/components/schemas/FunctionClauseDto"}},"name":{"type":"string"},"tenant_id":{"type":"string","format":"uuid"}}},"RegisterFunctionResponse":{"type":"object","description":"Response from function registration","required":["function_id","name","arity","clauses_count"],"properties":{"arity":{"type":"integer","minimum":0},"clauses_count":{"type":"integer","minimum":0},"function_id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"RegisterSourceRequest":{"type":"object","description":"Request to register a data source.\n\nRegisters a connector with the ingestion service so it can be used for\nschema discovery and data ingestion.","required":["source_id","source_name","source_type","config"],"properties":{"config":{"description":"Source-specific configuration (varies by source_type).\n\nExamples:\n- CSV: `{\"file_path\": \"/data/drugs.csv\", \"has_header\": true, \"delimiter\": \",\"}`\n- MySQL: `{\"connection_url\": \"mysql://user:pass@host/db\", \"schema\": \"public\"}`\n- MCP: `{\"transport\": {\"type\": \"stdio\", \"command\": \"npx\", \"args\": [\"-y\", \"@mcp/server\"]}}`"},"source_id":{"type":"string","description":"Unique source identifier (e.g., \"crm_postgres\", \"drug_csv\")"},"source_name":{"type":"string","description":"Human-readable source name (e.g., \"CRM PostgreSQL Database\")"},"source_type":{"type":"string","description":"Source type: \"csv\", \"parquet\", \"mysql\", \"sqlite\", \"cassandra\", \"neo4j\",\n\"mcp\", \"rest\", \"graphql\", \"postgres\""}}},"RegisterSourceResponse":{"type":"object","description":"Response from source registration.","required":["success","source_id","source_type","message"],"properties":{"message":{"type":"string","description":"Status message"},"source_id":{"type":"string","description":"The registered source ID"},"source_type":{"type":"string","description":"Source type"},"success":{"type":"boolean","description":"Whether registration was successful"}}},"RejectActionRequest":{"type":"object","description":"Request to reject an action","required":["review_id","reason"],"properties":{"reason":{"type":"string","description":"Reason for rejection (required)"},"review_id":{"type":"string","format":"uuid","description":"The review ID to reject"}}},"RejectEntityRequest":{"type":"object","description":"Request to reject an entity","required":["review_id","reason"],"properties":{"reason":{"type":"string","description":"Reason for rejection (required)"},"review_id":{"type":"string","format":"uuid","description":"The review ID to reject"}}},"RejectLearnedSimilarityRequest":{"type":"object","description":"Request to reject a learned similarity","required":["sort1_id","sort2_id","reason"],"properties":{"reason":{"type":"string","description":"Reason for rejection"},"sort1_id":{"type":"string","format":"uuid","description":"ID of the first sort"},"sort2_id":{"type":"string","format":"uuid","description":"ID of the second sort"}}},"RejectLearnedSimilarityResponse":{"type":"object","description":"Response for reject operation","required":["success","message"],"properties":{"message":{"type":"string"},"success":{"type":"boolean"}}},"RelOpDto":{"type":"string","description":"DTO for relational operators","enum":["equal","not_equal","less_than","less_than_or_equal","greater_than","greater_than_or_equal"]},"RelatedInfoDto":{"type":"object","description":"Related info DTO","required":["concept_id","canonical_name","relation_type","degree","evidence"],"properties":{"canonical_name":{"type":"string"},"concept_id":{"type":"string"},"degree":{"type":"number","format":"double"},"evidence":{"$ref":"#/components/schemas/EvidenceSourceDto"},"relation_type":{"$ref":"#/components/schemas/RelationTypeDto"}}},"RelationTypeDto":{"oneOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["Explicit"]}}},{"type":"object","required":["unified_features","type"],"properties":{"type":{"type":"string","enum":["Emergent"]},"unified_features":{"type":"array","items":{"type":"string"}}}}],"description":"Relation type DTO"},"RelationalArithRequest":{"type":"object","description":"Request for 3-way arithmetic operations (mult, div, add, sub)","required":["session_id"],"properties":{"arg1":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ArithValueDto","description":"First argument (optional - can be uninstantiated)"}]},"arg2":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ArithValueDto","description":"Second argument (optional - can be uninstantiated)"}]},"arg3":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ArithValueDto","description":"Third argument (optional - can be uninstantiated)"}]},"session_id":{"type":"string"}}},"RelationalArithResponse":{"oneOf":[{"type":"object","description":"Operation succeeded with a result","required":["result","computed_arg","status"],"properties":{"computed_arg":{"type":"integer","description":"Which argument was computed (1, 2, or 3)","minimum":0},"result":{"$ref":"#/components/schemas/ArithValueDto"},"status":{"type":"string","enum":["success"]}}},{"type":"object","description":"Need to residuate on one term","required":["term_id","status"],"properties":{"status":{"type":"string","enum":["residuate1"]},"term_id":{"type":"string"}}},{"type":"object","description":"Need to residuate on two terms","required":["term1_id","term2_id","status"],"properties":{"status":{"type":"string","enum":["residuate2"]},"term1_id":{"type":"string"},"term2_id":{"type":"string"}}},{"type":"object","description":"Need to residuate on three terms","required":["term1_id","term2_id","term3_id","status"],"properties":{"status":{"type":"string","enum":["residuate3"]},"term1_id":{"type":"string"},"term2_id":{"type":"string"},"term3_id":{"type":"string"}}},{"type":"object","description":"Operation would require currying","required":["missing_count","status"],"properties":{"missing_count":{"type":"integer","minimum":0},"status":{"type":"string","enum":["curry"]}}},{"type":"object","description":"Operation failed (constraint violation)","required":["reason","status"],"properties":{"reason":{"type":"string"},"status":{"type":"string","enum":["fail"]}}}],"description":"Response from relational arithmetic operation"},"ReleaseResiduationsRequest":{"type":"object","description":"Request to release residuations for a term","required":["session_id","term_id"],"properties":{"session_id":{"type":"string"},"term_id":{"type":"string"}}},"ReleaseResiduationsResponse":{"type":"object","description":"Response with released goals","required":["released_count","released_goals","evaluation_results","remaining_suspended"],"properties":{"evaluation_results":{"type":"array","items":{"$ref":"#/components/schemas/GoalEvaluationResultDto"},"description":"Evaluation results for goals that could be evaluated"},"released_count":{"type":"integer","minimum":0},"released_goals":{"type":"array","items":{"$ref":"#/components/schemas/ResiduationGoalDto"}},"remaining_suspended":{"type":"integer","minimum":0}}},"ReprocessFailedRequest":{"type":"object","description":"Request to reprocess failed documents","properties":{"max_documents":{"type":"integer","description":"Maximum number of documents to reprocess.\nDefaults to 100 if not specified.","minimum":0},"session_id":{"type":["string","null"],"format":"uuid","description":"Optional session ID to scope reprocessing to a specific session.\nIf not specified, reprocesses failed documents across all sessions."}}},"ReprocessFailedResponse":{"type":"object","description":"Response from reprocessing failed documents","required":["requeued_count","document_ids"],"properties":{"document_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"requeued_count":{"type":"integer","minimum":0}}},"ResidualWitnessDto":{"type":"object","description":"Residuated witness waiting for information","required":["witness_id","trigger","partial_bindings"],"properties":{"partial_bindings":{"type":"object","description":"Partial bindings found so far","additionalProperties":{"type":"string"},"propertyNames":{"type":"string"}},"trigger":{"type":"string","description":"What would trigger re-evaluation"},"witness_id":{"type":"string","description":"ID of the witness that couldn't be satisfied yet"}}},"ResiduateGoalRequest":{"type":"object","description":"Request to residuate a goal on a variable","required":["session_id","goal","term_id"],"properties":{"best_sort":{"type":["string","null"]},"best_value":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ExecutionValueDto"}]},"goal":{"$ref":"#/components/schemas/ResiduationGoalDto"},"session_id":{"type":"string"},"term_id":{"type":"string"}}},"ResiduatedEntry":{"type":"object","description":"A single residuated entry: an antecedent sort that is needed but\nnot yet present in the available evidence.","required":["feature_name","needed_by","rule_count","info_gain","wake_trigger"],"properties":{"feature_name":{"type":"string","description":"The sort name that is missing"},"info_gain":{"type":"number","format":"double","description":"Information gain: `rule_count / total_rules` for the goal"},"needed_by":{"type":"array","items":{"type":"string"},"description":"Rule head names (from the \"name\" feature) that need this sort"},"rule_count":{"type":"integer","description":"Number of rules that require this sort (proxy for information gain)","minimum":0},"wake_trigger":{"type":"string","description":"What would resolve this: \"Provide a fact with sort <name>\""}}},"ResiduatedTermDto":{"type":"object","description":"A residuated term","required":["id","term_id","kind","state","waiting_for","created_at"],"properties":{"created_at":{"type":"integer","format":"int64","description":"Creation timestamp (ms since epoch)"},"description":{"type":["string","null"],"description":"Optional description"},"id":{"type":"string","description":"Residuation ID"},"kind":{"$ref":"#/components/schemas/ResiduationKind","description":"Kind of residuation"},"state":{"$ref":"#/components/schemas/ResiduationStateDto","description":"Current state"},"term_id":{"type":"string","format":"uuid","description":"Term ID being waited on"},"waiting_for":{"type":"array","items":{"$ref":"#/components/schemas/WaitingConditionDto"},"description":"What this residuation is waiting for"}}},"ResiduationDetailDto":{"type":"object","description":"Detailed residuation info","required":["id","goal","is_pending"],"properties":{"best_sort":{"type":["string","null"]},"best_value":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ExecutionValueDto"}]},"goal":{"$ref":"#/components/schemas/ResiduationGoalDto"},"id":{"type":"string"},"is_pending":{"type":"boolean"}}},"ResiduationDto":{"type":"object","description":"A residuation (witness that couldn't be satisfied yet)","required":["witness_id","trigger","partial_bindings"],"properties":{"partial_bindings":{"type":"object","description":"Partial bindings found so far","additionalProperties":{"type":"string"},"propertyNames":{"type":"string"}},"trigger":{"type":"string","description":"What would trigger re-evaluation"},"witness_id":{"type":"string","description":"ID of the witness that residuated"}}},"ResiduationGoalDto":{"type":"object","description":"A goal to residuate","required":["operation_type"],"properties":{"arguments":{"type":"array","items":{"type":"string"}},"operation_type":{"type":"string"},"result_target":{"type":["string","null"]}}},"ResiduationKind":{"type":"string","description":"Kind of residuation to visualize","enum":["inference","fuzzy","extraction","all"]},"ResiduationRequest":{"type":"object","description":"Request for residuation check","required":["term_id"],"properties":{"term_id":{"type":"string","format":"uuid","description":"Term ID to check for suspended operations"}}},"ResiduationResponse":{"type":"object","description":"Response from residuation check","required":["suspended_operations","resumption_triggers","computation_time_ms"],"properties":{"computation_time_ms":{"type":"integer","format":"int64","description":"Computation time in milliseconds","minimum":0},"resumption_triggers":{"type":"array","items":{"type":"string"},"description":"Resumption triggers"},"suspended_operations":{"type":"array","items":{"type":"string"},"description":"List of suspended operations"}}},"ResiduationStateDto":{"type":"string","description":"Residuation state","enum":["pending","suspended","ready","completed","failed"]},"ResiduationStateFilter":{"type":"string","description":"State filter for residuation visualization","enum":["pending","suspended","ready","completed","all"]},"ResiduationStateRequest":{"type":"object","description":"Request for residuation state diagram","properties":{"generate_dot":{"type":"boolean","description":"Whether to generate DOT output"},"include_dependencies":{"type":"boolean","description":"Whether to include trigger dependencies"},"kind":{"$ref":"#/components/schemas/ResiduationKind","description":"Kind of residuation to visualize"},"state":{"$ref":"#/components/schemas/ResiduationStateFilter","description":"State filter"}}},"ResiduationStateResponse":{"type":"object","description":"Response for residuation state diagram","required":["residuated_terms","dependency_nodes","dependency_edges","stats"],"properties":{"dependency_edges":{"type":"array","items":{"$ref":"#/components/schemas/GraphEdgeDto"},"description":"Dependency edges (for graph visualization)"},"dependency_nodes":{"type":"array","items":{"$ref":"#/components/schemas/GraphNodeDto"},"description":"Dependency nodes (for graph visualization)"},"graph":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/VisualizationGraphDto","description":"The visualization graph"}]},"residuated_terms":{"type":"array","items":{"$ref":"#/components/schemas/ResiduatedTermDto"},"description":"Residuated terms"},"stats":{"$ref":"#/components/schemas/ResiduationStats","description":"Statistics"}}},"ResiduationStats":{"type":"object","description":"Statistics about residuation state","required":["total","pending","suspended","ready","completed","failed"],"properties":{"completed":{"type":"integer","description":"Completed count","minimum":0},"failed":{"type":"integer","description":"Failed count","minimum":0},"pending":{"type":"integer","description":"Pending count","minimum":0},"ready":{"type":"integer","description":"Ready count","minimum":0},"suspended":{"type":"integer","description":"Suspended count","minimum":0},"total":{"type":"integer","description":"Total residuations","minimum":0}}},"ResolveSymbolRequest":{"type":"object","description":"Request to resolve a qualified name","required":["session_id","qualified_name"],"properties":{"qualified_name":{"type":"string","description":"Qualified name (e.g., \"module#symbol\" or just \"symbol\")"},"session_id":{"type":"string"}}},"ResolveSymbolResponse":{"oneOf":[{"type":"object","required":["module_name","symbol","status"],"properties":{"module_name":{"type":"string"},"status":{"type":"string","enum":["found"]},"symbol":{"$ref":"#/components/schemas/SymbolDto"}}},{"type":"object","required":["reason","status"],"properties":{"reason":{"type":"string"},"status":{"type":"string","enum":["not_found"]}}},{"type":"object","required":["module_name","symbol_name","status"],"properties":{"module_name":{"type":"string"},"status":{"type":"string","enum":["not_visible"]},"symbol_name":{"type":"string"}}}],"description":"Response from symbol resolution"},"ResourceCoordinationRequest":{"type":"object","description":"Request for N-way resource coordination planning\n\nThis is a GENERIC system that works for coordinating ANY number of resources:\n- 2-way: Meals + Wines\n- 3-way: Meals + Wines + Desserts\n- 4-way: Tasks + Tools + Locations + TimeSlots\n- N-way: Any combination of complementary resources\n\nExample (Meal + Wine pairing):\n```json\n{\n \"tenant_id\": \"...\",\n \"resources\": [\n {\n \"sort_id\": \"recipe-sort\",\n \"match_field\": \"category\",\n \"fuzzy_query\": {\n \"features\": {\n \"vegan\": {\"type\": \"Real\", \"value\": 0.9},\n \"protein\": {\"type\": \"Real\", \"value\": 25.0}\n }\n }\n },\n {\n \"sort_id\": \"wine-sort\",\n \"match_field\": \"pairs_with\",\n \"fuzzy_query\": {\n \"features\": {\n \"price_max\": {\"type\": \"Real\", \"value\": 50.0}\n }\n }\n }\n ],\n \"num_selections\": 7,\n \"compatibility_threshold\": 0.6\n}\n```","required":["resources","num_selections"],"properties":{"compatibility_threshold":{"type":["number","null"],"format":"double","description":"Minimum compatibility score threshold (0.0-1.0, default: 0.0)"},"num_selections":{"type":"integer","description":"Number of coordinated sets to create","minimum":0},"resources":{"type":"array","items":{"$ref":"#/components/schemas/ResourceSpec"},"description":"List of resource types to coordinate (must have at least 2)"}}},"ResourceCoordinationResponse":{"type":"object","description":"Response from N-way resource coordination planning","required":["coordinated_sets","avg_compatibility","candidates_per_resource","computation_time_ms"],"properties":{"avg_compatibility":{"type":"number","format":"double","description":"Average compatibility score across all sets"},"candidates_per_resource":{"type":"array","items":{"type":"integer","minimum":0},"description":"Number of candidates evaluated per resource type"},"computation_time_ms":{"type":"integer","format":"int64","description":"Computation time in milliseconds","minimum":0},"coordinated_sets":{"type":"array","items":{"$ref":"#/components/schemas/CoordinatedResourceSet"},"description":"List of coordinated resource sets"}}},"ResourceSpec":{"type":"object","description":"Resource specification for N-way coordination","required":["sort_id","match_field"],"properties":{"fuzzy_query":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/QueryTerm","description":"Optional fuzzy query to pre-filter candidates for this resource"}]},"match_field":{"type":"string","description":"Field name in this resource used for matching"},"min_degree":{"type":["number","null"],"format":"double","description":"Minimum similarity degree for fuzzy filtering (default: 0.0)"},"sort_id":{"type":"string","format":"uuid","description":"Sort ID for this resource type"}}},"ResumeDocumentIngestionRequest":{"type":"object","description":"Request to resume ingestion of a document","required":["document_id","content","owner_id"],"properties":{"config":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/IngestionConfigDto","description":"Optional configuration overrides"}]},"content":{"type":"string","description":"Content of the document (must match original hash)"},"document_id":{"type":"string","description":"Document ID to resume"},"owner_id":{"type":"string","format":"uuid","description":"Owner ID"}}},"ResumeDocumentIngestionResponse":{"type":"object","description":"Response from resuming document ingestion","required":["success","session_id","document_id","resumed_from_chunk","stats"],"properties":{"document_id":{"type":"string","description":"Document ID"},"error":{"type":["string","null"],"description":"Error message if resume failed"},"pending_review":{"type":"array","items":{"$ref":"#/components/schemas/PendingReviewDto"},"description":"Entities pending human review"},"resumed_from_chunk":{"type":"integer","description":"Chunk that was resumed from","minimum":0},"session_id":{"type":"string","format":"uuid","description":"Session ID"},"stats":{"$ref":"#/components/schemas/IngestionStatsDto","description":"Ingestion statistics"},"success":{"type":"boolean","description":"Whether the resume was successful"}}},"ResumptionOptionDto":{"type":"object","description":"A suggested way to refine the query","required":["id","description","expected_confidence_gain"],"properties":{"description":{"type":"string","description":"Human-readable description"},"expected_confidence_gain":{"type":"number","format":"double","description":"Expected confidence improvement"},"id":{"type":"string","description":"Unique identifier for this option"}}},"RetractRuleRequest":{"type":"object","description":"Request to retract a rule","properties":{"pattern":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/RuleClauseDto","description":"If provided, retract rules matching this pattern"}]},"retract_all":{"type":"boolean","description":"If true, retract all matching; if false, retract first match only"},"rule_id":{"type":["string","null"],"description":"If provided, retract by ID"}}},"RetractRuleResponse":{"type":"object","description":"Response after retracting","required":["retracted_count","retracted_ids","remaining_count"],"properties":{"remaining_count":{"type":"integer","minimum":0},"retracted_count":{"type":"integer","minimum":0},"retracted_ids":{"type":"array","items":{"type":"string"}}}},"RetrievalStatsDto":{"type":"object","description":"Retrieval statistics DTO","required":["search_ms","graph_traversal_ms","relation_scan_ms","assembly_ms","terms_searched","concepts_found","feature_relations_found","relation_terms_found"],"properties":{"assembly_ms":{"type":"integer","format":"int64","minimum":0},"concepts_found":{"type":"integer","minimum":0},"feature_relations_found":{"type":"integer","minimum":0},"graph_traversal_ms":{"type":"integer","format":"int64","minimum":0},"relation_scan_ms":{"type":"integer","format":"int64","minimum":0},"relation_terms_found":{"type":"integer","minimum":0},"search_ms":{"type":"integer","format":"int64","minimum":0},"terms_searched":{"type":"integer","minimum":0}}},"ReviewActionResponse":{"type":"object","description":"Response from a review action (approve, reject, merge, correct)","required":["success","status","message"],"properties":{"message":{"type":"string","description":"Message describing what happened"},"status":{"$ref":"#/components/schemas/ReviewStatus","description":"The final status of the entity"},"success":{"type":"boolean","description":"Whether the action succeeded"},"term_id":{"type":["string","null"],"format":"uuid","description":"Created term ID (if entity was approved/corrected)"}}},"ReviewCandidateMatchDto":{"type":"object","description":"A candidate term match for deduplication","required":["term_id","display_name","sort","similarity","features"],"properties":{"display_name":{"type":"string","description":"Display name for the candidate"},"features":{"type":"object","description":"Key features for comparison","additionalProperties":{},"propertyNames":{"type":"string"}},"similarity":{"type":"number","format":"double","description":"Similarity score (0.0 - 1.0)"},"sort":{"type":"string","description":"Sort name of the candidate"},"term_id":{"type":"string","format":"uuid","description":"Term ID of the candidate"}}},"ReviewReason":{"type":"string","description":"Reason why an entity requires review","enum":["ambiguous_sort","low_confidence","multiple_candidates","unknown_sort","conflicting_features","missing_required_features","manual_request"]},"ReviewStatus":{"type":"string","description":"Review status for an extracted entity","enum":["pending","approved","rejected","corrected","merged"]},"ReviewSummaryDto":{"type":"object","description":"Summary statistics for pending reviews","required":["total_pending","by_reason","by_sort","high_confidence_count","low_confidence_count"],"properties":{"by_reason":{"type":"object","description":"Breakdown by reason","additionalProperties":{"type":"integer","minimum":0},"propertyNames":{"type":"string"}},"by_sort":{"type":"object","description":"Breakdown by sort","additionalProperties":{"type":"integer","minimum":0},"propertyNames":{"type":"string"}},"high_confidence_count":{"type":"integer","description":"Entities with high confidence (>0.8)","minimum":0},"low_confidence_count":{"type":"integer","description":"Entities with low confidence (<0.5)","minimum":0},"total_pending":{"type":"integer","description":"Total pending reviews","minimum":0}}},"RlPolicyConfigDto":{"type":"object","description":"Optional RL policy configuration overrides.","properties":{"discount_factor":{"type":["number","null"],"format":"double","description":"Discount factor (gamma) for future rewards (default: 0.99)"},"exploration_decay":{"type":["number","null"],"format":"double","description":"Exploration decay per episode (default: 0.995)"},"exploration_rate":{"type":["number","null"],"format":"double","description":"Initial exploration rate (epsilon) (default: 1.0)"},"learning_rate":{"type":["number","null"],"format":"double","description":"Learning rate (alpha) for Q-value updates (default: 0.1)"},"min_exploration":{"type":["number","null"],"format":"double","description":"Minimum exploration rate (default: 0.01)"}}},"RlTrainRequest":{"type":"object","description":"Request to start an RL training run.\n\nSupports two modes:\n- Standalone: Uses `environment_orchestrator::run()` (RL only, no cognitive cycle)\n- Cognitive: Uses `rl_cognitive_bridge::run()` (unified cognitive-RL loop)","required":["tenant_id","environment_name","num_episodes"],"properties":{"conversation_config":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ConversationTrainingConfigDto","description":"Configuration for conversation-based training (when environment_name starts with \"conversation\")"}]},"curiosity_bonus_amount":{"type":"number","format":"double","description":"Curiosity bonus amount (default: 0.1)"},"enable_auto_curriculum":{"type":"boolean","description":"Enable auto-curriculum (Phase B, dynamic difficulty)"},"enable_cognitive_cycle":{"type":"boolean","description":"If true, uses the cognitive-RL bridge (unified loop).\nIf false, uses the standalone environment orchestrator (RL only)."},"enable_curiosity_bonus":{"type":"boolean","description":"Whether to add curiosity bonus to rewards (only used with cognitive cycle)"},"enable_deliberation_scaling":{"type":"boolean","description":"Enable deliberation scaling (Phase A, uncertainty-gated imagination)"},"enable_expert_gating":{"type":"boolean","description":"Enable MoE dynamic expert gating (Phase F).\nWhen true, subsystem learning rates are dynamically routed via learned gating weights."},"enable_imagination_learning":{"type":"boolean","description":"Enable imagination learning (requires world model)"},"enable_neural_dqn":{"type":"boolean","description":"Enable neural DQN mode (creates CandleNeuralQAdapter)"},"enable_ontological_grounding":{"type":"boolean","description":"Enable ontological grounding loop"},"enable_plasticity_schedule":{"type":"boolean","description":"Enable plasticity schedule (Phase C, differential learning rates per developmental phase)"},"enable_self_play":{"type":"boolean","description":"Enable multi-agent self-play training (Phase E).\nWhen true, runs multiple agents in parallel, sharing trajectories."},"enable_state_encoder":{"type":"boolean","description":"Enable contrastive state encoder (auto-enabled with DQN)"},"enable_world_model":{"type":"boolean","description":"Enable neural world model for imagination learning"},"encoding_dim":{"type":"integer","description":"Encoding dimension for state encoder (default: 8)","minimum":0},"environment_name":{"type":"string","description":"Environment identifier (e.g., \"grid_world_5x5\", \"grid_world_10x10\")"},"expert_gate_entropy_coefficient":{"type":"number","format":"double","description":"Expert gating entropy regularization coefficient (default: 0.1)"},"expert_gate_learning_rate":{"type":"number","format":"double","description":"Expert gating learning rate (default: 0.01)"},"expert_gate_temperature":{"type":"number","format":"double","description":"Expert gating softmax temperature (default: 1.0)"},"hidden_dim":{"type":"integer","description":"Hidden dimension for neural networks (default: 32)","minimum":0},"max_steps_per_episode":{"type":"integer","description":"Maximum steps per episode (1..=10,000, default: 200)","minimum":0},"num_episodes":{"type":"integer","description":"Number of training episodes (1..=10,000)","minimum":0},"persist_weights":{"type":"boolean","description":"Enable saving/loading DQN weights for persistence across restarts.\nWhen true, weights are saved to a tenant-specific path after training\nand loaded before training starts (continuing from last checkpoint)."},"rl_config":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/RlPolicyConfigDto","description":"Optional RL policy configuration overrides"}]},"self_play_exchange_mode":{"type":"string","description":"Trajectory exchange mode: \"top_k\" | \"all_to_all\" | \"ring\""},"self_play_num_agents":{"type":"integer","description":"Number of agents in self-play population (default: 2, max: 10)","minimum":0},"self_play_num_rounds":{"type":"integer","description":"Number of self-play rounds (default: 5, max: 50)","minimum":0},"self_play_quality_threshold":{"type":"number","format":"double","description":"Quality threshold for shared trajectories [0.0, 1.0]"},"self_play_social_observation":{"type":"boolean","description":"Enable social observation (trajectory sharing between agents)"},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID for multi-tenant isolation"}}},"RlTrainResponse":{"type":"object","description":"Response from an RL training run.","required":["episodes_completed","episode_rewards","episode_steps","avg_reward_last_10","final_exploration_rate","total_transitions","cognitive_cycles_run"],"properties":{"avg_reward_last_10":{"type":"number","format":"double","description":"Average reward over the last 10 episodes (or all if fewer)"},"cognitive_cycles_run":{"type":"integer","description":"Total cognitive cycles run (0 if cognitive cycle disabled)","minimum":0},"collapse_episodes":{"type":"array","items":{"type":"integer","minimum":0},"description":"Episodes where representation collapse was detected"},"contrastive_losses":{"type":"array","items":{"type":"number","format":"float"},"description":"Contrastive losses from encoder training (empty if no encoder)"},"conversation_decisions":{"type":"object","description":"Conversation-specific metrics when training on conversation environment","additionalProperties":{"type":"integer","minimum":0},"propertyNames":{"type":"string"}},"curriculum_adjustments":{"type":"integer","description":"Auto-curriculum adjustments","minimum":0},"curriculum_backtracks":{"type":"integer","description":"Auto-curriculum backtracks","minimum":0},"curriculum_stage_reached":{"type":["integer","null"],"description":"Auto-curriculum stage reached (None if disabled)","minimum":0},"deliberative_decisions":{"type":"integer","description":"Number of deliberative decisions from deliberation scaling","minimum":0},"dynamics_losses":{"type":"array","items":{"type":"number","format":"float"},"description":"Dynamics losses from neural world model (empty if no world model)"},"episode_rewards":{"type":"array","items":{"type":"number","format":"double"},"description":"Reward per episode"},"episode_steps":{"type":"array","items":{"type":"integer","minimum":0},"description":"Steps per episode"},"episodes_completed":{"type":"integer","description":"Number of episodes completed","minimum":0},"expert_avg_entropy":{"type":"number","format":"double","description":"Average expert weight entropy (0.0 if disabled)"},"expert_avg_weights":{"type":"object","description":"Average expert weights (empty map if gating disabled)","additionalProperties":{"type":"number","format":"double"},"propertyNames":{"type":"string"}},"expert_collapse_recoveries":{"type":"integer","description":"Expert collapse recoveries count","minimum":0},"expert_final_weights":{"type":"object","description":"Final expert weights at end of training","additionalProperties":{"type":"number","format":"double"},"propertyNames":{"type":"string"}},"final_contrastive_temperature":{"type":"number","format":"float","description":"Final contrastive temperature after feedback adaptation"},"final_exploration_rate":{"type":"number","format":"double","description":"Final exploration rate after training"},"final_imagination_steps":{"type":"integer","description":"Final imagination steps after feedback adaptation","minimum":0},"imagination_transitions":{"type":"integer","description":"Imagined transitions from Dyna-Q (0 if disabled)","minimum":0},"mode_distribution":{"type":"object","description":"Mode distribution (how often each cognitive mode was selected)","additionalProperties":{"type":"integer","minimum":0},"propertyNames":{"type":"string"}},"peer_demonstrations_consumed":{"type":"integer","description":"Number of peer demonstrations consumed from self-play trajectory exchange","minimum":0},"plasticity_phase_transitions":{"type":"array","items":{"type":"array","items":false,"prefixItems":[{"type":"integer","minimum":0},{"type":"integer","minimum":0}]},"description":"Plasticity phase transitions observed (episode, phase)"},"reactive_decisions":{"type":"integer","description":"Number of reactive decisions from deliberation scaling","minimum":0},"self_play_agent_fitnesses":{"type":"array","items":{"type":"array","items":{"type":"number","format":"double"}},"description":"Agent fitness per round: outer vec = agents, inner vec = rounds"},"self_play_best_fitness":{"type":["number","null"],"format":"double","description":"Best agent fitness from self-play (None if self-play disabled)"},"self_play_mean_fitness_per_round":{"type":"array","items":{"type":"number","format":"double"},"description":"Mean fitness per self-play round (empty if disabled)"},"sort_aware_training_steps":{"type":"integer","description":"Number of sort-aware training steps performed","minimum":0},"sorts_discovered":{"type":"integer","description":"Sorts discovered by ontological grounding","minimum":0},"total_transitions":{"type":"integer","description":"Total transitions recorded across all episodes","minimum":0},"trajectories_exchanged":{"type":"integer","description":"Number of trajectories exchanged between agents in self-play","minimum":0}}},"RootCauseAnalysisRequest":{"type":"object","description":"Request for root cause analysis","required":["effect"],"properties":{"effect":{"type":"string","description":"The effect to analyze"},"max_depth":{"type":"integer","description":"Maximum depth to search","minimum":0}}},"RootCauseAnalysisResponse":{"type":"object","description":"Response with root cause analysis","required":["effect","root_causes","causal_chains"],"properties":{"causal_chains":{"type":"array","items":{"$ref":"#/components/schemas/CausalChainDto"},"description":"Causal chains leading to the effect"},"effect":{"type":"string","description":"The effect being analyzed"},"root_causes":{"type":"array","items":{"$ref":"#/components/schemas/RootCauseDto"},"description":"All root causes found"}}},"RootCauseDto":{"type":"object","description":"A root cause with its chain","required":["cause","certainty","path"],"properties":{"cause":{"type":"string","description":"The root cause variable"},"certainty":{"type":"number","format":"double","description":"Chain certainty"},"path":{"type":"array","items":{"type":"string"},"description":"Full path from cause to effect"},"via":{"type":["string","null"],"description":"The intermediate variable (via)"}}},"RootCauseWithProofResponse":{"type":"object","description":"Enhanced root cause response with proof tree","required":["effect","root_causes","causal_chains","proof_tree"],"properties":{"causal_chains":{"type":"array","items":{"$ref":"#/components/schemas/CausalChainDto"},"description":"Causal chains"},"effect":{"type":"string","description":"The effect being analyzed"},"proof_tree":{"$ref":"#/components/schemas/CausalProofTreeDto","description":"Proof tree showing how each chain was derived"},"root_causes":{"type":"array","items":{"$ref":"#/components/schemas/RootCauseDto"},"description":"Root causes found"}}},"RowIntegrateRequest":{"type":"object","description":"Request for feature-based data integration\n\nMerge entities from different sources that share common features.\nThis enables data integration across heterogeneous schemas.","required":["match_features"],"properties":{"create_merged":{"type":"boolean","description":"Whether to create a merged entity or just return matches"},"match_features":{"type":"array","items":{"type":"string"},"description":"Features to use for matching entities (the \"join keys\")"},"merge_features":{"type":"array","items":{"type":"string"},"description":"Optional: features to merge from matched entities"},"min_similarity":{"type":"number","format":"double","description":"Optional: minimum similarity threshold (0.0 to 1.0)"},"source_namespaces":{"type":"array","items":{"type":"string"},"description":"Optional: source namespaces to integrate"}}},"RowIntegrateResponse":{"type":"object","description":"Response from feature-based data integration","required":["integration_groups","entities_analyzed","groups_found","duration_us"],"properties":{"duration_us":{"type":"integer","format":"int64","description":"Query time in microseconds","minimum":0},"entities_analyzed":{"type":"integer","description":"Total entities analyzed","minimum":0},"groups_found":{"type":"integer","description":"Number of integration groups found","minimum":0},"integration_groups":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationGroupDto"},"description":"Groups of entities that can be integrated"}}},"RowMatchDto":{"type":"object","description":"A matched entity from row search","required":["id","sort_name","sort_id","features","similarity"],"properties":{"features":{"type":"object","description":"All features of the entity","additionalProperties":{},"propertyNames":{"type":"string"}},"id":{"type":"string","format":"uuid","description":"Entity ID"},"similarity":{"type":"number","format":"double","description":"Similarity score (1.0 = exact match)"},"sort_id":{"type":"string","format":"uuid","description":"Entity's sort ID"},"sort_name":{"type":"string","description":"Entity's sort name"}}},"RowSearchRequest":{"type":"object","description":"Request for schema-flexible entity search\n\nFind all entities that have the specified features, regardless of their sort type.\nThis enables cross-type queries like \"find all entities with a 'name' feature\".","required":["pattern"],"properties":{"collection_id":{"type":["string","null"],"format":"uuid","description":"Optional: limit results to specific collection"},"limit":{"type":"integer","description":"Maximum number of results","minimum":0},"namespace":{"type":["string","null"],"description":"Optional: limit results to specific namespace"},"pattern":{"$ref":"#/components/schemas/RowTypeDto","description":"The row pattern to match (required features)"}}},"RowSearchResponse":{"type":"object","description":"Response from schema-flexible entity search","required":["matches","scanned","sorts_matched","duration_us"],"properties":{"duration_us":{"type":"integer","format":"int64","description":"Query time in microseconds","minimum":0},"matches":{"type":"array","items":{"$ref":"#/components/schemas/RowMatchDto"},"description":"Matched entities"},"scanned":{"type":"integer","description":"Total entities scanned","minimum":0},"sorts_matched":{"type":"integer","description":"Number of distinct sorts matched","minimum":0}}},"RowSimilarityRequest":{"type":"object","description":"Request to compute similarity between row types","required":["row1","row2"],"properties":{"row1":{"$ref":"#/components/schemas/RowTypeDto","description":"First row type"},"row2":{"$ref":"#/components/schemas/RowTypeDto","description":"Second row type"}}},"RowSimilarityResponse":{"type":"object","description":"Response from row similarity computation","required":["similarity","shared_features","only_in_row1","only_in_row2"],"properties":{"only_in_row1":{"type":"array","items":{"type":"string"},"description":"Features only in row1"},"only_in_row2":{"type":"array","items":{"type":"string"},"description":"Features only in row2"},"shared_features":{"type":"array","items":{"type":"string"},"description":"Shared features"},"similarity":{"type":"number","format":"double","description":"Similarity score (0.0 to 1.0)"}}},"RowTypeDto":{"type":"object","description":"Row type specification for queries","required":["features"],"properties":{"features":{"type":"array","items":{"$ref":"#/components/schemas/FeatureRequirementDto"},"description":"Required features"},"open":{"type":"boolean","description":"Whether the row is open (can have additional features) or closed (exact match)"}}},"RowUnifyRequest":{"type":"object","description":"Request to unify two row types","required":["row1","row2"],"properties":{"row1":{"$ref":"#/components/schemas/RowTypeDto","description":"First row type"},"row2":{"$ref":"#/components/schemas/RowTypeDto","description":"Second row type"}}},"RowUnifyResponse":{"type":"object","description":"Response from row unification","required":["success"],"properties":{"failure_reason":{"type":["string","null"],"description":"Reason for failure (if unsuccessful)"},"success":{"type":"boolean","description":"Whether unification succeeded"},"unified":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/RowTypeDto","description":"Unified row type (if successful)"}]}}},"RuleClauseDto":{"type":"object","description":"A rule clause (OSF clause)","properties":{"constraints":{"type":"array","items":{"$ref":"#/components/schemas/RuleConstraintDto"},"description":"Constraints on variables in this clause"}}},"RuleConstraintDto":{"oneOf":[{"type":"object","description":"Variable has a specific sort","required":["var_name","sort_id","type"],"properties":{"sort_id":{"type":"string"},"type":{"type":"string","enum":["sort"]},"var_name":{"type":"string"}}},{"type":"object","description":"Variable has a feature with a value","required":["var_name","feature_name","value","type"],"properties":{"feature_name":{"type":"string"},"type":{"type":"string","enum":["feature"]},"value":{"type":"object"},"var_name":{"type":"string"}}},{"type":"object","description":"Two variables are equal (coreference)","required":["var1","var2","type"],"properties":{"type":{"type":"string","enum":["equal"]},"var1":{"type":"string"},"var2":{"type":"string"}}}],"description":"A constraint in a rule clause"},"RuleDto":{"type":"object","description":"A complete rule","required":["id","head","body","is_fact"],"properties":{"body":{"type":"array","items":{"$ref":"#/components/schemas/RuleClauseDto"}},"head":{"$ref":"#/components/schemas/RuleClauseDto"},"id":{"type":"string"},"is_fact":{"type":"boolean"}}},"RuleStoreResponse":{"type":"object","description":"Response with rule store info","required":["store_id","tenant_id","rule_count"],"properties":{"rule_count":{"type":"integer","minimum":0},"store_id":{"type":"string"},"tenant_id":{"type":"string","format":"uuid"}}},"RuleUtilityDto":{"type":"object","description":"Rule utility DTO.","required":["rule_id","utility","confidence","uses"],"properties":{"confidence":{"type":"number","format":"double","description":"Confidence in utility"},"last_fuzzy_degree":{"type":["number","null"],"format":"double","description":"Last fuzzy degree used in utility update (for verifying fuzzy integration)"},"rule_head_sort":{"type":["string","null"],"description":"Sort name of the rule's head term"},"rule_id":{"type":"string","format":"uuid","description":"Rule ID"},"uses":{"type":"integer","description":"Number of uses","minimum":0},"utility":{"type":"number","format":"double","description":"Utility value"}}},"RunCycleRequest":{"type":"object","description":"Request to run an agent cycle.","required":["agent_id","tenant_id"],"properties":{"agent_id":{"type":"string","format":"uuid","description":"Agent ID"},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"}}},"RunCycleResponse":{"type":"object","description":"Response after running an agent cycle.","required":["outcome","message"],"properties":{"message":{"type":"string","description":"Message describing what happened"},"outcome":{"$ref":"#/components/schemas/CycleOutcomeDto","description":"Outcome of the cycle"}}},"RunIntegratedCycleRequest":{"type":"object","description":"Request to run an integrated cognitive cycle.","required":["agent_id","tenant_id"],"properties":{"agent_id":{"type":"string","format":"uuid","description":"Agent ID"},"config":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/IntegratedEngineConfigDto","description":"Optional configuration overrides"}]},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"}}},"RunIntegratedCycleResponse":{"type":"object","description":"Response from integrated cognitive cycle.","required":["outcome","message","duration_ms"],"properties":{"duration_ms":{"type":"integer","format":"int64","description":"Cycle duration in milliseconds","minimum":0},"message":{"type":"string","description":"Detailed message"},"outcome":{"$ref":"#/components/schemas/IntegratedCycleOutcomeDto","description":"Outcome of the integrated cycle"}}},"RunSynthesisRequest":{"type":"object","description":"Request: run the full grounded-synthesis pipeline (generate → critique\n→ score → optional Elo → coverage) against the LLM configured on the\nAPI server.","required":["target_description","sort_names","strategies","per_strategy_taxonomies","sample_budget"],"properties":{"max_tokens":{"type":"integer","format":"int32","description":"Max tokens per LLM completion.","minimum":0},"per_strategy_taxonomies":{"type":"object","description":"Per-strategy taxonomy bindings — map strategy taxonomy id to the\nlist of sort names drawn from.","additionalProperties":{"type":"array","items":{"type":"string"}},"propertyNames":{"type":"string"}},"run_elo":{"type":"boolean","description":"Whether to run Elo calibration over accepted samples."},"sample_budget":{"type":"integer","description":"Total sample budget across all strategies.","minimum":0},"sampling_seed":{"type":"integer","format":"int64","description":"Sampling seed.","minimum":0},"scores_by_name":{"type":"object","description":"Per-sort relevance score keyed by sort name.","additionalProperties":{"type":"number","format":"double"},"propertyNames":{"type":"string"}},"shacl_shapes":{"type":"array","items":{"$ref":"#/components/schemas/ShaclShapeDto"},"description":"SHACL shapes to translate + register before the run."},"sort_names":{"type":"array","items":{"type":"string"},"description":"All sort names participating in the taxonomy (roots first)."},"strategies":{"type":"array","items":{"$ref":"#/components/schemas/SamplingStrategyDto"},"description":"Sampling strategies."},"style":{"type":"string","description":"Generator style hint: `\"default\" | \"complexify\" | \"paraphrase\" | \"hard_negative\"`."},"subclass_edges":{"type":"array","items":{"type":"array","items":{"type":"string"}},"description":"Parent → child edges as `[child, parent]` pairs. Determines the\nscratch hierarchy; empty means flat (all roots)."},"target_description":{"type":"string","description":"Free-text target dataset description (`y` in the paper)."},"threshold":{"type":"number","format":"double","description":"Filter threshold."}}},"RunSynthesisResponse":{"type":"object","description":"Response: per-sample results + aggregated metrics.","required":["samples","accepted_count","rejected_count","retention_ratio","coverage_level_ratio","coverage_class_ratio"],"properties":{"accepted_count":{"type":"integer","description":"Count of samples that cleared both mechanical and semantic critics.","minimum":0},"coverage_class_ratio":{"type":"number","format":"double","description":"Global class coverage (0..1)."},"coverage_level_ratio":{"type":"array","items":{"type":"number","format":"double"},"description":"Per-level coverage ratio over the filtered taxonomy."},"elo":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/EloSummaryDto","description":"Optional Elo ratings, keyed by sample index in `samples`."}]},"rejected_count":{"type":"integer","description":"Count rejected.","minimum":0},"retention_ratio":{"type":"number","format":"double","description":"Retention ratio of the filtered taxonomy."},"samples":{"type":"array","items":{"$ref":"#/components/schemas/ProducedSampleDto"},"description":"Produced samples."}}},"SafetyModelInfoDto":{"type":"object","description":"Safety model architecture info.","required":["parameters","embedding_dim","categories","questions"],"properties":{"categories":{"type":"integer","minimum":0},"embedding_dim":{"type":"integer","minimum":0},"parameters":{"type":"integer","minimum":0},"questions":{"type":"integer","minimum":0}}},"SampledHypothesisDto":{"type":"object","description":"A single sampled hypothesis DTO.","required":["body_sorts","log_probability","from_joining","trajectory_index"],"properties":{"body_sorts":{"type":"array","items":{"type":"string"},"description":"Body sort names for this hypothesis."},"from_joining":{"type":"boolean","description":"Whether this was produced by rule joining."},"log_probability":{"type":"number","format":"double","description":"Log-probability of sampling this hypothesis."},"trajectory_index":{"type":"integer","description":"Trajectory index that produced this hypothesis.","minimum":0}}},"SamplingDrawDto":{"type":"object","description":"A single draw entry.","required":["taxonomy_id","draws"],"properties":{"draws":{"type":"integer","description":"How many sort names to draw per sample from this taxonomy.","minimum":0},"taxonomy_id":{"type":"string","description":"Taxonomy id matching a key in `per_strategy_taxonomies`."}}},"SamplingStrategyDto":{"type":"object","description":"One sampling strategy description.","required":["name","weight","draws"],"properties":{"draws":{"type":"array","items":{"$ref":"#/components/schemas/SamplingDrawDto"},"description":"`[taxonomy_id, draws_per_sample]` pairs."},"name":{"type":"string","description":"Stable strategy name."},"weight":{"type":"number","format":"double","description":"Relative allocation weight."}}},"SaveWeightsResponse":{"type":"object","description":"Response for the save weights endpoint.","required":["success"],"properties":{"error":{"type":["string","null"],"description":"Error message if saving failed."},"success":{"type":"boolean","description":"Whether weights were saved successfully."}}},"ScenarioSummaryDto":{"type":"object","description":"Summary of a single scenario (used in list responses).","required":["scenario_id","prompt","created_at","sorts_created","beliefs_created","rules_created"],"properties":{"agent_id":{"type":["string","null"],"description":"Agent TermId (if an agent was created)."},"beliefs_created":{"type":"integer","description":"Number of beliefs created during materialization.","minimum":0},"created_at":{"type":"integer","format":"int64","description":"Unix timestamp of creation."},"prompt":{"type":"string","description":"Original user prompt."},"rules_created":{"type":"integer","description":"Number of rules created during materialization.","minimum":0},"scenario_id":{"type":"string","description":"Unique scenario identifier."},"sorts_created":{"type":"integer","description":"Number of sorts created during materialization.","minimum":0}}},"SchedulingFeasibilityRequest":{"type":"object","description":"A scheduling feasibility request.\n\nAgents are identified by opaque caller-chosen string IDs so the\nresponse can be joined back to whatever identity the caller\nmaintains (e.g. employee numbers, user IDs, UUIDs).","required":["agents","days","shifts_per_day","demands"],"properties":{"agents":{"type":"array","items":{"$ref":"#/components/schemas/AgentInput"},"description":"All agents that may be assigned to slots."},"days":{"type":"integer","description":"Number of days in the scheduling horizon. Valid day indices\nare `0..days`.","minimum":0},"demands":{"type":"array","items":{"$ref":"#/components/schemas/ShiftDemandInput"},"description":"Per-slot demand. At most one entry per `(day, shift)` pair."},"pins":{"type":"array","items":{"$ref":"#/components/schemas/PinInput"},"description":"Pre-assigned `(agent_id, day, shift)` triples the caller has\nfixed; the engine treats each as confirmed-true and reduces\nthe remaining demand accordingly."},"shifts_per_day":{"type":"integer","description":"Number of shifts per day. Valid shift indices are\n`0..shifts_per_day`.","minimum":0}}},"SchedulingFeasibilityResponse":{"type":"object","description":"Response to [`SchedulingFeasibilityRequest`].","required":["status","assignments"],"properties":{"assignments":{"type":"array","items":{"$ref":"#/components/schemas/AssignmentDto"},"description":"Empty when `status` is `infeasible`; otherwise contains one\nentry per `(agent, day, shift)` triple in the input grid."},"status":{"$ref":"#/components/schemas/SchedulingStatusDto"}}},"SchedulingOptimizeRequest":{"type":"object","description":"Request body for `POST /api/v1/scheduling/optimize`.\n\nSame hard-constraint shape as\n[`SchedulingFeasibilityRequest`], plus a list of soft\n`preferences`. The engine returns the per-cell envelope across\nthe space of **optimal** schedules under the supplied\npreferences.","required":["agents","days","shifts_per_day","demands"],"properties":{"agents":{"type":"array","items":{"$ref":"#/components/schemas/AgentInput"}},"days":{"type":"integer","minimum":0},"demands":{"type":"array","items":{"$ref":"#/components/schemas/ShiftDemandInput"}},"pins":{"type":"array","items":{"$ref":"#/components/schemas/PinInput"}},"preferences":{"type":"array","items":{"$ref":"#/components/schemas/PreferenceInput"},"description":"Soft preferences applied to the objective. Empty = unweighted\n(every feasible schedule is \"optimal\")."},"shifts_per_day":{"type":"integer","minimum":0}}},"SchedulingOptimizeResponse":{"type":"object","description":"Response to [`SchedulingOptimizeRequest`].\n\nThe per-cell `assignments` trichotomy classifies each cell over\nthe space of **optimal** schedules — strictly stronger than the\nfeasibility-only trichotomy returned by\n`/api/v1/scheduling/feasibility`. When the un-pinned reduced\nproblem is infeasible, `status = \"infeasible\"`, `assignments` is\nempty, and `total_score` is `0`.","required":["status","total_score","assignments"],"properties":{"assignments":{"type":"array","items":{"$ref":"#/components/schemas/AssignmentDto"},"description":"Empty when `status` is `infeasible`; otherwise one entry per\n`(agent, day, shift)` triple in the input grid, with\ntrichotomy taken across the space of optimal schedules."},"status":{"$ref":"#/components/schemas/SchedulingStatusDto"},"total_score":{"type":"integer","format":"int64","description":"Sum of [`PreferenceInput::score`] over assigned cells in the\noptimum. `0` when no preferences were supplied or the\nproblem is infeasible."}}},"SchedulingStatusDto":{"type":"string","description":"Top-level request status.","enum":["feasible","infeasible"]},"SearchCommunitiesRequest":{"type":"object","description":"Request to search communities","required":["tenant_id","search_mode"],"properties":{"max_results":{"type":"integer","description":"Maximum results to return","minimum":0},"min_impact_score":{"type":["number","null"],"format":"double","description":"Minimum impact score (for impact search)"},"search_mode":{"$ref":"#/components/schemas/CommunitySearchModeDto","description":"Search mode"},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"}}},"SearchCommunitiesResponse":{"type":"object","description":"Response from community search","required":["communities","stats"],"properties":{"communities":{"type":"array","items":{"$ref":"#/components/schemas/CommunityMatchDto"},"description":"Matching communities"},"stats":{"$ref":"#/components/schemas/CommunitySearchStatsDto","description":"Search statistics"}}},"SearchModeDto":{"type":"string","description":"Which computation the search endpoint should perform.\n\nDefaults to `solutions` for full backward compatibility with existing clients\nthat do not send a `mode` field.","enum":["solutions","feasibility"]},"SearchRequest":{"type":"object","description":"Request to search for solutions","required":["strategy"],"properties":{"collect_traces":{"type":["boolean","null"],"description":"Enable trace collection during search.\nWhen true, every choice point records a SearchTrace into the shared\nTraceCollector for later training via `/admin/neuro-symbolic/train/from-traces`."},"max_solutions":{"type":["integer","null"],"description":"Maximum number of solutions to find (only used in `solutions` mode)","minimum":0},"mode":{"$ref":"#/components/schemas/SearchModeDto","description":"Which computation to perform. Omit or set to `\"solutions\"` for the\ndefault enumeration behaviour (backward compatible)."},"strategy":{"$ref":"#/components/schemas/SearchStrategyDto","description":"Search strategy to use"},"use_neural_guidance":{"type":["boolean","null"],"description":"Wire the neural scorer into search (AlphaProof-style guidance).\nWhen true, the search strategy uses the trained CandleSearchScorer\nto order alternatives at each choice point."}}},"SearchResponse":{"oneOf":[{"type":"object","description":"Returned when `mode = \"solutions\"` (the default).\n\nContains up to `max_solutions` complete, valid assignments.\n`count` is the number of solutions actually found; if `count < max_solutions`\nthe search exhausted the solution space.","required":["solutions","count","kind"],"properties":{"count":{"type":"integer","description":"Number of solutions found.","minimum":0},"kind":{"type":"string","enum":["solutions"]},"search_stats":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/SearchStatsDto","description":"Search statistics (present when `collect_traces` or `use_neural_guidance`\nis true, or when the SAT solver was used)."}]},"solutions":{"type":"array","items":{"$ref":"#/components/schemas/SpaceSolutionDto"},"description":"Enumerated complete assignments."}}},{"type":"object","description":"Returned when `mode = \"feasibility\"`.\n\nMaps each uncommitted variable name to its reachability in the solution\nspace. Variables that do not appear were either already committed or are\nnot binary choice-point variables.","required":["variables","kind"],"properties":{"kind":{"type":"string","enum":["feasibility"]},"search_stats":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/SearchStatsDto","description":"Solver statistics for the feasibility queries."}]},"variables":{"type":"object","description":"Per-variable feasibility. Key is the variable name as registered\nin the space's choice points.","additionalProperties":{"$ref":"#/components/schemas/VariableFeasibilityDto"},"propertyNames":{"type":"string"}}}}],"description":"Response from the search endpoint.\n\nThe `kind` field is a discriminator — always read it first to know which\nvariant you received before accessing the mode-specific fields."},"SearchStatsDto":{"type":"object","description":"Search statistics collected during a search operation.\n\nEnables side-by-side comparison of heuristic vs neural-guided search:\ncompare nodes_explored, backtracks, and solve_time_ms across runs.","required":["nodes_explored","nodes_pruned","backtracks","solve_time_ms","scorer_calls","restarts","learned_clauses"],"properties":{"backtracks":{"type":"integer","description":"Number of backtracks (dead ends encountered).","minimum":0},"forced_choices":{"type":"array","items":{"$ref":"#/components/schemas/ChoiceSelection"},"description":"Choice points that were forced by initial propagation (before any\nsearch decision). Each entry is an unbiased \"confirmed\" assignment:\nevery solution in the search space respects it. Clients should use\nthis list (not the intersection of enumerated solutions) to display\nwhich choices are definitively locked in."},"learned_clauses":{"type":"integer","description":"Number of learned nogood clauses.","minimum":0},"nodes_explored":{"type":"integer","description":"Total nodes visited during search.","minimum":0},"nodes_pruned":{"type":"integer","description":"Nodes pruned by constraint propagation.","minimum":0},"restarts":{"type":"integer","description":"Number of restarts performed (Luby restart strategy).","minimum":0},"scorer_calls":{"type":"integer","description":"Number of times the neural scorer was invoked.","minimum":0},"solve_time_ms":{"type":"integer","format":"int64","description":"Wall-clock search time in milliseconds.","minimum":0}}},"SearchStrategyDto":{"oneOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["depth_first"]}}},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["breadth_first"]}}}],"description":"Search strategy"},"SendMessageRequest":{"type":"object","description":"Request to send a message to another agent.","required":["tenant_id","from_agent_id","to_agent_id","content"],"properties":{"content":{"$ref":"#/components/schemas/JsonValue","description":"Message content (arbitrary JSON)"},"from_agent_id":{"type":"string","format":"uuid","description":"Sender agent ID"},"priority":{"type":"integer","format":"int64","description":"Priority (0-10, higher is more urgent)","default":5},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"},"to_agent_id":{"type":"string","format":"uuid","description":"Recipient agent ID"}}},"SendMessageResponse":{"type":"object","description":"Response after sending a message.","required":["message_id","timestamp","message"],"properties":{"message":{"type":"string","description":"Message"},"message_id":{"type":"string","format":"uuid","description":"Created message ID"},"timestamp":{"type":"string","description":"Delivery timestamp"}}},"SessionProgressResponse":{"type":"object","description":"Response containing live progress for all documents in a session.","required":["session_id","documents"],"properties":{"documents":{"type":"array","items":{"$ref":"#/components/schemas/DocumentProgressDto"},"description":"Documents currently being processed (with live progress)."},"session_id":{"type":"string","format":"uuid","description":"Session ID."}}},"SessionStatsResponse":{"type":"object","description":"Response for GET /api/v1/ingest/sessions/{session_id}/stats","required":["session_id","documents","total"],"properties":{"documents":{"type":"array","items":{"$ref":"#/components/schemas/DocumentStatsDto"},"description":"Stats per document (only completed documents included)"},"session_id":{"type":"string","format":"uuid","description":"Session identifier"},"total":{"type":"integer","description":"Total number of documents with stats","minimum":0}}},"SessionStatusResponse":{"type":"object","description":"Current status of a live oversight session.","required":["session_id","status","user_intent","step_count","created_at","updated_at"],"properties":{"alerts":{"type":"array","items":{"$ref":"#/components/schemas/OversightAlertDto"},"description":"All alerts accumulated during the session"},"created_at":{"type":"integer","format":"int64","description":"Unix timestamp (ms) when session was created","minimum":0},"current_score":{"type":["number","null"],"format":"double","description":"Current running score (if any steps verified)"},"current_verdict":{"type":["string","null"],"description":"Current running verdict (if any steps verified)"},"session_id":{"type":"string","description":"Unique session identifier"},"status":{"type":"string","description":"Session status: \"active\", \"finalizing\", \"completed\", \"cancelled\""},"step_count":{"type":"integer","description":"Number of steps ingested","minimum":0},"updated_at":{"type":"integer","format":"int64","description":"Unix timestamp (ms) of last update","minimum":0},"user_intent":{"type":"string","description":"User intent for this session"}}},"SetFeatureRequest":{"type":"object","description":"Request to set a feature on a term","required":["term_id","feature_name","value"],"properties":{"feature_name":{"type":"string"},"term_id":{"type":"string"},"value":{"type":"object"}}},"SetFeatureResponse":{"type":"object","description":"Response after setting feature","required":["success","term_id","feature_name"],"properties":{"feature_name":{"type":"string"},"success":{"type":"boolean"},"term_id":{"type":"string"}}},"SetPreferenceRequestDto":{"type":"object","description":"Request to set/update a preference.","required":["value"],"properties":{"scope":{"type":["string","null"],"description":"Optional scope."},"value":{"type":"string","description":"Preference value."}}},"SetSortSimilarityRequest":{"type":"object","description":"Request to set similarity degree between two sorts","required":["sort1_id","sort2_id","degree"],"properties":{"degree":{"type":"number","format":"double","description":"Similarity degree ∈ [0,1] (symmetric)"},"sort1_id":{"type":"string","format":"uuid","description":"First sort ID"},"sort2_id":{"type":"string","format":"uuid","description":"Second sort ID"}}},"SetSortSimilarityResponse":{"type":"object","description":"Response for setting sort similarity","required":["success","message"],"properties":{"message":{"type":"string","description":"Message"},"success":{"type":"boolean","description":"Whether the operation succeeded"}}},"ShaclPropertyDto":{"type":"object","description":"A SHACL property shape supporting the M1 facet subset.","required":["path"],"properties":{"datatype":{"type":["string","null"],"description":"`sh:datatype` (local xsd name, e.g. `\"integer\"`, `\"string\"`)."},"max_count":{"type":["integer","null"],"format":"int32","description":"`sh:maxCount`.","minimum":0},"max_value":{"type":["string","null"],"description":"`sh:maxInclusive`."},"min_count":{"type":["integer","null"],"format":"int32","description":"`sh:minCount`.","minimum":0},"min_value":{"type":["string","null"],"description":"`sh:minInclusive` (string-preserved for datatype-agnostic parsing)."},"path":{"type":"string","description":"Feature path (`sh:path` local name)."}}},"ShaclShapeDto":{"type":"object","description":"A SHACL shape expressed over sort names (local names only — no IRIs).","required":["target_class","properties"],"properties":{"properties":{"type":"array","items":{"$ref":"#/components/schemas/ShaclPropertyDto"},"description":"Property shapes."},"target_class":{"type":"string","description":"Local name of the target class."}}},"ShiftDemandInput":{"type":"object","description":"Demand for a single `(day, shift)` slot.","required":["day","shift","total"],"properties":{"day":{"type":"integer","minimum":0},"role_minimums":{"type":"object","description":"Minimum count per role. The remainder of `total` may be filled\nby any eligible agent. Role names must match tags used in\n[`AgentInput::roles`].","additionalProperties":{"type":"integer","format":"int32","minimum":0},"propertyNames":{"type":"string"}},"shift":{"type":"integer","minimum":0},"total":{"type":"integer","format":"int32","description":"Total number of agents required for this slot.","minimum":0}}},"SimilarityEntry":{"type":"object","description":"A single similarity entry for bulk operations","required":["sort1_id","sort2_id","degree"],"properties":{"degree":{"type":"number","format":"double","description":"Similarity degree [0, 1]"},"sort1_id":{"type":"string","format":"uuid","description":"First sort ID"},"sort2_id":{"type":"string","format":"uuid","description":"Second sort ID"}}},"SimilarityMatch":{"type":"object","description":"A single similarity match result","required":["term","degree","confidence_percent"],"properties":{"confidence_percent":{"type":"number","format":"double","description":"Percentage representation (0-100)"},"degree":{"type":"number","format":"double","description":"Similarity degree μ ∈ [0,1]"},"term":{"$ref":"#/components/schemas/TermDto","description":"The matched term"}}},"SimilaritySearchResponse":{"type":"object","description":"Response from similarity search","required":["results","count"],"properties":{"count":{"type":"integer","description":"Number of results returned","minimum":0},"results":{"type":"array","items":{"$ref":"#/components/schemas/SimilarityMatch"},"description":"List of matching terms with similarity scores"}}},"SingleCopyRequest":{"type":"object","description":"Single copy request in a batch","required":["term_id","copy_mode"],"properties":{"copy_mode":{"$ref":"#/components/schemas/CopyModeDto"},"term_id":{"type":"string"}}},"SnapshotEnvelope":{"type":"object","description":"The envelope structure for an exported snapshot.","required":["format","version","metadata","data"],"properties":{"data":{"description":"The snapshot data payload (tables as JSON objects with arrays of rows)."},"format":{"type":"string","description":"Must be \"osfkb-snapshot\"."},"metadata":{"$ref":"#/components/schemas/SnapshotExportMetadata","description":"Metadata about the snapshot."},"version":{"type":"integer","format":"int32","description":"Envelope version. Must be 1.","minimum":0}}},"SnapshotExportMetadata":{"type":"object","description":"Metadata block inside an exported snapshot envelope.","required":["name","created_at","source_tenant_id","table_counts","size_bytes","osfkb_version"],"properties":{"created_at":{"type":"string","description":"ISO 8601 timestamp of when the snapshot was originally created."},"name":{"type":"string","description":"Human-readable name."},"osfkb_version":{"type":"string","description":"OSFKB version that created this snapshot."},"size_bytes":{"type":"integer","format":"int64","description":"Approximate byte size of the data payload."},"source_tenant_id":{"type":"string","description":"The tenant this snapshot was originally captured from."},"table_counts":{"type":"object","description":"Per-table row counts.","additionalProperties":{"type":"integer","minimum":0},"propertyNames":{"type":"string"}}}},"SnapshotResponse":{"type":"object","description":"Snapshot metadata response (used in create, list, and get responses).","required":["id","tenant_id","name","created_at","table_counts","size_bytes"],"properties":{"created_at":{"type":"string","description":"ISO 8601 timestamp of when the snapshot was taken."},"id":{"type":"string","description":"Unique snapshot identifier."},"name":{"type":"string","description":"Human-readable name given at creation time."},"size_bytes":{"type":"integer","format":"int64","description":"Approximate byte size of the serialized data payload."},"table_counts":{"type":"object","description":"Per-table row counts at snapshot time.","additionalProperties":{"type":"integer","minimum":0},"propertyNames":{"type":"string"}},"tenant_id":{"type":"string","description":"The tenant this snapshot was captured from."}}},"SnapshotValidationErrorResponse":{"type":"object","description":"Response for validation errors during import.","required":["error","message","validation_errors"],"properties":{"error":{"type":"string","description":"Error type."},"message":{"type":"string","description":"Human-readable summary."},"validation_errors":{"type":"array","items":{"type":"string"},"description":"List of all validation errors found."}}},"SoftUnifyRequest":{"type":"object","description":"Request for soft unification (Phase 2).","required":["term_a_id","term_b_id"],"properties":{"term_a_id":{"type":"string","format":"uuid","description":"First term ID."},"term_b_id":{"type":"string","format":"uuid","description":"Second term ID."}}},"SoftUnifyResponse":{"type":"object","description":"Response for soft unification.","required":["confidence","sort_score","feature_score","hard_compatible","elapsed_ms"],"properties":{"confidence":{"type":"number","format":"double"},"elapsed_ms":{"type":"integer","format":"int64","minimum":0},"feature_score":{"type":"number","format":"double"},"hard_compatible":{"type":"boolean"},"sort_score":{"type":"number","format":"double"}}},"SolutionDto":{"type":"object","description":"A solution from backward chaining or open-world inference.","required":["substitution","certainty"],"properties":{"certainty":{"type":"number","format":"double","description":"Overall certainty of this solution"},"evidence_matched":{"type":["integer","null"],"description":"Number of matched antecedents (open-world only).\nPresent only when open_world=true in the request.","minimum":0},"evidence_ratio":{"type":["number","null"],"format":"double","description":"Evidence ratio (open-world only): matched antecedents / total antecedents.\nPresent only when open_world=true in the request."},"proof":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ProofDto","description":"The proof tree (optional, may be omitted for performance)"}]},"residuated_sorts":{"type":"array","items":{"type":"string"},"description":"Sort names of residuated (missing/unknown) antecedents (open-world only).\nPresent only when open_world=true in the request."},"substitution":{"$ref":"#/components/schemas/HomoiconicSubstitutionDto","description":"The substitution that satisfies the query"}}},"SolveConstraintRequest":{"type":"object","description":"Request to solve a constraint problem","required":["constraints"],"properties":{"constraints":{"type":"array","items":{"$ref":"#/components/schemas/ArithmeticConstraintDto"}},"initial_bindings":{"type":["object","null"],"additionalProperties":{"type":"integer","format":"int64"},"propertyNames":{"type":"string"}}}},"SolveConstraintResponse":{"type":"object","description":"Response from solving a constraint problem","required":["success","bindings","suspended_constraints"],"properties":{"bindings":{"type":"object","additionalProperties":{"type":"integer","format":"int64"},"propertyNames":{"type":"string"}},"message":{"type":["string","null"]},"success":{"type":"boolean"},"suspended_constraints":{"type":"array","items":{"type":"string"}}}},"SortAncestorsResponse":{"type":"object","description":"Response with ancestor sorts","required":["sort_id","ancestors"],"properties":{"ancestors":{"type":"array","items":{"$ref":"#/components/schemas/SortInfoDto"}},"sort_id":{"type":"string"}}},"SortBoxRequest":{"type":"object","description":"Request for looking up a sort's box embedding.","required":["sort_name"],"properties":{"sort_name":{"type":"string","description":"The sort name to look up."}}},"SortBoxResponse":{"type":"object","description":"Response for the sort box lookup endpoint.","required":["sort_name","found"],"properties":{"dim":{"type":["integer","null"],"description":"Embedding dimensionality.","minimum":0},"error":{"type":["string","null"],"description":"Error message if lookup failed."},"found":{"type":"boolean","description":"Whether the sort was found and has a box embedding."},"log_volume":{"type":["number","null"],"format":"double","description":"Log-volume of the box (more specific sorts have more negative values)."},"max_coords":{"type":["array","null"],"items":{"type":"number","format":"double"},"description":"Maximum coordinates of the box."},"min_coords":{"type":["array","null"],"items":{"type":"number","format":"double"},"description":"Minimum coordinates of the box."},"sort_name":{"type":"string","description":"The sort name that was looked up."}}},"SortCalibrationDto":{"type":"object","description":"ECE result for a single sort.","required":["sort_id","sort_name","ece","total_predictions","accuracy","mean_confidence","feature_ece","is_overconfident","is_underconfident"],"properties":{"accuracy":{"type":"number","format":"double","description":"Overall accuracy for this sort."},"ece":{"type":"number","format":"double","description":"Expected Calibration Error."},"feature_ece":{"type":"object","description":"Feature-level ECE (if computed).","additionalProperties":{"type":"number","format":"double"},"propertyNames":{"type":"string"}},"is_overconfident":{"type":"boolean","description":"Whether the sort is overconfident."},"is_underconfident":{"type":"boolean","description":"Whether the sort is underconfident."},"mean_confidence":{"type":"number","format":"double","description":"Mean confidence for this sort."},"sort_id":{"type":"string","format":"uuid","description":"Sort UUID."},"sort_name":{"type":"string","description":"Sort name."},"total_predictions":{"type":"integer","description":"Total predictions for this sort.","minimum":0}}},"SortChildrenResponse":{"type":"object","description":"Response with child sorts","required":["sort_id","children"],"properties":{"children":{"type":"array","items":{"$ref":"#/components/schemas/SortInfoDto"}},"sort_id":{"type":"string"}}},"SortCompareOperator":{"type":"string","description":"Sort comparison operators","enum":["isa_le","isa_lt","isa_ge","isa_gt","isa_eq","isa_cmp"]},"SortCompareRequest":{"type":"object","description":"Request for sort comparison","required":["tenant_id","sort_a","sort_b","operator"],"properties":{"operator":{"$ref":"#/components/schemas/SortCompareOperator"},"sort_a":{"type":"string"},"sort_b":{"type":"string"},"tenant_id":{"type":"string","format":"uuid"}}},"SortCompareResponse":{"type":"object","description":"Response from sort comparison","required":["sort_a","sort_b","operator","result"],"properties":{"operator":{"$ref":"#/components/schemas/SortCompareOperator"},"result":{"type":"boolean"},"sort_a":{"type":"string"},"sort_b":{"type":"string"}}},"SortCompareResultDto":{"type":"object","description":"Single sort comparison result","required":["sort_a","sort_b","operator","result"],"properties":{"operator":{"$ref":"#/components/schemas/SortCompareOperator"},"result":{"type":"boolean"},"sort_a":{"type":"string"},"sort_b":{"type":"string"}}},"SortComparisonDto":{"type":"object","description":"Single sort comparison","required":["sort_a","sort_b","operator"],"properties":{"operator":{"$ref":"#/components/schemas/SortCompareOperator"},"sort_a":{"type":"string"},"sort_b":{"type":"string"}}},"SortDescendantsResponse":{"type":"object","description":"Response with descendant sorts","required":["sort_id","descendants"],"properties":{"descendants":{"type":"array","items":{"$ref":"#/components/schemas/SortInfoDto"}},"sort_id":{"type":"string"}}},"SortDiscoveryRequestDto":{"type":"object","description":"Request for on-demand sort discovery via FCA (Formal Concept Analysis).\n\nPOST /api/v1/analysis/sort-discovery","properties":{"auto_create_sorts":{"type":"boolean","description":"Whether to automatically create sorts above threshold (default: false)"},"auto_create_threshold":{"type":"number","format":"double","description":"Confidence threshold for automatic sort creation (default: 0.8)"},"fuzzy_thresholds":{"type":"array","items":{"type":"number","format":"double"},"description":"Alpha-cut thresholds for fuzzy concept enumeration (default: [] = crisp only).\nExample: [0.9, 0.8, 0.7, 0.5] runs FCA at each threshold level."},"max_concepts":{"type":"integer","description":"Maximum number of formal concepts to enumerate (default: 10_000)","minimum":0},"max_terms":{"type":"integer","description":"Maximum number of terms to analyze (safety limit for large KBs) (default: 50_000)","minimum":0},"min_confidence":{"type":"number","format":"double","description":"Minimum confidence for a recommendation to be included (default: 0.3)"},"min_extent_size":{"type":"integer","description":"Minimum extent size (number of terms sharing the feature set) (default: 2)","minimum":0},"min_intent_size":{"type":"integer","description":"Minimum intent size (number of features in a concept) (default: 2)","minimum":0}}},"SortDiscoveryResponseDto":{"type":"object","description":"Response from sort discovery analysis.","required":["success","terms_analyzed","total_concepts","concepts_matching_existing","novel_concepts_discovered","sorts_created","recommendations","processing_time_ms"],"properties":{"concepts_matching_existing":{"type":"integer","description":"Concepts that match existing sorts in the hierarchy","minimum":0},"fuzzy_levels":{"type":["array","null"],"items":{"$ref":"#/components/schemas/FuzzyConceptLevelDto"},"description":"Fuzzy concept levels (only present when fuzzy_thresholds was non-empty)"},"novel_concepts_discovered":{"type":"integer","description":"Novel concepts discovered (potential new sorts)","minimum":0},"processing_time_ms":{"type":"integer","description":"Processing time in milliseconds","minimum":0},"recommendations":{"type":"array","items":{"$ref":"#/components/schemas/SortRecommendationDto"},"description":"Ranked recommendations for new sorts"},"sorts_created":{"type":"array","items":{"type":"string"},"description":"Names of sorts created (if auto_create_sorts was enabled)"},"success":{"type":"boolean","description":"Whether the analysis succeeded"},"terms_analyzed":{"type":"integer","description":"Number of terms analyzed","minimum":0},"total_concepts":{"type":"integer","description":"Total formal concepts enumerated by FCA","minimum":0}}},"SortDto":{"type":"object","description":"API representation of a sort with full OSF schema","required":["id","name","tenant_id","parents"],"properties":{"annotations":{"type":"object","description":"Custom OWL annotations (e.g., icon, color)","additionalProperties":{"type":"string"},"propertyNames":{"type":"string"}},"bound_constraints":{"type":"array","items":{"$ref":"#/components/schemas/BoundConstraintDto"},"description":"Bound constraints on feature values"},"description":{"type":["string","null"],"description":"Human-readable description for semantic search"},"feature_declarations":{"type":"array","items":{"$ref":"#/components/schemas/FeatureDescriptorDto"},"description":"Feature declarations that define the sort's schema"},"id":{"type":"string","format":"uuid","description":"Sort ID"},"name":{"type":"string","description":"Sort name"},"needs_review":{"type":"boolean","description":"Whether this sort needs human review"},"origin":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/SortOriginDto","description":"Origin/provenance of this sort"}]},"parents":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Parent sort IDs"},"status":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/SortStatusDto","description":"Lifecycle status"}]},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"}}},"SortInfoDto":{"type":"object","description":"Basic sort information","required":["id"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]}}},"SortListResponse":{"type":"object","description":"Response for sort list operations","required":["sorts","count"],"properties":{"count":{"type":"integer","description":"Number of sorts in **this response** — not the tenant total\nwhen pagination is active.","minimum":0},"offset":{"type":"integer","description":"Offset of the first sort in this response.","minimum":0},"sorts":{"type":"array","items":{"$ref":"#/components/schemas/SortDto"},"description":"Sorts in this page (or all sorts when no ``limit`` query\nparameter was supplied)."},"total":{"type":"integer","description":"Total number of sorts the tenant owns after filters, across\nall pages. Lets the client know when to stop paginating.","minimum":0}}},"SortOriginDto":{"oneOf":[{"type":"object","description":"Manually created by a user","required":["created_by","type"],"properties":{"created_by":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["Manual"]}}},{"type":"object","description":"Auto-discovered by LLM extraction","required":["confidence","type"],"properties":{"confidence":{"type":"number","format":"float"},"source_document":{"type":["string","null"]},"type":{"type":"string","enum":["LlmExtracted"]}}},{"type":"object","description":"Imported from external ontology","required":["ontology","original_id","type"],"properties":{"ontology":{"type":"string"},"original_id":{"type":"string"},"type":{"type":"string","enum":["Imported"]}}},{"type":"object","description":"System-defined","required":["type"],"properties":{"type":{"type":"string","enum":["System"]}}},{"type":"object","description":"Learned from examples (ILP)","required":["confidence","example_count","type"],"properties":{"confidence":{"type":"number","format":"float"},"example_count":{"type":"integer","minimum":0},"type":{"type":"string","enum":["Learned"]}}},{"type":"object","description":"Autonomously learned by the cognitive system from observed patterns","required":["confidence","source","observation_count","type"],"properties":{"confidence":{"type":"number","format":"float"},"observation_count":{"type":"integer","minimum":0},"source":{"type":"string"},"type":{"type":"string","enum":["AutonomousLearning"]}}}],"description":"API representation of sort origin/provenance"},"SortParentsResponse":{"type":"object","description":"Response with parent sorts","required":["sort_id","parents"],"properties":{"parents":{"type":"array","items":{"$ref":"#/components/schemas/SortInfoDto"}},"sort_id":{"type":"string"}}},"SortRecommendationDto":{"type":"object","description":"A single sort recommendation from FCA analysis.","required":["sort_name","features","term_count","confidence","explanation"],"properties":{"confidence":{"type":"number","format":"double","description":"Confidence score (0.0 - 1.0)"},"explanation":{"type":"string","description":"Human-readable explanation of why this sort is recommended"},"features":{"type":"array","items":{"type":"string"},"description":"Features that define this sort"},"parent_sort":{"type":["string","null"],"description":"Suggested parent sort in the hierarchy"},"sort_name":{"type":"string","description":"Suggested sort name (GLB-aware)"},"term_count":{"type":"integer","description":"Number of terms matching this feature set","minimum":0}}},"SortResponse":{"type":"object","description":"Response for sort operations","required":["sort"],"properties":{"sort":{"$ref":"#/components/schemas/SortDto","description":"The sort"}}},"SortStatusDto":{"oneOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["Active"]}}},{"type":"object","required":["reason","type"],"properties":{"reason":{"type":"string"},"replacement":{"type":["string","null"],"format":"uuid"},"type":{"type":"string","enum":["Deprecated"]}}},{"type":"object","required":["type"],"properties":{"submitted_by":{"type":["string","null"],"format":"uuid"},"type":{"type":"string","enum":["Proposed"]}}}],"description":"API representation of sort lifecycle status"},"SortSuggestionDto":{"type":"object","description":"Sort suggestion DTO from autonomous sort learning.","required":["suggested_name","parent_sorts","features","confidence","origin"],"properties":{"confidence":{"type":"number","format":"double","description":"Confidence in this suggestion (0.0 to 1.0)"},"features":{"type":"array","items":{"type":"string"},"description":"Feature names for the new sort"},"observation_count":{"type":["integer","null"],"format":"int32","description":"Number of supporting observations","minimum":0},"origin":{"type":"string","description":"Source mechanism (drift, lgg, observation)"},"parent_sorts":{"type":"array","items":{"type":"string"},"description":"Parent sort names"},"suggested_name":{"type":"string","description":"Suggested name for the new sort"}}},"SortSummaryDto":{"type":"object","description":"Summary of a sort for trace responses","required":["id","name","is_synthetic"],"properties":{"id":{"type":"string","format":"uuid","description":"Sort ID"},"is_synthetic":{"type":"boolean","description":"Whether this is a synthetic sort"},"name":{"type":"string","description":"Sort name"}}},"SourceDetailResponse":{"type":"object","description":"Response with source details and health.","required":["source_id","source_type","available"],"properties":{"available":{"type":"boolean","description":"Whether the source is currently available"},"source_id":{"type":"string","description":"Source identifier"},"source_type":{"type":"string","description":"Source type"}}},"SourceExcerptDto":{"type":"object","description":"Source excerpt DTO","required":["concept","text"],"properties":{"concept":{"type":"string"},"document":{"type":["string","null"]},"text":{"type":"string"}}},"SourceSummaryDto":{"type":"object","description":"Summary of a registered source.","required":["source_id","source_type","available"],"properties":{"available":{"type":"boolean","description":"Whether the source is currently available/reachable"},"source_id":{"type":"string","description":"Source identifier"},"source_type":{"type":"string","description":"Source type"}}},"SpaceConstraintDto":{"oneOf":[{"type":"object","required":["term1_id","term2_id","type"],"properties":{"term1_id":{"type":"string"},"term2_id":{"type":"string"},"type":{"type":"string","enum":["unification"]}}},{"type":"object","required":["expression","type"],"properties":{"expression":{"type":"string"},"type":{"type":"string","enum":["arithmetic"]}}},{"type":"object","required":["variables","type"],"properties":{"type":{"type":"string","enum":["all_different"]},"variables":{"type":"array","items":{"type":"string"}}}},{"type":"object","required":["assignment","variable","id","type"],"properties":{"assignment":{"type":"string"},"id":{"type":"integer","format":"int64"},"type":{"type":"string","enum":["feature_assign"]},"variable":{"type":"string"}}},{"type":"object","required":["variables","total","type"],"properties":{"total":{"type":"integer","format":"int64"},"type":{"type":"string","enum":["sum_less_equal"]},"variables":{"type":"array","items":{"type":"string"}}}},{"type":"object","required":["variables","total","type"],"properties":{"total":{"type":"integer","format":"int64"},"type":{"type":"string","enum":["sum_greater_equal"]},"variables":{"type":"array","items":{"type":"string"}}}},{"type":"object","required":["index","table","result","type"],"properties":{"index":{"type":"string"},"result":{"type":"string"},"table":{"type":"array","items":{"type":"integer","format":"int64"}},"type":{"type":"string","enum":["element"]}}},{"type":"object","required":["index","vars","result","type"],"properties":{"index":{"type":"string"},"result":{"type":"string"},"type":{"type":"string","enum":["element_var_array"]},"vars":{"type":"array","items":{"type":"string"}}}},{"type":"object","required":["a","b","bool","type"],"properties":{"a":{"type":"string"},"b":{"type":"string"},"bool":{"type":"string"},"type":{"type":"string","enum":["reified_equal"]}}},{"type":"object","required":["a","b","bool","type"],"properties":{"a":{"type":"string"},"b":{"type":"string"},"bool":{"type":"string"},"type":{"type":"string","enum":["reified_less_equal"]}}},{"type":"object","required":["variables","total","type"],"properties":{"total":{"type":"integer","format":"int64"},"type":{"type":"string","enum":["sum_equal"]},"variables":{"type":"array","items":{"type":"string"}}}},{"type":"object","description":"Lexicographic ordering `a ≤_lex b` on two equal-length boolean\nvectors. See [`Constraint::LexLeq`][crate::operations::computation_space::Constraint::LexLeq]\nin the domain for semantics.","required":["a","b","type"],"properties":{"a":{"type":"array","items":{"type":"string"}},"b":{"type":"array","items":{"type":"string"}},"type":{"type":"string","enum":["lex_leq"]}}},{"type":"object","description":"Declare that the given boolean-variable vectors are pairwise\ninterchangeable and install chained lex-ordering constraints\nbetween consecutive pairs. Equivalent to emitting\n`LexLeq(groups[i], groups[i+1])` for each `i`.\n\nUse this to break value-symmetry on large equivalence classes\n(e.g. interchangeable workers, slots, machines). Every vector\nin `groups` must have the same length and represent one\ncanonical ordering of the variables assigned to each member of\nthe equivalence class.","required":["groups","type"],"properties":{"groups":{"type":"array","items":{"type":"array","items":{"type":"string"}}},"type":{"type":"string","enum":["symmetry_group"]}}},{"type":"object","description":"Declare that the given entity vectors are interchangeable for\nthe purpose of **per-variable feasibility queries** — unlike\n[`SymmetryGroup`], this does NOT add any clauses to the\nformula; it is pure metadata. The per-variable feasibility\nsolver uses it to probe only one representative per orbit and\ncopy the result to the other members, a sound optimisation\nbased on the orbit theorem (two interchangeable variables\nhave provably identical per-var feasibility).\n\n`entities[k]` is the flattened variable vector for entity `k`\n(same length and position-order for all entities). Groups\nwith fewer than two entities, or with mismatched lengths, are\nsilently ignored.\n\nSound for **per-variable feasibility queries**. Do not combine\nwith `SymmetryGroup` on the same variables.","required":["entities","type"],"properties":{"entities":{"type":"array","items":{"type":"array","items":{"type":"string"}}},"type":{"type":"string","enum":["symmetric_observation"]}}},{"type":"object","description":"Define a set variable with lower/upper bounds\nlower: elements that MUST be in the set\nupper: elements that MAY be in the set","required":["variable","lower","upper","type"],"properties":{"lower":{"type":"array","items":{"type":"integer","format":"int64"}},"type":{"type":"string","enum":["set_domain"]},"upper":{"type":"array","items":{"type":"integer","format":"int64"}},"variable":{"type":"string"}}},{"type":"object","description":"Cardinality constraint: |S| = n (exact)","required":["variable","cardinality","type"],"properties":{"cardinality":{"type":"integer","minimum":0},"type":{"type":"string","enum":["set_cardinality_equal"]},"variable":{"type":"string"}}},{"type":"object","description":"Cardinality constraint: |S| >= min","required":["variable","min","type"],"properties":{"min":{"type":"integer","minimum":0},"type":{"type":"string","enum":["set_cardinality_min"]},"variable":{"type":"string"}}},{"type":"object","description":"Cardinality constraint: |S| <= max","required":["variable","max","type"],"properties":{"max":{"type":"integer","minimum":0},"type":{"type":"string","enum":["set_cardinality_max"]},"variable":{"type":"string"}}},{"type":"object","description":"Membership constraint: element ∈ set","required":["element","set","type"],"properties":{"element":{"type":"integer","format":"int64"},"set":{"type":"string"},"type":{"type":"string","enum":["set_member"]}}},{"type":"object","description":"Non-membership constraint: element ∉ set","required":["element","set","type"],"properties":{"element":{"type":"integer","format":"int64"},"set":{"type":"string"},"type":{"type":"string","enum":["set_not_member"]}}},{"type":"object","description":"Subset constraint: a ⊆ b","required":["a","b","type"],"properties":{"a":{"type":"string"},"b":{"type":"string"},"type":{"type":"string","enum":["set_subset"]}}},{"type":"object","description":"Disjoint constraint: a ∩ b = ∅","required":["a","b","type"],"properties":{"a":{"type":"string"},"b":{"type":"string"},"type":{"type":"string","enum":["set_disjoint"]}}},{"type":"object","description":"Union constraint: a ∪ b = result","required":["a","b","result","type"],"properties":{"a":{"type":"string"},"b":{"type":"string"},"result":{"type":"string"},"type":{"type":"string","enum":["set_union"]}}},{"type":"object","description":"Intersection constraint: a ∩ b = result","required":["a","b","result","type"],"properties":{"a":{"type":"string"},"b":{"type":"string"},"result":{"type":"string"},"type":{"type":"string","enum":["set_intersection"]}}},{"type":"object","description":"Difference constraint: a \\ b = result","required":["a","b","result","type"],"properties":{"a":{"type":"string"},"b":{"type":"string"},"result":{"type":"string"},"type":{"type":"string","enum":["set_difference"]}}},{"type":"object","description":"Define a set of OSF terms with bounds and optional sort constraint\n\nUnlike numeric SetDomain, elements are UUIDs referencing actual terms.\nThis enables feature-based constraint checking during search.","required":["variable","lower","upper","type"],"properties":{"allow_subsorts":{"type":"boolean","description":"Whether to allow subsorts of element_sort (default: true)"},"element_sort":{"type":["string","null"],"description":"Optional sort constraint: all elements must be of this sort"},"lower":{"type":"array","items":{"type":"string"},"description":"Term IDs that MUST be in the set (as UUID strings)"},"type":{"type":"string","enum":["osf_set_domain"]},"upper":{"type":"array","items":{"type":"string"},"description":"Term IDs that MAY be in the set (as UUID strings)"},"variable":{"type":"string"}}},{"type":"object","description":"Feature constraint on all set members: ∀t ∈ S. t.feature satisfies constraint\n\nNOT just filtering - this fires DURING SEARCH when terms are forced\ninto sets by propagation. Catches violations as they happen.","required":["set_var","feature_name","constraint","type"],"properties":{"constraint":{"$ref":"#/components/schemas/FeatureConstraintDto","description":"The constraint type and value"},"feature_name":{"type":"string","description":"The feature name to check on each term"},"set_var":{"type":"string","description":"The set variable to constrain"},"type":{"type":"string","enum":["feature_set_constraint"]}}},{"type":"object","description":"Link a term's set-valued feature to an FS variable\n\nThis is where the real power is: propagation through set-valued features.\nLink each consultant's \"skills\" to an FS var, then compute unions/subsets.\nSearch prunes when combined skills can't cover requirements.","required":["term_id","feature_name","set_var","type"],"properties":{"feature_name":{"type":"string","description":"The feature name that holds the set"},"set_var":{"type":"string","description":"The FS variable to link to"},"term_id":{"type":"string","description":"The term whose feature is set-valued (UUID string)"},"type":{"type":"string","enum":["set_feature_link"]}}},{"type":"object","required":["variable","cardinality","type"],"properties":{"cardinality":{"type":"integer","minimum":0},"type":{"type":"string","enum":["osf_set_cardinality_equal"]},"variable":{"type":"string"}}},{"type":"object","required":["variable","min","type"],"properties":{"min":{"type":"integer","minimum":0},"type":{"type":"string","enum":["osf_set_cardinality_min"]},"variable":{"type":"string"}}},{"type":"object","required":["variable","max","type"],"properties":{"max":{"type":"integer","minimum":0},"type":{"type":"string","enum":["osf_set_cardinality_max"]},"variable":{"type":"string"}}},{"type":"object","required":["term","set","type"],"properties":{"set":{"type":"string"},"term":{"type":"string"},"type":{"type":"string","enum":["osf_set_member"]}}},{"type":"object","required":["term","set","type"],"properties":{"set":{"type":"string"},"term":{"type":"string"},"type":{"type":"string","enum":["osf_set_not_member"]}}},{"type":"object","required":["a","b","type"],"properties":{"a":{"type":"string"},"b":{"type":"string"},"type":{"type":"string","enum":["osf_set_subset"]}}},{"type":"object","required":["a","b","type"],"properties":{"a":{"type":"string"},"b":{"type":"string"},"type":{"type":"string","enum":["osf_set_disjoint"]}}},{"type":"object","required":["a","b","result","type"],"properties":{"a":{"type":"string"},"b":{"type":"string"},"result":{"type":"string"},"type":{"type":"string","enum":["osf_set_union"]}}},{"type":"object","required":["a","b","result","type"],"properties":{"a":{"type":"string"},"b":{"type":"string"},"result":{"type":"string"},"type":{"type":"string","enum":["osf_set_intersection"]}}},{"type":"object","required":["a","b","result","type"],"properties":{"a":{"type":"string"},"b":{"type":"string"},"result":{"type":"string"},"type":{"type":"string","enum":["osf_set_difference"]}}}],"description":"A constraint in the space\n\nRenamed from `ConstraintDto` to avoid utoipa schema collision with the\nsort-level `ConstraintDto` (Integer/String/Boolean feature constraints)."},"SpaceResponse":{"type":"object","description":"Response when creating or querying a space","required":["id","status","constraint_count"],"properties":{"constraint_count":{"type":"integer","description":"Number of constraints in the space","minimum":0},"id":{"type":"string","description":"Unique ID of the space"},"selected_alternative":{"type":["integer","null"],"description":"Selected alternative (if any)","minimum":0},"status":{"$ref":"#/components/schemas/SpaceStatusDto","description":"Current status"}}},"SpaceSolutionDto":{"type":"object","description":"A solution from a search","required":["space_id","status","choices"],"properties":{"choices":{"type":"array","items":{"$ref":"#/components/schemas/ChoiceSelection"},"description":"The choices made at each choice point"},"events":{"type":["array","null"],"items":{"$ref":"#/components/schemas/TraceEventDto"},"description":"Trace events (e.g., LIFE feature creation)"},"space_id":{"type":"string","description":"ID of the space containing this solution"},"status":{"$ref":"#/components/schemas/SpaceStatusDto","description":"Status (should be Succeeded)"}}},"SpaceStatusDto":{"oneOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["running"]}}},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["failed"]}}},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["succeeded"]}}},{"type":"object","required":["count","type"],"properties":{"count":{"type":"integer","minimum":0},"type":{"type":"string","enum":["alternatives"]}}}],"description":"Status of a computation space"},"SpecificityDto":{"type":"object","description":"Volume-specificity verification sub-DTO.","required":["total_parent_child_pairs","pairs_volume_correct","spearman_correlation","violation_count"],"properties":{"pairs_volume_correct":{"type":"integer","description":"Pairs where child volume < parent volume.","minimum":0},"spearman_correlation":{"type":"number","format":"double","description":"Spearman rank correlation between depth and -log_volume."},"total_parent_child_pairs":{"type":"integer","description":"Number of parent-child pairs checked.","minimum":0},"violation_count":{"type":"integer","description":"Number of violations.","minimum":0}}},"StartExplorationRequestDto":{"type":"object","description":"Request to start a new attribute exploration session.\n\nPOST /api/v1/analysis/attribute-exploration/start","properties":{"max_concepts":{"type":"integer","description":"Maximum number of formal concepts to enumerate (default: 10_000)","minimum":0},"max_terms":{"type":"integer","description":"Maximum number of terms to include in the context (default: 50_000)","minimum":0},"min_extent_size":{"type":"integer","description":"Minimum extent size (number of terms sharing the feature set) (default: 2)","minimum":0},"min_intent_size":{"type":"integer","description":"Minimum intent size (number of features in a concept) (default: 1)","minimum":0}}},"StartExplorationResponseDto":{"type":"object","description":"Response after starting an exploration session.","required":["session_id","attribute_count","object_count"],"properties":{"attribute_count":{"type":"integer","description":"Number of attributes (features) in the formal context","minimum":0},"object_count":{"type":"integer","description":"Number of objects (terms) in the formal context","minimum":0},"question":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ExplorationQuestionDto","description":"First implication question (None if exploration is immediately complete)"}]},"session_id":{"type":"string","description":"Unique session identifier (UUID)"}}},"StartIngestionSessionRequest":{"type":"object","description":"Request to start a new ingestion session","required":["document_ids"],"properties":{"document_ids":{"type":"array","items":{"type":"string"},"description":"List of document IDs that will be ingested in this session"}}},"StatisticalSuccessResponse":{"type":"object","description":"Simple success response for stateless operations (reset, clear).","required":["success","message"],"properties":{"message":{"type":"string","description":"Status message"},"success":{"type":"boolean","description":"Whether the operation was successful"}}},"StepLogEntryDto":{"type":"object","description":"A timestamped log entry from a pipeline step.","required":["timestamp","step","message"],"properties":{"message":{"type":"string","description":"Human-readable description of what happened."},"step":{"type":"string","description":"Pipeline step that produced this event."},"timestamp":{"type":"string","description":"When this event occurred (ISO 8601)."}}},"StepVerificationResponse":{"type":"object","description":"Response from ingesting a step (incremental verification result).","required":["step_index","incremental_verdict","incremental_score","total_steps"],"properties":{"alerts":{"type":"array","items":{"$ref":"#/components/schemas/OversightAlertDto"},"description":"Alerts triggered by this step"},"incremental_score":{"type":"number","format":"double","description":"Incremental overall score (0.0-1.0)"},"incremental_verdict":{"type":"string","description":"Incremental verdict after this step: \"safe\", \"unsafe\", \"partial\", or \"residuated\""},"step_index":{"type":"integer","description":"Index of the ingested step","minimum":0},"total_steps":{"type":"integer","description":"Total steps ingested so far","minimum":0}}},"StorePlanRequest":{"type":"object","description":"Request to store a plan in the library.","required":["tenant_id","agent_id","goal_id","actions"],"properties":{"actions":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Sequence of action IDs"},"agent_id":{"type":"string","format":"uuid","description":"Agent ID"},"goal_id":{"type":"string","format":"uuid","description":"Goal this plan achieves"},"initial_outcome":{"type":["boolean","null"],"description":"Initial outcome (optional)"},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"}}},"StorePlanResponse":{"type":"object","description":"Response after storing a plan.","required":["plan_id","message"],"properties":{"message":{"type":"string","description":"Success message"},"plan_id":{"type":"string","format":"uuid","description":"Created plan template ID"}}},"StringCompareOperator":{"type":"string","description":"Wild_Life string comparison operators","enum":["lt","gt","le","ge","eq","ne"]},"StringComparePredicateRequest":{"type":"object","description":"Request for Wild_Life-style string comparison predicate\nThese return success/failure like Wild_LIFE predicates (not ordering)","required":["string1","string2","operator"],"properties":{"operator":{"$ref":"#/components/schemas/StringCompareOperator","description":"Comparison operator"},"string1":{"type":"string","description":"First string operand"},"string2":{"type":"string","description":"Second string operand"}}},"StringComparePredicateResponse":{"type":"object","description":"Response from Wild_Life-style string comparison predicate","required":["success","operator","explanation"],"properties":{"explanation":{"type":"string","description":"Human-readable explanation"},"operator":{"$ref":"#/components/schemas/StringCompareOperator","description":"The operator used"},"success":{"type":"boolean","description":"Whether the comparison succeeded (like Wild_LIFE success/failure)"}}},"StringCompareRequest":{"type":"object","description":"Request for string comparison","required":["string1","string2"],"properties":{"ignore_case":{"type":"boolean","description":"If true, comparison is case-insensitive"},"string1":{"type":"string"},"string2":{"type":"string"}}},"StringCompareResponse":{"type":"object","description":"Response from string comparison","required":["ordering","are_equal"],"properties":{"are_equal":{"type":"boolean"},"ordering":{"type":"integer","format":"int32","description":"-1 if string1 < string2, 0 if equal, 1 if string1 > string2"}}},"StringConcatRequest":{"type":"object","description":"Request for string concatenation","required":["string1","string2"],"properties":{"string1":{"type":"string"},"string2":{"type":"string"}}},"StringConcatResponse":{"type":"object","description":"Response from string concatenation","required":["result"],"properties":{"result":{"type":"string"}}},"StringLengthRequest":{"type":"object","description":"Request for string length","required":["string_value"],"properties":{"string_value":{"type":"string"}}},"StringLengthResponse":{"type":"object","description":"Response from string length","required":["length"],"properties":{"length":{"type":"integer","format":"int64"}}},"StringOpParams":{"type":"object","description":"Parameters for string operations","properties":{"delimiter":{"type":["string","null"]},"index":{"type":["integer","null"],"minimum":0},"replacement":{"type":["string","null"]},"search":{"type":["string","null"]}}},"StringOpRequest":{"type":"object","description":"Request for general string operation","required":["operation","string_value"],"properties":{"operation":{"$ref":"#/components/schemas/StringOperationType"},"params":{"$ref":"#/components/schemas/StringOpParams","description":"Additional parameters for operations that need them"},"string_value":{"type":"string"}}},"StringOpResponse":{"oneOf":[{"type":"object","required":["result","type"],"properties":{"result":{"type":"string"},"type":{"type":"string","enum":["string"]}}},{"type":"object","required":["result","type"],"properties":{"result":{"type":"string"},"type":{"type":"string","enum":["char"]}}},{"type":"object","required":["result","type"],"properties":{"result":{"type":"integer","format":"int64"},"type":{"type":"string","enum":["integer"]}}},{"type":"object","required":["result","type"],"properties":{"result":{"type":"boolean"},"type":{"type":"string","enum":["boolean"]}}},{"type":"object","required":["result","type"],"properties":{"result":{"type":"array","items":{"type":"string"}},"type":{"type":"string","enum":["strings"]}}},{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["not_found"]}}}],"description":"Response from string operation"},"StringOperationType":{"type":"string","description":"String operation types","enum":["to_upper","to_lower","trim","trim_start","trim_end","reverse","char_at","index_of","replace","split","contains","starts_with","ends_with"]},"StructuredIngestionStatsDto":{"type":"object","description":"Structured ingestion statistics.","required":["tables_discovered","columns_discovered","relations_discovered","sorts_created","entities_extracted","entities_created","relations_created","terms_created","documents_rendered","records_processed","elapsed_ms"],"properties":{"columns_discovered":{"type":"integer","description":"Number of columns discovered","minimum":0},"documents_rendered":{"type":"integer","description":"Number of documents rendered and processed","minimum":0},"elapsed_ms":{"type":"integer","format":"int64","description":"Total elapsed time in milliseconds","minimum":0},"entities_created":{"type":"integer","description":"Number of entities created","minimum":0},"entities_extracted":{"type":"integer","description":"Number of entities extracted (from pipeline)","minimum":0},"records_processed":{"type":"integer","description":"Number of source records processed","minimum":0},"relations_created":{"type":"integer","description":"Number of relations created","minimum":0},"relations_discovered":{"type":"integer","description":"Number of relations discovered","minimum":0},"sorts_created":{"type":"integer","description":"Number of sorts created (from pipeline)","minimum":0},"tables_discovered":{"type":"integer","description":"Number of types/tables discovered","minimum":0},"terms_created":{"type":"integer","description":"Number of terms created","minimum":0}}},"SubscribeToKbRequest":{"type":"object","description":"Request to subscribe agent to KB changes.","required":["agent_id","tenant_id","watched_sorts"],"properties":{"agent_id":{"type":"string","format":"uuid","description":"Agent ID"},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"},"watched_features":{"type":"array","items":{"type":"string"},"description":"Feature names to watch for changes"},"watched_sorts":{"type":"array","items":{"type":"string"},"description":"Sort names to watch for changes"}}},"SubscribeToKbResponse":{"type":"object","description":"Response from KB subscription.","required":["success","subscription_id","message"],"properties":{"message":{"type":"string","description":"Message"},"subscription_id":{"type":"string","format":"uuid","description":"Subscription ID"},"success":{"type":"boolean","description":"Success status"}}},"SubstringRequest":{"type":"object","description":"Request for substring","required":["string_value","start","length"],"properties":{"length":{"type":"integer","minimum":0},"start":{"type":"integer","minimum":0},"string_value":{"type":"string"}}},"SubstringResponse":{"type":"object","description":"Response from substring","required":["result"],"properties":{"result":{"type":"string"}}},"SuspendedQueryDto":{"type":"object","description":"Information about a suspended (incomplete) query","required":["confidence","missing_info","resumption_options"],"properties":{"confidence":{"type":"number","format":"double","description":"Confidence in partial results"},"missing_info":{"type":"array","items":{"$ref":"#/components/schemas/MissingInfoDto"},"description":"What information is missing"},"resumption_options":{"type":"array","items":{"$ref":"#/components/schemas/ResumptionOptionDto"},"description":"Suggested refinements"}}},"SymbolDto":{"type":"object","description":"A module symbol","required":["name","visibility","kind"],"properties":{"doc":{"type":["string","null"]},"kind":{"$ref":"#/components/schemas/SymbolKindDto"},"name":{"type":"string"},"visibility":{"$ref":"#/components/schemas/VisibilityDto"}}},"SymbolKindDto":{"oneOf":[{"type":"object","required":["sort_id","type"],"properties":{"sort_id":{"type":"string"},"type":{"type":"string","enum":["sort"]}}},{"type":"object","required":["arity","evaluable","type"],"properties":{"arity":{"type":"integer","minimum":0},"evaluable":{"type":"boolean"},"type":{"type":"string","enum":["function"]}}},{"type":"object","required":["arity","type"],"properties":{"arity":{"type":"integer","minimum":0},"type":{"type":"string","enum":["predicate"]}}},{"type":"object","required":["value","type"],"properties":{"type":{"type":"string","enum":["constant"]},"value":{"$ref":"#/components/schemas/AssignValueDto"}}},{"type":"object","required":["module_name","type"],"properties":{"module_name":{"type":"string"},"type":{"type":"string","enum":["module"]}}}],"description":"Symbol kind"},"SymbolicResultDto":{"type":"object","description":"Summary of symbolic forward chaining result.","required":["total_facts","derived_count","iterations","fixpoint_reached"],"properties":{"derived_count":{"type":"integer","minimum":0},"fixpoint_reached":{"type":"boolean"},"iterations":{"type":"integer","minimum":0},"total_facts":{"type":"integer","minimum":0}}},"SynthesizeRequest":{"type":"object","description":"Request for neural-guided ILP synthesis.","required":["target_sort","examples"],"properties":{"examples":{"type":"array","items":{"$ref":"#/components/schemas/TrainingExample"},"description":"Training examples as input/output pairs."},"max_proposals":{"type":["integer","null"],"description":"Maximum proposals to try.","minimum":0},"target_sort":{"type":"string","description":"Target sort name to synthesize rules for."},"use_gflownet":{"type":"boolean","description":"Whether to use GFlowNet-guided sampling."}}},"SynthesizeResponse":{"type":"object","description":"Response from neural-guided synthesis.","required":["success","proposals_tried","gflownet_hypotheses_sampled","neural_guide_available","processing_time_ms"],"properties":{"error":{"type":["string","null"],"description":"Error message (if failed)."},"found_by":{"type":["string","null"],"description":"How the solution was found (if successful)."},"gflownet_hypotheses_sampled":{"type":"integer","description":"Number of GFlowNet hypotheses sampled.","minimum":0},"neural_guide_available":{"type":"boolean","description":"Whether GFlowNet neural guide was available."},"processing_time_ms":{"type":"integer","description":"Processing time in milliseconds.","minimum":0},"proposals_tried":{"type":"integer","description":"Number of proposals tried.","minimum":0},"success":{"type":"boolean","description":"Whether synthesis succeeded."}}},"TaggedDerivedFact":{"type":"object","description":"A derived fact with its provenance tag.","required":["term_id","confidence","is_initial"],"properties":{"confidence":{"type":"number","format":"double","description":"Provenance confidence in [0.0, 1.0]."},"is_initial":{"type":"boolean","description":"Whether this was an initial fact (axiom) or newly derived."},"sort_name":{"type":["string","null"],"description":"The sort name of the derived fact."},"term_id":{"type":"string","format":"uuid","description":"The term ID of the derived fact."}}},"TaggedFactDto":{"type":"object","description":"A fact with a probabilistic semiring tag.","required":["term_id","sort_name","probability"],"properties":{"probability":{"type":"number","format":"double"},"sort_name":{"type":"string"},"term_id":{"type":"string","format":"uuid"}}},"TaggedFcRequest":{"type":"object","description":"Request for tagged forward chaining (Phase 1).","properties":{"max_iterations":{"type":"integer","format":"int32","description":"Maximum forward chaining iterations (default: 50).","minimum":0}}},"TaggedFcResponse":{"type":"object","description":"Response for tagged forward chaining.","required":["tagged_facts","iterations","fixpoint_reached","derived_count","elapsed_ms"],"properties":{"derived_count":{"type":"integer","description":"Number of derived facts (excluding initial).","minimum":0},"elapsed_ms":{"type":"integer","format":"int64","description":"Elapsed time in milliseconds.","minimum":0},"fixpoint_reached":{"type":"boolean","description":"Whether fixpoint was reached."},"iterations":{"type":"integer","description":"Number of derivation iterations.","minimum":0},"tagged_facts":{"type":"array","items":{"$ref":"#/components/schemas/TaggedFactDto"},"description":"Tagged facts with probabilistic provenance."}}},"TaggedFeatureValueDto":{"oneOf":[{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","enum":["String"]},"value":{"type":"string"}}},{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","enum":["Integer"]},"value":{"type":"integer","format":"int64"}}},{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","enum":["Real"]},"value":{"type":"number","format":"double"}}},{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","enum":["Boolean"]},"value":{"type":"boolean"}}},{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","enum":["Reference"]},"value":{"type":"string","format":"uuid"}}},{"type":"object","required":["type","value"],"properties":{"type":{"type":"string","enum":["List"]},"value":{"type":"array","items":{"$ref":"#/components/schemas/TaggedFeatureValueDto"}}}}],"title":"TaggedFeatureValueDto","description":"Typed value for OSF feature constraints. Adjacently tagged with 'type' and 'value' fields. Variants: String, Integer, Real, Boolean, Reference, List.","discriminator":{"propertyName":"type"}},"TaggedForwardChainRequest":{"type":"object","description":"Request body for the tagged forward chain endpoint.","properties":{"fact_confidences":{"type":"array","items":{"$ref":"#/components/schemas/FactConfidenceEntry"},"description":"Initial fact confidence values (term_id → probability).\nFacts not listed here default to 1.0 (certain)."},"max_facts":{"type":"integer","description":"Maximum facts to derive before stopping.","minimum":0},"max_iterations":{"type":"integer","description":"Maximum iterations for forward chaining.","minimum":0}}},"TaggedForwardChainResponse":{"type":"object","description":"Response for the tagged forward chain endpoint.","required":["total_facts","derived_count","facts","iterations","fixpoint_reached","execution_time_ms"],"properties":{"derived_count":{"type":"integer","description":"Number of newly derived facts (excluding initial).","minimum":0},"execution_time_ms":{"type":"integer","description":"Execution time in milliseconds.","minimum":0},"facts":{"type":"array","items":{"$ref":"#/components/schemas/TaggedDerivedFact"},"description":"Derived facts with provenance tags."},"fixpoint_reached":{"type":"boolean","description":"Whether fixpoint was reached."},"iterations":{"type":"integer","description":"Number of iterations performed.","minimum":0},"total_facts":{"type":"integer","description":"Total facts after materialization (initial + derived).","minimum":0}}},"TaskDto":{"type":"object","description":"A task in the decomposed network.","required":["task_id","is_primitive","subtasks"],"properties":{"is_primitive":{"type":"boolean","description":"Whether this is a primitive (directly executable) task"},"subtasks":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Subtasks (if not primitive)"},"task_id":{"type":"string","format":"uuid","description":"Task ID"}}},"TemporalPlanRequest":{"type":"object","description":"Request for temporal planning with diversity constraints","required":["sort_id","num_selections"],"properties":{"distance_metric":{"type":["string","null"],"description":"Distance metric for proximity optimization.\n\nDetermines how distance between field values is computed:\n- `\"categorical\"` (default): exact string match (0.0 = same, 1.0 = different).\n Suitable for cuisine types, categories, or any discrete field.\n- `\"geographical\"`: haversine GPS distance. Expects `group_by_field` values\n to be `\"latitude,longitude\"` strings (e.g., `\"37.7749,-122.4194\"`).\n Normalised by `max_distance_km` (default 100 km).\n- `\"temporal\"`: time difference in minutes.\n\nWhen absent or null, defaults to `\"categorical\"` for backward compatibility."},"fuzzy_query":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/QueryTerm","description":"Optional fuzzy query for automatic top-k scoring\nIf provided, performs fuzzy matching against all candidates and uses similarity scores"}]},"group_by_field":{"type":["string","null"],"description":"Optional field to group by for proximity optimization (e.g., \"gps_location\")"},"max_distance_km":{"type":["number","null"],"format":"double","description":"Maximum distance in kilometres for geographical distance normalisation.\n\nOnly used when `distance_metric` is `\"geographical\"`.\nDefault: 100.0 (typical metropolitan area)."},"min_degree":{"type":["number","null"],"format":"double","description":"Minimum similarity degree for fuzzy query (default: 0.0)"},"no_repeat_fields":{"type":["array","null"],"items":{"type":"string"},"description":"Optional fields that must have unique values across selections (e.g., [\"cuisine\"])\nWhen None or empty, allows same term to be selected multiple times"},"num_selections":{"type":"integer","description":"Number of terms to select (e.g., 7 for weekly plan)","minimum":0},"proximity_weight":{"type":["number","null"],"format":"double","description":"Weight for proximity optimization (0.0-1.0, default: 0.0 = no proximity)"},"sequence_by_field":{"type":["string","null"],"description":"Optional field to sort results by (e.g., \"prep_time\" for ascending order)\nWhen provided, the selected terms will be ordered by this field's value"},"sort_id":{"type":"string","format":"uuid","description":"Sort ID to select terms from (e.g., recipe sort)"},"top_k":{"type":["object","null"],"description":"Optional quality scores for top-k selection (term_id -> score)\nWhen provided, selects highest-quality diverse candidates","additionalProperties":{"type":"number","format":"double"},"propertyNames":{"type":"string","format":"uuid"}}}},"TemporalPlanResponse":{"type":"object","description":"Response from temporal planning","required":["selected_term_ids","diversity_score","candidates_count","computation_time_ms"],"properties":{"candidates_count":{"type":"integer","description":"Number of candidates evaluated","minimum":0},"computation_time_ms":{"type":"integer","format":"int64","description":"Computation time in milliseconds","minimum":0},"diversity_score":{"type":"number","format":"double","description":"Diversity score (0.0 to 1.0, higher is more diverse)"},"proximity_score":{"type":["number","null"],"format":"double","description":"Proximity score (0.0 to 1.0, higher means better clustering), if proximity was requested"},"selected_term_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Selected term IDs in temporal order"}}},"TenantInfo":{"type":"object","description":"Information about a single tenant in the system.","required":["tenant_id","term_count","session_count"],"properties":{"session_count":{"type":"integer","format":"int64","description":"Number of ingestion sessions for this tenant"},"tenant_id":{"type":"string","description":"The tenant UUID"},"term_count":{"type":"integer","format":"int64","description":"Number of terms owned by this tenant"}}},"TermBindingDto":{"type":"object","description":"A term binding","required":["term_id","sort_id","features"],"properties":{"features":{"type":"array","items":{"$ref":"#/components/schemas/FeatureBindingDto"}},"sort_id":{"type":"string"},"term_id":{"type":"string"}}},"TermDto":{"type":"object","description":"API representation of a term","required":["id","sort_id","tenant_id","owner_id","features"],"properties":{"display_name":{"type":["string","null"],"description":"Human-readable display name extracted from features (name/label/title/...)"},"features":{"type":"object","description":"Features map","additionalProperties":{"$ref":"#/components/schemas/ValueDto"},"propertyNames":{"type":"string"}},"id":{"type":"string","format":"uuid","description":"Term ID"},"owner_id":{"type":"string","format":"uuid","description":"Owner ID"},"referenced_terms":{"type":"object","description":"Summaries of referenced terms — maps UUID string to display info.\nEnriched at API layer via DomainTermStore lookups, zero extra I/O.","additionalProperties":{"$ref":"#/components/schemas/ReferencedTermSummary"},"propertyNames":{"type":"string"}},"sort_id":{"type":"string","format":"uuid","description":"Sort ID"},"sort_name":{"type":["string","null"],"description":"Human-readable sort name (enriched at API layer via SortHierarchy lookup)"},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"}}},"TermExistsResponse":{"type":"object","description":"Response for term existence check","required":["exists"],"properties":{"exists":{"type":"boolean","description":"Whether the term exists"}}},"TermInputDto":{"oneOf":[{"type":"object","title":"Reference","description":"Reference an existing term by ID","required":["term_id"],"properties":{"term_id":{"type":"string","format":"uuid"}}},{"type":"object","title":"Inline","description":"Define a term inline with sort ID","required":["sort_id","features"],"properties":{"features":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/FeatureInputValueDto"}},"sort_id":{"type":"string","format":"uuid"}}},{"type":"object","title":"InlineByName","description":"Define a term inline with sort name (resolved server-side)","required":["sort_name"],"properties":{"features":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/FeatureInputValueDto"}},"sort_name":{"type":"string"}}}],"title":"TermInputDto","description":"Input for creating/referencing a term (TRUE HOMOICONICITY). Either:\n- {term_id: UUID} to reference an existing term, OR\n- {sort_id: UUID, features: {...}} to define inline with sort ID, OR\n- {sort_name: String, features: {...}} to define inline with sort name (resolved server-side)"},"TermListResponse":{"type":"object","description":"Response for term list operations","required":["terms","count"],"properties":{"count":{"type":"integer","description":"Total count","minimum":0},"terms":{"type":"array","items":{"$ref":"#/components/schemas/TermDto"},"description":"List of terms"}}},"TermPatternDto":{"type":"object","description":"Term pattern for unification queries","required":["sort_id","features"],"properties":{"features":{"type":"object","description":"Features to match","additionalProperties":{"$ref":"#/components/schemas/ValueDto"},"propertyNames":{"type":"string"}},"sort_id":{"type":"string","format":"uuid","description":"Sort ID of the pattern"}}},"TermResponse":{"type":"object","description":"Response for term operations","required":["term"],"properties":{"residual_witnesses":{"type":"array","items":{"$ref":"#/components/schemas/ResidualWitnessDto"},"description":"Residuated witnesses (if residuated)"},"state":{"$ref":"#/components/schemas/TermState","description":"Term state (complete, residuated, or no_witnesses)"},"term":{"$ref":"#/components/schemas/TermDto","description":"The term"},"witness_proofs":{"type":"array","items":{"$ref":"#/components/schemas/WitnessProofDto"},"description":"Witness proofs (if complete)"}}},"TermState":{"type":"string","description":"Term completion state (Hassan's LIFE semantics)","enum":["complete","residuated","no_witnesses"]},"TermStoreSessionResponse":{"type":"object","description":"Response with term store session info","required":["session_id","tenant_id","term_count","variable_count"],"properties":{"session_id":{"type":"string"},"tenant_id":{"type":"string","format":"uuid"},"term_count":{"type":"integer","minimum":0},"variable_count":{"type":"integer","minimum":0}}},"TermTranslationDto":{"type":"object","description":"Term ID translation entry","required":["original_id","copied_id"],"properties":{"copied_id":{"type":"string"},"original_id":{"type":"string"}}},"TokenUsageDto":{"type":"object","description":"Token usage from LLM API calls during ingestion","required":["input_tokens","output_tokens","cache_read_tokens","cache_creation_tokens","total_tokens"],"properties":{"cache_creation_tokens":{"type":"integer","format":"int64","description":"Tokens written to prompt cache","minimum":0},"cache_read_tokens":{"type":"integer","format":"int64","description":"Tokens served from prompt cache (reduces cost)","minimum":0},"input_tokens":{"type":"integer","format":"int64","description":"Input tokens sent to the LLM","minimum":0},"output_tokens":{"type":"integer","format":"int64","description":"Output tokens received from the LLM","minimum":0},"total_tokens":{"type":"integer","format":"int64","description":"Total tokens (input + output)","minimum":0}}},"ToolCallInfo":{"type":"object","description":"Tool call information (for constraint mode)","required":["name","arguments","confidence"],"properties":{"arguments":{"description":"Tool arguments"},"confidence":{"type":"number","format":"double","description":"Translation confidence (0.0 - 1.0)"},"name":{"type":"string","description":"Tool name that was invoked"}}},"TraceEventDto":{"type":"object","description":"Trace event payload","required":["assignment","value_label","id","event_type"],"properties":{"assignment":{"type":"string"},"event_type":{"type":"string","description":"'feature_created' | 'feature_verified' | 'feature_conflict'"},"id":{"type":"integer","format":"int64"},"value_label":{"type":"integer","format":"int64"},"variable":{"type":["string","null"]}}},"TrailEntryDto":{"oneOf":[{"type":"object","required":["term_id","feature_name","type"],"properties":{"feature_name":{"type":"string"},"previous_value":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/ExecutionValueDto"}]},"term_id":{"type":"string"},"type":{"type":"string","enum":["term_binding"]}}},{"type":"object","required":["var_id","type"],"properties":{"previous_binding":{"type":["string","null"]},"type":{"type":"string","enum":["variable_binding"]},"var_id":{"type":"string"}}},{"type":"object","required":["term_id","previous_sort","type"],"properties":{"previous_sort":{"type":"string"},"term_id":{"type":"string"},"type":{"type":"string","enum":["sort_narrowing"]}}},{"type":"object","required":["term_id","feature_name","type"],"properties":{"feature_name":{"type":"string"},"term_id":{"type":"string"},"type":{"type":"string","enum":["feature_addition"]}}},{"type":"object","required":["term_id","type"],"properties":{"previous_coref":{"type":["string","null"]},"term_id":{"type":"string"},"type":{"type":"string","enum":["coref_change"]}}},{"type":"object","required":["var_id","prev_lower","prev_upper","type"],"properties":{"prev_lower":{"type":"string"},"prev_upper":{"type":"string"},"type":{"type":"string","enum":["rational_bounds_change"]},"var_id":{"type":"string"}}}],"description":"Trail entry DTO"},"TrainFromTracesResponse":{"type":"object","description":"Response for the train-from-traces endpoint.","required":["triggered","traces_consumed","loss"],"properties":{"error":{"type":["string","null"],"description":"Error message if training failed to trigger."},"loss":{"type":"number","format":"float","description":"Final training loss (0.0 if no traces were consumed)."},"traces_consumed":{"type":"integer","description":"Number of traces consumed from the buffer.","minimum":0},"triggered":{"type":"boolean","description":"Whether training was triggered."}}},"TrainingExample":{"type":"object","description":"A single training example for inductive learning.","required":["input","output"],"properties":{"input":{"type":"integer","format":"int64","description":"Input value (e.g., n for factorial(n))"},"output":{"type":"integer","format":"int64","description":"Output value (e.g., n! for factorial)"}}},"TrainingExampleDto":{"type":"object","description":"A single serialized training example.","required":["id","input","output","format","polarity","source"],"properties":{"faithfulness_score":{"type":["number","null"],"format":"double","description":"Faithfulness verification score."},"format":{"type":"string","description":"Training pair format (Extraction, QuestionAnswer, FillBlank, Negative, MultiHop)."},"generation_method":{"type":["string","null"],"description":"Generation method used."},"id":{"type":"string","description":"Unique example identifier (e.g., \"synth_000001\")."},"input":{"type":"string","description":"Input text (natural language or structured)."},"output":{"type":"string","description":"Expected output (entities, relations, answers)."},"polarity":{"type":"string","description":"Polarity (Positive or Negative)."},"sort_name":{"type":["string","null"],"description":"Sort name for sort-specific pairs."},"source":{"type":"string","description":"Data source (real, synthetic, negative)."}}},"TrainingTriggerResponse":{"type":"object","description":"Response for training trigger endpoints.","required":["triggered"],"properties":{"error":{"type":["string","null"],"description":"Error message if training failed to trigger."},"result":{"type":["object","null"],"description":"Training result (None if subsystem is disabled)."},"triggered":{"type":"boolean","description":"Whether the training was triggered successfully."}}},"TrajectoryStepDto":{"type":"object","description":"A single step in the agent's execution trajectory.\n\nPaper Table 5: Information extracted from agent execution trajectories.","required":["action"],"properties":{"action":{"type":"string","description":"Action/tool name executed"},"agent_id":{"type":["string","null"],"description":"Agent identifier for multi-agent systems (CrewAI, AutoGen, OpenAI Agents SDK)"},"agent_name":{"type":["string","null"],"description":"Human-readable agent name for multi-agent systems"},"error":{"type":["string","null"],"description":"Error message if the tool call failed"},"file_content":{"type":["string","null"],"description":"Actual content returned by file-reading tools (paper Table 5: tool_calls[].result)"},"input":{"description":"Tool input parameters (JSON)"},"output":{"description":"Tool output/result (JSON)"},"success":{"type":["boolean","null"],"description":"Whether the tool call succeeded"},"timestamp":{"type":["string","null"],"description":"ISO 8601 timestamp of the step"},"tool_used":{"type":["string","null"],"description":"Specific tool identifier (if different from action)"}}},"TranslateShaclRequest":{"type":"object","description":"Request: translate one or more SHACL shapes into homoiconic OSF rules.","required":["shapes"],"properties":{"shapes":{"type":"array","items":{"$ref":"#/components/schemas/ShaclShapeDto"},"description":"Shapes to translate."}}},"TranslateShaclResponse":{"type":"object","description":"Response: a summary of the generated rules.","required":["translated","total_rule_count"],"properties":{"total_rule_count":{"type":"integer","description":"Total rules generated across all shapes.","minimum":0},"translated":{"type":"array","items":{"$ref":"#/components/schemas/TranslatedShapeDto"},"description":"Per-shape translation result."}}},"TranslatedRuleDto":{"type":"object","description":"One homoiconic rule's user-facing summary.","required":["kind","feature_path"],"properties":{"feature_path":{"type":"string","description":"Feature path the facet targets."},"kind":{"type":"string","description":"Facet kind: `\"min_count\"`, `\"max_count\"`, `\"datatype\"`, `\"min_inclusive\"`,\n`\"max_inclusive\"`."}}},"TranslatedShapeDto":{"type":"object","description":"Per-shape output summary.","required":["target_class","rules"],"properties":{"rules":{"type":"array","items":{"$ref":"#/components/schemas/TranslatedRuleDto"},"description":"One entry per generated rule with the facet kind + feature path."},"target_class":{"type":"string","description":"Echo of the target class name."}}},"TranspileRequest":{"type":"object","description":"Request to transpile an OSFQL query to SQL.","required":["osfql"],"properties":{"dialect":{"type":"string","description":"SQL dialect: \"postgres\", \"mysql\", or \"sqlite\"."},"osfql":{"type":"string","description":"OSFQL query to transpile."}}},"TranspileResponse":{"type":"object","description":"Response from OSFQL-to-SQL transpilation.","required":["sql","param_count","fully_transpilable"],"properties":{"fully_transpilable":{"type":"boolean","description":"Whether the entire plan is SQL-transpilable."},"param_count":{"type":"integer","description":"Number of parameters in the generated SQL.","minimum":0},"source_id":{"type":["string","null"],"description":"Source ID the query targets."},"sql":{"type":"string","description":"Generated SQL query."}}},"TriggerDependencyRequest":{"type":"object","description":"Request for trigger dependency graph","properties":{"generate_dot":{"type":"boolean","description":"Whether to generate DOT output"},"residuation_id":{"type":["string","null"],"description":"Focus on specific residuation ID"}}},"TriggerDependencyResponse":{"type":"object","description":"Response for trigger dependency graph","required":["graph","critical_paths"],"properties":{"critical_paths":{"type":"array","items":{"type":"array","items":{"type":"string"}},"description":"Critical paths (longest dependency chains)"},"graph":{"$ref":"#/components/schemas/VisualizationGraphDto","description":"The visualization graph"}}},"TrizInventRequest":{"type":"object","description":"Request body for `POST /api/v1/triz/invent` — the structured-input,\nno-LLM path into the TRIZ invention engine.","required":["tenant_id","improving_parameter","worsening_parameter"],"properties":{"domain_context":{"type":"string","description":"Human-readable context (e.g. \"drug_discovery\", \"kinase_program_279\").\nThe engine uses this in explanations but not in the reasoning."},"domains":{"type":"array","items":{"type":"string"},"description":"Sort names the caller has pre-seeded under this tenant. Required:\nwithout them the KB-matching step (`query_kb_for_triz_data`) has\nno domain hints and falls through to the LLM-synthetic path —\ndefeating the purpose of this endpoint."},"improving_parameter":{"type":"string"},"tenant_id":{"type":"string","format":"uuid"},"worsening_parameter":{"type":"string"}}},"TrizRecordOutcomeRequest":{"type":"object","description":"Request body for `POST /api/v1/triz/record-outcome`.","required":["tenant_id","invention_term_id","success"],"properties":{"invention_term_id":{"type":"string","format":"uuid","description":"UUID of the ``triz_inventive_proposal`` term the engine emitted."},"measured_ratio":{"type":"number","format":"double","description":"Measured performance ratio (e.g. potency fold, selectivity\nfold). ``0.0`` if unmeasured — the engine still records the\nsuccess/failure signal."},"notes":{"type":"string","description":"Free-text notes on the outcome for downstream audit."},"success":{"type":"boolean","description":"Whether the invention succeeded in downstream validation /\nexperimental testing."},"tenant_id":{"type":"string","format":"uuid"}}},"TrizRecordOutcomeResponse":{"type":"object","description":"Response payload for outcome recording.","required":["success","recorded","mappings_updated","updated_confidence"],"properties":{"error":{"type":["string","null"]},"mappings_updated":{"type":"integer","description":"Number of learned-mapping terms whose confidence was adjusted.","minimum":0},"outcome_term_id":{"type":["string","null"],"format":"uuid","description":"UUID of the newly-created ``triz_invention_outcome`` audit term."},"recorded":{"type":"boolean"},"success":{"type":"boolean"},"updated_confidence":{"type":"number","format":"double","description":"New post-update average confidence across the adjusted mappings."}}},"TurnDto":{"type":"object","description":"A single conversation turn (message).","required":["id","role","content","timestamp"],"properties":{"claim_annotations":{"type":["array","null"],"items":{"$ref":"#/components/schemas/ClaimAnnotationDto"},"description":"Per-claim provenance annotations (assistant turns only)."},"content":{"type":"string","description":"Message content."},"id":{"type":"string","description":"Turn ID."},"intent":{"type":["string","null"],"description":"Classified intent (assistant turns only)."},"osfql":{"type":["string","null"],"description":"OSFQL generated (assistant turns only)."},"role":{"type":"string","description":"\"user\" or \"assistant\"."},"timestamp":{"type":"string","description":"ISO 8601 timestamp."}}},"UIActionDto":{"oneOf":[{"type":"object","description":"Submit form data via OSFQL INSERT","required":["sort_name","osfql_template","field_types","type"],"properties":{"field_types":{"type":"object","additionalProperties":{"type":"string"},"propertyNames":{"type":"string"}},"osfql_template":{"type":"string"},"sort_name":{"type":"string"},"type":{"type":"string","enum":["submit_form"]}}},{"type":"object","description":"Load tabular data via OSFQL MATCH","required":["osfql_query","type"],"properties":{"osfql_query":{"type":"string"},"type":{"type":"string","enum":["load_data"]}}},{"type":"object","description":"Update existing term (RETRACT + INSERT)","required":["sort_name","osfql_template","field_types","type"],"properties":{"field_types":{"type":"object","additionalProperties":{"type":"string"},"propertyNames":{"type":"string"}},"osfql_template":{"type":"string"},"sort_name":{"type":"string"},"type":{"type":"string","enum":["update_form"]}}},{"type":"object","description":"Delete a term via OSFQL RETRACT","required":["sort_name","type"],"properties":{"sort_name":{"type":"string"},"type":{"type":"string","enum":["delete_record"]}}},{"type":"object","description":"Trigger forward-chaining inference via OSFQL DERIVE","required":["osfql_derive","type"],"properties":{"osfql_derive":{"type":"string"},"type":{"type":"string","enum":["trigger_inference"]}}},{"type":"object","description":"Navigate to a different adaptive view (client-side)","required":["sort_id","view_mode","type"],"properties":{"sort_id":{"type":"string"},"term_id":{"type":["string","null"]},"type":{"type":"string","enum":["navigate"]},"view_mode":{"type":"string"}}},{"type":"object","description":"Refresh current view data","required":["type"],"properties":{"type":{"type":"string","enum":["refresh"]}}}],"description":"DTO for UIAction — all actions reference OSFQL execution"},"UIActionRequest":{"type":"object","description":"Request to execute a UI action (form submit, update, delete, etc.)\n\nAll actions are translated to OSFQL and executed through OsfqlService.","required":["action_type"],"properties":{"action_type":{"type":"string","description":"Action type: \"submit_form\", \"update_form\", \"delete_record\", \"trigger_inference\""},"field_types":{"type":["object","null"],"description":"Field type metadata (field_name → type hint like \"string\", \"integer\", \"boolean\")","additionalProperties":{"type":"string"},"propertyNames":{"type":"string"}},"original_values":{"type":["object","null"],"description":"Original field values for update operations (used for RETRACT to identify the term)","additionalProperties":{},"propertyNames":{"type":"string"}},"osfql":{"type":["string","null"],"description":"Raw OSFQL override (if provided, used directly instead of building from values)"},"sort_name":{"type":["string","null"],"description":"Sort name (for submit/update/delete actions)"},"term_id":{"type":["string","null"],"description":"Term ID for update/delete operations"},"values":{"type":["object","null"],"description":"Field values for submit/update (field_name → JSON value)","additionalProperties":{},"propertyNames":{"type":"string"}}}},"UIActionResponse":{"type":"object","description":"Response from executing a UI action","required":["success"],"properties":{"diagnostics":{"type":"array","items":{"type":"string"},"description":"Diagnostics from OSFQL execution"},"error":{"type":["string","null"],"description":"Error message if failed"},"produced_term_ids":{"type":"array","items":{"type":"string"},"description":"Produced term IDs (for INSERT actions)"},"success":{"type":"boolean","description":"Whether the action succeeded"}}},"UIAssemblyStatsDto":{"type":"object","description":"DTO for assembly statistics","required":["sort_name","view_mode","total_features","included_features","component_count"],"properties":{"component_count":{"type":"integer","minimum":0},"data_rows":{"type":"integer","description":"Number of data rows loaded","minimum":0},"included_features":{"type":"integer","minimum":0},"osfql_executed":{"type":["string","null"],"description":"OSFQL query executed (if any)"},"sort_name":{"type":"string"},"total_features":{"type":"integer","minimum":0},"view_mode":{"type":"string"}}},"UICatalogEntry":{"type":"object","description":"A single UI component in the catalog","required":["sort","category"],"properties":{"category":{"type":"string","description":"Human-readable category"},"sort":{"$ref":"#/components/schemas/UiSort","description":"Component sort name (e.g. \"input\", \"slider\", \"data_table\")"}}},"UICatalogResponse":{"type":"object","description":"Response for the UI catalog endpoint","required":["components","count"],"properties":{"components":{"type":"array","items":{"$ref":"#/components/schemas/UICatalogEntry"},"description":"All available UiSort variants with metadata"},"count":{"type":"integer","description":"Total count","minimum":0}}},"UICustomizationDto":{"type":"object","description":"A single UI customization instruction from the frontend.\n\nCustomizations are accumulated across chat turns and sent alongside\nthe describe request. The assembly service applies them as patches\non top of the base descriptor generated from the sort definition.","required":["customization_type"],"properties":{"component":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/UIDescriptorDto","description":"Component descriptor for add_component / add_tab"}]},"customization_type":{"type":"string","description":"Type of customization"},"layout_mode":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/LayoutModeDto","description":"Layout mode for change_layout"}]},"params":{"type":["object","null"],"description":"Additional params (label, column name, style values, etc.)","additionalProperties":{},"propertyNames":{"type":"string"}},"props_override":{"type":["object","null"],"description":"Props to override on an existing component","additionalProperties":{},"propertyNames":{"type":"string"}},"target_path":{"type":["string","null"],"description":"JSONPath-style target for modifications (e.g., \"children[0].props\")"},"target_slot":{"type":["string","null"],"description":"Target slot for component additions/removals"}}},"UIDescribeRequest":{"type":"object","description":"Request to generate a UI descriptor for a sort.","required":["sort_id"],"properties":{"customizations":{"type":["array","null"],"items":{"$ref":"#/components/schemas/UICustomizationDto"},"description":"Accumulated UI customizations from multi-turn conversation"},"load_data":{"type":"boolean","description":"Whether to load data via OSFQL (Table/Detail views, default: true)"},"max_components":{"type":"integer","description":"Maximum number of components (default: 50)","minimum":0},"max_depth":{"type":"integer","description":"Maximum nesting depth (default: 5)","minimum":0},"priority_threshold":{"type":"integer","format":"int32","description":"Minimum priority threshold 0-10 (default: 0)","minimum":0},"query":{"type":["string","null"],"description":"Optional OSFQL query for data-bound views"},"session_id":{"type":["string","null"],"description":"Session ID for linking to ui_session (enables persistence)"},"sort_id":{"type":"string","format":"uuid","description":"Sort ID to generate UI for (UUID)"},"term_id":{"type":["string","null"],"description":"Optional term ID for pre-populating form values"},"view_mode":{"type":"string","description":"View mode: \"form\", \"table\", \"detail\", \"card\", \"tree\""}}},"UIDescribeResponse":{"type":"object","description":"Assembled UI descriptor response","required":["layout","descriptor","stats"],"properties":{"data":{"type":"object","description":"Loaded data payload (optional)"},"descriptor":{"$ref":"#/components/schemas/UIDescriptorDto"},"layout":{"$ref":"#/components/schemas/LayoutSurfaceDto"},"stats":{"$ref":"#/components/schemas/UIAssemblyStatsDto"}}},"UIDescriptorDto":{"type":"object","description":"UI component tree node (recursive)","required":["sort","props","priority"],"properties":{"actions":{"type":"array","items":{"$ref":"#/components/schemas/UIActionDto"}},"binding_path":{"type":"string","description":"Data binding path"},"children":{"type":"array","items":{"$ref":"#/components/schemas/UIDescriptorDto"}},"initial_values":{"type":"object","description":"Pre-populated values"},"priority":{"type":"integer","description":"Priority (0-10)"},"props":{"type":"object","description":"Component props"},"slot_id":{"type":"string","description":"Layout slot placement"},"sort":{"type":"string","description":"Component sort (e.g. form, input, slider)"},"validation_rules":{"type":"array","items":{"$ref":"#/components/schemas/ValidationRuleDto"}}}},"UiSort":{"type":"string","description":"Complete hierarchy of UI component sorts","enum":["app","page","dashboard","grid","flex","stack","box","card","divider","spacer","navbar","sidebar","tabs","tab_panel","breadcrumbs","menu","menu_item","link","router","route","data_table","column","list","list_item","tree","tree_node","chart","stat","badge","avatar","icon","image","video","text","heading","paragraph","code","markdown","label","form","form_field","input","textarea","select","option","checkbox","radio","radio_group","toggle","slider","date_picker","time_picker","date_range_picker","file_upload","color_picker","autocomplete","search_input","button","button_group","icon_button","fab","dropdown_button","modal","dialog","drawer","popover","tooltip","toast","alert","progress","spinner","skeleton","accordion","accordion_item","collapsible","carousel","drag_drop_zone","draggable","drop_target","resizable","sortable_list","command_palette","wizard","wizard_step","timeline","timeline_item","kanban_board","kanban_column","kanban_card","calendar","rich_text_editor","conditional","for_each","show","suspense","error_boundary","portal","data_source","computed","state","effect","on_event","on_click","on_submit","on_change","sequence","navigate","api_call","set_state","show_toast","open_modal","close_modal","animate","transition","keyframes","auth_provider","protected_route","login_form","logout_button","user_profile","permission_gate","session_timeout","i18n_provider","trans","language_switcher","locale_date","locale_number","locale_currency","bidi","responsive","show_on_breakpoint","hide_on_breakpoint","container_query","aspect_ratio","theme_provider","theme_toggle","css_var","styled","color_scheme","screen_reader_only","skip_link","focus_trap","live_region","keyboard_nav","accessible_label","focus_ring","virtual_list","virtual_grid","virtual_table","infinite_scroll","lazy_load","code_split","prefetch","offline_indicator","sync_status","cache_control","background_sync","install_prompt","update_available","undo_provider","undo_button","redo_button","history_browser","snapshot","restore_point","hotkey","shortcut_hint","key_combo","shortcut_scope","global_search","search_results","search_highlight","search_filters","recent_searches","copy_button","paste_handler","share_button","qr_code","export_button","print_button","print_only","screen_only","pdf_preview","presence_indicator","cursor_overlay","typing_indicator","conflict_resolver","realtime_diff","notification_center","push_notification","inbox","unread_badge","notification_settings","debug_panel","state_inspector","perf_monitor","network_inspector","error_reporter","position","layer","overlay","fixed","sticky","form_state_provider","field_error","validation_schema","async_validator","cross_field_validation","pagination","cursor_pagination","load_more","page_size_selector","search_params","route_params","deep_link","url_state","query_binding","scroll_container","scroll_snap","scroll_lock","scroll_restore","scroll_to","scroll_spy","selection_provider","selectable","selection_actions","range_selection","gesture_handler","swipe_action","pinch_zoom","long_press","pan_gesture","multi_touch","file_download","file_preview","file_progress","file_browser","drop_zone","image_cropper","animation_controller","animation_timeline","spring","motion_value","animate_presence","stagger","focus_scope","focus_manager","auto_focus","restore_focus","merge_conflict","conflict_resolution","version_indicator","tenant_provider","tenant_switcher","tenant_branding","audit_log","activity_feed","change_history","feature_gate","feature_provider","beta_badge","experiment","variant","experiment_provider","analytics","page_view","click_tracker","event_tracker","rate_limit_indicator","maintenance_mode","system_status","scheduled_downtime","document_head","meta_tag","document_title","open_graph","structured_data","video_call","audio_call","screen_share","media_stream","camera_capture","audio_recorder","canvas2_d","web_g_l","drawing_canvas","signature_pad","geolocation","device_orientation","camera","barcode_scanner","local_storage_binding","session_storage_binding","indexed_db_binding"]},"UncertainEdgeDto":{"type":"object","required":["x","y","uncertainty","possible_directions"],"properties":{"possible_directions":{"type":"array","items":{"type":"array","items":false,"prefixItems":[{"type":"string"},{"type":"string"}]},"description":"Possible directions"},"uncertainty":{"type":"number","format":"double","description":"Uncertainty score (0 = certain, 1 = completely uncertain)"},"x":{"type":"string","description":"First variable"},"y":{"type":"string","description":"Second variable"}}},"UndoRequest":{"type":"object","description":"Request for undo (execute on backtracking)","required":["session_id","goal"],"properties":{"goal":{"type":"object","description":"Goal to execute when backtracking occurs"},"session_id":{"type":"string"}}},"UndoResponse":{"type":"object","description":"Response from undo registration","required":["undo_id","trail_position"],"properties":{"trail_position":{"type":"integer","description":"Current trail position","minimum":0},"undo_id":{"type":"string","description":"ID for this undo action"}}},"UndoRuleStoreRequest":{"type":"object","description":"Request to undo to a checkpoint","required":["marker_index"],"properties":{"marker_index":{"type":"integer","minimum":0}}},"UndoRuleStoreResponse":{"type":"object","description":"Response after undoing","required":["success","rule_count"],"properties":{"rule_count":{"type":"integer","minimum":0},"success":{"type":"boolean"}}},"UnificationQueryRequest":{"type":"object","description":"Request to find unifiable terms\n\n# Tenant Context\nThe tenant is determined from the `X-Tenant-Id` header.","required":["pattern"],"properties":{"pattern":{"$ref":"#/components/schemas/TermPatternDto","description":"Pattern to match against"}}},"UnificationQueryResponse":{"type":"object","description":"Response for unification query","required":["results","count"],"properties":{"count":{"type":"integer","description":"Total count","minimum":0},"results":{"type":"array","items":{"$ref":"#/components/schemas/TermDto"},"description":"Matching terms"}}},"UnifyTermsRequest":{"type":"object","description":"Request to unify two terms","required":["term1_id","term2_id"],"properties":{"term1_id":{"type":"string"},"term2_id":{"type":"string"}}},"UnifyTermsResponse":{"type":"object","description":"Response after unification","required":["success","trail_length"],"properties":{"failure_reason":{"type":["string","null"],"description":"If unification failed, the reason"},"success":{"type":"boolean"},"trail_length":{"type":"integer","description":"Trail length after unification (for backtracking)","minimum":0},"unified_term_id":{"type":["string","null"],"description":"The resulting unified term ID (if successful)"}}},"UpdateCollectionRequest":{"type":"object","description":"Request to update a collection","required":["tags"],"properties":{"description":{"type":["string","null"],"description":"Optional description"},"tags":{"type":"array","items":{"type":"string"},"description":"Tags for categorization"}}},"UpdateMetadataRequest":{"type":"object","description":"Request to update namespace metadata","required":["tags"],"properties":{"description":{"type":["string","null"],"description":"Optional description"},"tags":{"type":"array","items":{"type":"string"},"description":"Tags"}}},"UpdatePlanStatsRequest":{"type":"object","description":"Request to update plan statistics.","required":["tenant_id","agent_id","plan_id","success"],"properties":{"agent_id":{"type":"string","format":"uuid","description":"Agent ID"},"plan_id":{"type":"string","format":"uuid","description":"Plan template ID"},"success":{"type":"boolean","description":"Whether the plan succeeded"},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"}}},"UpdatePlanStatsResponse":{"type":"object","description":"Response after updating plan stats.","required":["new_success_rate","new_use_count","message"],"properties":{"message":{"type":"string","description":"Message"},"new_success_rate":{"type":"number","format":"double","description":"New success rate"},"new_use_count":{"type":"integer","format":"int64","description":"New use count"}}},"UpdateScenarioRequest":{"type":"object","description":"Request body for PATCH /api/v1/scenarios/:id — incremental updates.","properties":{"add_beliefs":{"type":"array","items":{},"description":"Additional beliefs to materialize.\nEach object: `{ \"sort\": \"...\", \"features\": {...}, \"confidence\": 0.9, \"source\": \"...\" }`"},"add_constraints":{"type":"array","items":{},"description":"Additional generic constraints to materialize.\nEach object: `{ \"sort\": \"...\", \"features\": {...} }`"},"add_guard_constraints":{"type":"array","items":{},"description":"Additional guard constraints to materialize.\nEach object: `{ \"left\": \"?Var\", \"operator\": \">\", \"right\": 100 }`"},"add_rules":{"type":"array","items":{},"description":"Additional rules to register.\nEach object: `{ \"head\": { \"sort\": \"...\", \"features\": {...} }, \"antecedents\": [...] }`"},"add_sorts":{"type":"array","items":{},"description":"Additional sorts to add (appended to existing hierarchy).\nEach object: `{ \"name\": \"...\", \"parents\": [\"thing\"], \"features\": {...} }`"},"add_temporal_constraints":{"type":"array","items":{},"description":"Additional temporal constraints to materialize.\nEach object: `{ \"relation\": \"before\", \"interval_a\": \"...\", \"interval_b\": \"...\" }`"},"add_webhook_actions":{"type":"array","items":{},"description":"Additional webhook actions to materialize.\nEach object: `{ \"name\": \"...\", \"channel\": \"Email\", \"webhookUrl\": \"...\", \"description\": \"...\" }`"}}},"UpdateScenarioResponse":{"type":"object","description":"Response for PATCH /api/v1/scenarios/:id — incremental update result.","required":["scenario_id","sorts_added","beliefs_added","rules_added","constraints_added","guard_constraints_added","temporal_constraints_added","webhook_actions_added","total_sorts","total_beliefs","total_rules","total_constraints","total_guard_constraints","total_temporal_constraints","total_webhook_actions"],"properties":{"beliefs_added":{"type":"integer","description":"Number of beliefs added in this update.","minimum":0},"constraints_added":{"type":"integer","description":"Number of generic constraints added in this update.","minimum":0},"guard_constraints_added":{"type":"integer","description":"Number of guard constraints added in this update.","minimum":0},"rules_added":{"type":"integer","description":"Number of rules added in this update.","minimum":0},"scenario_id":{"type":"string","description":"Scenario ID that was updated."},"sorts_added":{"type":"integer","description":"Number of sorts added in this update.","minimum":0},"temporal_constraints_added":{"type":"integer","description":"Number of temporal constraints added in this update.","minimum":0},"total_beliefs":{"type":"integer","description":"Updated total beliefs count.","minimum":0},"total_constraints":{"type":"integer","description":"Updated total generic constraints count.","minimum":0},"total_guard_constraints":{"type":"integer","description":"Updated total guard constraints count.","minimum":0},"total_rules":{"type":"integer","description":"Updated total rules count.","minimum":0},"total_sorts":{"type":"integer","description":"Updated total sorts count.","minimum":0},"total_temporal_constraints":{"type":"integer","description":"Updated total temporal constraints count.","minimum":0},"total_webhook_actions":{"type":"integer","description":"Updated total webhook actions count.","minimum":0},"webhook_actions_added":{"type":"integer","description":"Number of webhook actions added in this update.","minimum":0}}},"UpdateSortReviewRequest":{"type":"object","description":"Request to update sort review status","properties":{"approve":{"type":"boolean","description":"Clear the needs_review flag (approve the sort)"},"mark_for_review":{"type":"boolean","description":"Mark for review"}}},"UpdateTemplateRequestDto":{"type":"object","description":"Request to update an existing template.","properties":{"description":{"type":["string","null"],"description":"Updated description."},"osfql_pattern":{"type":["string","null"],"description":"Updated OSFQL pattern."}}},"UpdateTermRequest":{"type":"object","description":"Request to update a term","required":["features"],"properties":{"features":{"type":"object","description":"Features to update","additionalProperties":{"$ref":"#/components/schemas/ValueDto"},"propertyNames":{"type":"string"}}}},"UpdateVisibilityRequest":{"type":"object","description":"Request to update namespace visibility","required":["visibility"],"properties":{"visibility":{"$ref":"#/components/schemas/VisibilityDto","description":"New visibility level"}}},"ValidatedTermRequest":{"type":"object","description":"Request for witness-validated term creation\n\nThis endpoint validates that a term satisfies its sort's existential witnesses.\nUnlike regular term creation, this checks that the term is a LEGITIMATE instance\nof its type according to the type's definition (compiled rules).\n\n## Example\nIf sort `grandparent` was defined by rule:\n`grandparent(X,Z) :- parent(X,Y), parent(Y,Z)`\n\nThen creating a `grandparent(person => alice, grandchild => charlie)` term\nwill check that there EXISTS a Y such that parent(alice, Y) ∧ parent(Y, charlie).\n\n## Difference from Regular Term Creation\n- Regular: Just stores the term (no validation)\n- Validated: Checks witnesses, fails if type constraints not satisfied\n\n# Tenant Context\nThe tenant is determined from the `X-Tenant-Id` header.","required":["term"],"properties":{"persist":{"type":"boolean","description":"If true, also persist the term on success"},"term":{"$ref":"#/components/schemas/TermPatternDto","description":"The term to validate and create"}}},"ValidatedTermResponse":{"type":"object","description":"Response from witness-validated term creation","required":["valid","witnesses_satisfied","witnesses_residuated"],"properties":{"failure_reason":{"type":["string","null"],"description":"Reason for failure (if invalid)"},"term":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/TermDto","description":"The validated term (if valid)"}]},"valid":{"type":"boolean","description":"Whether validation succeeded"},"witnesses_residuated":{"type":"array","items":{"$ref":"#/components/schemas/ResiduationDto"},"description":"Witnesses that are residuated (waiting for more information)"},"witnesses_satisfied":{"type":"array","items":{"$ref":"#/components/schemas/WitnessInstantiationDto"},"description":"Witnesses that were satisfied (proof the term is legitimate)"}}},"ValidatedUnifyRequest":{"type":"object","description":"Request for witness-validated unification\n\nUnifies two terms AND validates that the result satisfies the GLB sort's witnesses.\n\n## Example\nUnifying `person(name => \"Alice\")` with `employee(salary => 50000)`:\n1. Computes GLB of person and employee\n2. Creates unified term with both features\n3. Checks witnesses on the GLB sort\n4. Returns result with witness proofs\n\n# Tenant Context\nThe tenant is determined from the `X-Tenant-Id` header.","required":["term1","term2"],"properties":{"term1":{"$ref":"#/components/schemas/TermPatternDto","description":"First term"},"term2":{"$ref":"#/components/schemas/TermPatternDto","description":"Second term"}}},"ValidatedUnifyResponse":{"type":"object","description":"Response from witness-validated unification","required":["success","witnesses_satisfied","witnesses_residuated","duration_us"],"properties":{"duration_us":{"type":"integer","format":"int64","description":"Processing time in microseconds","minimum":0},"failure_reason":{"type":["string","null"],"description":"Failure reason (if failed)"},"glb_sort_id":{"type":["string","null"],"format":"uuid","description":"The GLB sort used"},"success":{"type":"boolean","description":"Whether unification succeeded (including witness validation)"},"unified_term":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/TermDto","description":"The unified term (if successful)"}]},"witnesses_residuated":{"type":"array","items":{"$ref":"#/components/schemas/ResiduationDto"},"description":"Witnesses residuated (couldn't satisfy yet, but may succeed later)"},"witnesses_satisfied":{"type":"array","items":{"$ref":"#/components/schemas/WitnessInstantiationDto"},"description":"Witnesses satisfied during unification"}}},"ValidationRuleDto":{"type":"object","description":"DTO for validation rules (client-side validation from FeatureDescriptor constraints)","required":["field","rule_type","message"],"properties":{"field":{"type":"string","description":"Feature/field name this rule applies to"},"message":{"type":"string","description":"Human-readable error message"},"rule_type":{"$ref":"#/components/schemas/ValidationTypeDto","description":"Validation type (determines frontend behavior)"}}},"ValidationTypeDto":{"oneOf":[{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["required"]}}},{"type":"object","required":["params","type"],"properties":{"params":{"type":"number","format":"double"},"type":{"type":"string","enum":["min"]}}},{"type":"object","required":["params","type"],"properties":{"params":{"type":"number","format":"double"},"type":{"type":"string","enum":["max"]}}},{"type":"object","required":["params","type"],"properties":{"params":{"type":"string"},"type":{"type":"string","enum":["pattern"]}}},{"type":"object","required":["params","type"],"properties":{"params":{"type":"array","items":{"type":"string"}},"type":{"type":"string","enum":["one_of"]}}},{"type":"object","required":["params","type"],"properties":{"params":{"type":"string"},"type":{"type":"string","enum":["value_type"]}}},{"type":"object","required":["params","type"],"properties":{"params":{"type":"string"},"type":{"type":"string","enum":["date_after"]}}},{"type":"object","required":["params","type"],"properties":{"params":{"type":"string"},"type":{"type":"string","enum":["date_before"]}}}],"description":"DTO for validation type"},"ValueDto":{"oneOf":[{"type":"object","title":"String","description":"String value","required":["type","value"],"properties":{"type":{"type":"string","enum":["String"]},"value":{"type":"string"}}},{"type":"object","title":"Integer","description":"64-bit integer value","required":["type","value"],"properties":{"type":{"type":"string","enum":["Integer"]},"value":{"type":"integer","format":"int64"}}},{"type":"object","title":"Real","description":"64-bit floating-point value","required":["type","value"],"properties":{"type":{"type":"string","enum":["Real"]},"value":{"type":"number","format":"double"}}},{"type":"object","title":"Boolean","description":"Boolean value","required":["type","value"],"properties":{"type":{"type":"string","enum":["Boolean"]},"value":{"type":"boolean"}}},{"type":"object","title":"Uninstantiated","description":"Uninstantiated/unbound value (logic variable)","required":["type"],"properties":{"type":{"type":"string","enum":["Uninstantiated"]}}},{"type":"object","title":"Reference","description":"Reference to another term by UUID","required":["type","value"],"properties":{"type":{"type":"string","enum":["Reference"]},"value":{"type":"string","format":"uuid"}}},{"type":"object","title":"List","description":"List of values (recursive)","required":["type","value"],"properties":{"type":{"type":"string","enum":["List"]},"value":{"type":"array","items":{"$ref":"#/components/schemas/ValueDto"}}}},{"type":"object","title":"FuzzyScalar","description":"Fuzzy scalar with value and membership degree","required":["type","value"],"properties":{"type":{"type":"string","enum":["FuzzyScalar"]},"value":{"type":"object","required":["value","membership"],"properties":{"membership":{"type":"number","format":"double","description":"Membership degree (0.0 to 1.0)"},"value":{"type":"number","format":"double","description":"The scalar value"}}}}},{"type":"object","title":"FuzzyNumber","description":"Fuzzy number with shape (Triangular, Trapezoidal, Gaussian, CyclicGaussian)","required":["type","value"],"properties":{"type":{"type":"string","enum":["FuzzyNumber"]},"value":{"type":"object","required":["shape"],"properties":{"shape":{"$ref":"#/components/schemas/FuzzyShapeDto"}}}}},{"type":"object","title":"Set","description":"Set-valued feature with lower/upper bounds for constraint propagation","required":["type","value"],"properties":{"type":{"type":"string","enum":["Set"]},"value":{"type":"object","required":["lower","upper"],"properties":{"lower":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Lower bound - definite members"},"sort_constraint":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Optional sort constraint for set members"},"upper":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Upper bound - possible members"}}}}}],"title":"ValueDto","description":"Value in a term feature. Discriminated by 'type' field.\nVariants: String, Integer, Real, Boolean, Uninstantiated, Reference, List, FuzzyScalar, FuzzyNumber, Set.","discriminator":{"propertyName":"type"}},"ValuePatternDto":{"oneOf":[{"type":"object","description":"Match any value","required":["type"],"properties":{"type":{"type":"string","enum":["any"]}}},{"type":"object","description":"Match any value of specific type","required":["feature_type","type"],"properties":{"feature_type":{"$ref":"#/components/schemas/FeatureTypeDto"},"type":{"type":"string","enum":["of_type"]}}},{"type":"object","description":"Match exact value","required":["value","type"],"properties":{"type":{"type":"string","enum":["exact"]},"value":{}}},{"type":"object","description":"Match values greater than","required":["value","type"],"properties":{"type":{"type":"string","enum":["greater_than"]},"value":{}}},{"type":"object","description":"Match values less than","required":["value","type"],"properties":{"type":{"type":"string","enum":["less_than"]},"value":{}}},{"type":"object","description":"Match values containing substring","required":["substring","type"],"properties":{"substring":{"type":"string"},"type":{"type":"string","enum":["contains"]}}},{"type":"object","description":"Match values matching regex","required":["pattern","type"],"properties":{"pattern":{"type":"string"},"type":{"type":"string","enum":["regex"]}}},{"type":"object","description":"Bind to variable for extraction","required":["variable","type"],"properties":{"type":{"type":"string","enum":["bind"]},"variable":{"type":"string"}}}],"description":"Value pattern for dynamic queries"},"VariableFeasibilityDto":{"type":"object","description":"Feasibility of a single binary variable in the constraint space.\n\nProduced by `feasibility` mode search. Fields report **observation-based**\nreachability: the solver sets `can_be_true` only when it has witnessed a\ncomplete satisfying assignment with this variable = 1 (and similarly for\n`can_be_false`). Both fields can be `false` only when the problem is UNSAT.","required":["can_be_true","can_be_false"],"properties":{"can_be_false":{"type":"boolean","description":"`true` if the solver witnessed a valid assignment where this variable\nis 0 (unselected / false)."},"can_be_true":{"type":"boolean","description":"`true` if the solver witnessed a valid assignment where this variable\nis 1 (selected / true)."},"verified":{"type":"boolean","description":"`true` when the result is fully determined by the solver — both\npolarities were either observed in a model or formally proven\ninfeasible (by unit propagation or an UNSAT probe).\n\n`false` when a conflict limit was hit before the solver could fully\ndetermine the variable's status. In that case `can_be_true` /\n`can_be_false` still faithfully reflect the polarities the solver\nactually witnessed — they are **never** optimistic defaults. Clients\ntypically render unverified variables in an intermediate visual state\n(e.g. yellow/amber) so the user knows the result is approximate."}}},"VerbalizationResultDto":{"type":"object","description":"Result of verbalizing a single PsiTerm.","required":["text","strategy","sort_name","features_included","features_total"],"properties":{"features_included":{"type":"integer","description":"Number of features included in verbalization.","minimum":0},"features_total":{"type":"integer","description":"Total features available on the term.","minimum":0},"sort_name":{"type":"string","description":"The sort name of the source term."},"strategy":{"type":"string","description":"The verbalization strategy used."},"text":{"type":"string","description":"The generated natural language text."}}},"VerbalizeTermRequest":{"type":"object","description":"Request to verbalize a specific term.","required":["term_id"],"properties":{"include_parent_context":{"type":"boolean","description":"Whether to include parent sort context."},"include_sort_description":{"type":"boolean","description":"Whether to include sort description in output."},"max_features":{"type":["integer","null"],"description":"Maximum features to include (0 = all).","minimum":0},"strategy":{"type":["string","null"],"description":"Verbalization strategy. Options: \"Template\", \"SchemaGuided\", \"SortEmbedding\", \"Narrative\"."},"term_id":{"type":"string","format":"uuid","description":"Term ID to verbalize."}}},"VerbalizeTermResponse":{"type":"object","description":"Response from term verbalization.","required":["result"],"properties":{"result":{"$ref":"#/components/schemas/VerbalizationResultDto","description":"The verbalization result."}}},"VerificationDto":{"type":"object","description":"Verification result DTO.","required":["passed","coverage","soft_constraint_score","checks","violations"],"properties":{"checks":{"type":"array","items":{"$ref":"#/components/schemas/ConstraintCheckDto"},"description":"Individual constraint check results."},"coverage":{"type":"number","format":"double","description":"Citation coverage ratio (0.0–1.0)."},"passed":{"type":"boolean","description":"Whether all hard constraints are satisfied."},"soft_constraint_score":{"type":"number","format":"double","description":"Soft constraint satisfaction score (0.0–1.0)."},"violations":{"type":"array","items":{"$ref":"#/components/schemas/ViolationDto"},"description":"Violations found during verification."}}},"VerificationStepDto":{"type":"object","description":"A single verification step in the trajectory.","required":["name","description","passed"],"properties":{"description":{"type":"string","description":"Description of what happened in this step."},"name":{"type":"string","description":"Step name (e.g., \"sort_creation\", \"belief_materialization\")."},"passed":{"type":"boolean","description":"Whether this step passed verification."}}},"VerifyFaithfulnessRequest":{"type":"object","description":"Request to verify faithfulness of generated text against source entities.","required":["original","extracted"],"properties":{"extracted":{"type":"object","description":"Extracted entity features (from generated text).","additionalProperties":{"type":"string"},"propertyNames":{"type":"string"}},"min_recovery_rate":{"type":["number","null"],"format":"double","description":"Minimum entity recovery rate (default: 0.5)."},"min_score":{"type":["number","null"],"format":"double","description":"Minimum faithfulness score threshold (default: 0.3)."},"original":{"type":"object","description":"Original entity features (source of truth).","additionalProperties":{"type":"string"},"propertyNames":{"type":"string"}}}},"VerifyFaithfulnessResponse":{"type":"object","description":"Response from faithfulness verification.","required":["passed","score","entities_recovered","entities_expected","mismatches"],"properties":{"entities_expected":{"type":"integer","description":"Total entities expected.","minimum":0},"entities_recovered":{"type":"integer","description":"Number of entities recovered in round-trip extraction.","minimum":0},"mismatches":{"type":"array","items":{"type":"string"},"description":"Details of mismatches found."},"passed":{"type":"boolean","description":"Whether the pair passed faithfulness verification."},"score":{"type":"number","format":"double","description":"Faithfulness score (0.0-1.0)."}}},"VerifyIntegrityRequest":{"type":"object","properties":{"entries":{"type":"array","items":{"$ref":"#/components/schemas/AuditEntryDto"}}}},"VerifyRoundTripRequest":{"type":"object","description":"Request for OSF-aware round-trip faithfulness verification.\n\nCompares ground truth Ψ-terms against extracted Ψ-terms using Wu-Palmer\nsort similarity, feature-level comparison, and Hungarian algorithm matching.","required":["ground_truth","extracted"],"properties":{"extracted":{"type":"array","items":{"$ref":"#/components/schemas/EntityDto"},"description":"Extracted entities (sort_id + features) from round-trip extraction."},"feature_weight":{"type":["number","null"],"format":"double","description":"Weight for feature recovery in entity scoring (default: 0.6)."},"ground_truth":{"type":"array","items":{"$ref":"#/components/schemas/EntityDto"},"description":"Ground truth entities (sort_id + features)."},"min_faithfulness_score":{"type":["number","null"],"format":"double","description":"Minimum faithfulness score threshold (default: 0.5)."},"min_feature_recovery":{"type":["number","null"],"format":"double","description":"Minimum feature recovery rate (default: 0.5)."},"min_sort_similarity":{"type":["number","null"],"format":"double","description":"Minimum sort similarity threshold (default: 0.5)."},"sort_weight":{"type":["number","null"],"format":"double","description":"Weight for sort similarity in entity scoring (default: 0.4)."}}},"VerifyRoundTripResponse":{"type":"object","description":"Response from round-trip faithfulness verification.","required":["faithfulness_score","passed","entities_matched","entities_expected","entities_extracted","entity_details","unmatched_ground_truth","unmatched_extracted","total_features_expected","total_features_recovered","mismatches"],"properties":{"entities_expected":{"type":"integer","description":"Number of ground truth entities.","minimum":0},"entities_extracted":{"type":"integer","description":"Number of extracted entities.","minimum":0},"entities_matched":{"type":"integer","description":"Number of entities successfully matched.","minimum":0},"entity_details":{"type":"array","items":{"$ref":"#/components/schemas/EntityVerificationDetailDto"},"description":"Per-entity verification details."},"faithfulness_score":{"type":"number","format":"double","description":"Overall faithfulness score (0.0-1.0)."},"mismatches":{"type":"array","items":{"type":"string"},"description":"Summary of mismatches found."},"passed":{"type":"boolean","description":"Whether the verification passed all thresholds."},"total_features_expected":{"type":"integer","description":"Total features expected across all ground truth entities.","minimum":0},"total_features_recovered":{"type":"integer","description":"Total features successfully recovered.","minimum":0},"unmatched_extracted":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Extracted entities not matched to any ground truth."},"unmatched_ground_truth":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Ground truth entities not matched by any extraction."}}},"VerifyScenarioRequest":{"type":"object","description":"Request body for POST /api/v1/scenarios/:id/verify.","properties":{"config":{"description":"Optional custom verification config (reserved for future use)."}}},"VerifyScenarioResponse":{"type":"object","description":"Response for POST /api/v1/scenarios/:id/verify.","required":["scenario_id","verdict","confidence","steps","summary"],"properties":{"confidence":{"type":"number","format":"double","description":"Confidence score (0.0 to 1.0)."},"formal_verdict":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/FormalVerdictDto","description":"FormalJudge semantic verdict (only present if LLM is configured)."}]},"scenario_id":{"type":"string","description":"The scenario ID that was verified."},"steps":{"type":"array","items":{"$ref":"#/components/schemas/VerificationStepDto"},"description":"Per-step verification details."},"summary":{"type":"string","description":"Summary explanation."},"verdict":{"type":"string","description":"Overall verdict: \"safe\", \"unsafe\", \"needs_review\", \"partial\", or \"residuated\"."}}},"ViolationDto":{"type":"object","description":"A verification violation.","required":["description","severity"],"properties":{"description":{"type":"string","description":"Description of the violation."},"related_fact_id":{"type":["string","null"],"format":"uuid","description":"Related fact ID (if applicable)."},"severity":{"type":"string","description":"Severity: \"error\" or \"warning\"."}}},"VisibilityDto":{"type":"string","description":"Visibility level DTO","enum":["public","internal","protected","private","restricted"]},"VisualizationGraphDto":{"type":"object","description":"Unified graph response for all visualization types","required":["graph_id","metadata","nodes","edges"],"properties":{"dot_output":{"type":["string","null"],"description":"DOT format output (if requested)"},"edges":{"type":"array","items":{"$ref":"#/components/schemas/GraphEdgeDto"},"description":"All edges in the graph"},"graph_id":{"type":"string","format":"uuid","description":"Unique identifier for this graph"},"hyperedges":{"type":"array","items":{"$ref":"#/components/schemas/HyperedgeDto"},"description":"All hyperedges in the graph"},"layout":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/LayoutHintsDto","description":"Layout hints for rendering"}]},"metadata":{"$ref":"#/components/schemas/GraphMetadataDto","description":"Metadata about the graph"},"nodes":{"type":"array","items":{"$ref":"#/components/schemas/GraphNodeDto"},"description":"All nodes in the graph"}}},"WaitingConditionDto":{"type":"object","description":"What a residuation is waiting for","required":["condition_type","description"],"properties":{"condition_type":{"$ref":"#/components/schemas/WaitingConditionType","description":"Condition type"},"description":{"type":"string","description":"Description"},"feature_name":{"type":["string","null"],"description":"Feature name (if waiting on feature)"},"target_id":{"type":["string","null"],"format":"uuid","description":"Target term/variable ID"}}},"WaitingConditionType":{"type":"string","description":"Type of waiting condition","enum":["feature_binding","sort_narrowing","term_creation","external_input","constraint_satisfaction"]},"WebhookCallbackRequest":{"type":"object","description":"Request to complete a pending invocation (webhook callback).\n\nThis is POSTed by the external system when the action completes.\nOutputs are bound to the action Ψ-term's features, and demons fire.\n\nOptionally, set `notify_agent_id` and `notify_tenant_id` to bridge\nthe webhook result as a belief into the cognitive agent's TermStore.","required":["status"],"properties":{"error":{"type":["string","null"],"description":"Error message if failed"},"notify_agent_id":{"type":["string","null"],"format":"uuid","description":"Optional: Agent UUID to notify with webhook results"},"notify_tenant_id":{"type":["string","null"],"format":"uuid","description":"Optional: Tenant UUID for the agent to notify"},"outputs":{"type":"object","description":"Output values to bind to the Ψ-term features","additionalProperties":{},"propertyNames":{"type":"string"}},"status":{"type":"string","description":"Status of the action: \"success\", \"failed\", or \"cancelled\""}}},"WebhookCallbackResponse":{"type":"object","description":"Response after processing a webhook callback.","required":["status","demons_fired","term_updated","message"],"properties":{"demons_fired":{"type":"integer","description":"Number of demons fired","minimum":0},"message":{"type":"string","description":"Confirmation message"},"status":{"type":"string","description":"Final status of the invocation"},"term_updated":{"type":"boolean","description":"Whether the action Ψ-term was updated"}}},"WeightedFactDto":{"type":"object","description":"A weighted fact with provenance information.","required":["term_id","sort_name","weight","depth","contributing_rules"],"properties":{"contributing_rules":{"type":"array","items":{"type":"string","format":"uuid"}},"depth":{"type":"integer","format":"int32","minimum":0},"sort_name":{"type":"string"},"term_id":{"type":"string","format":"uuid"},"weight":{"type":"number","format":"double"}}},"WitnessInstantiationDto":{"type":"object","description":"A witness instantiation (proof that existential constraint was satisfied)","required":["witness_id","bindings","confidence"],"properties":{"bindings":{"type":"object","description":"The bindings that satisfy the witness\ne.g., {\"?Y\": \"bob\"} for grandparent witness ∃Y. parent(X,Y) ∧ parent(Y,Z)","additionalProperties":{"type":"string"},"propertyNames":{"type":"string"}},"confidence":{"type":"number","format":"double","description":"Confidence in the witness (1.0 = certain)"},"explanation":{"type":["string","null"],"description":"Human-readable explanation"},"witness_id":{"type":"string","description":"ID of the witness that was satisfied"}}},"WitnessProofDto":{"type":"object","description":"Witness proof for a term","required":["witness_id","bindings","certainty"],"properties":{"bindings":{"type":"object","description":"Variable bindings that satisfy the witness","additionalProperties":{"type":"string"},"propertyNames":{"type":"string"}},"certainty":{"type":"number","format":"double","description":"Confidence/certainty of the proof"},"witness_id":{"type":"string","description":"ID of the witness that was satisfied"}}},"WsConnectParams":{"type":"object","description":"Parameters for WebSocket connection.","required":["agent_id","tenant_id"],"properties":{"agent_id":{"type":"string","format":"uuid","description":"Agent ID to subscribe to"},"tenant_id":{"type":"string","format":"uuid","description":"Tenant ID"}}}},"securitySchemes":{"tenant_id":{"type":"apiKey","in":"header","name":"X-Tenant-Id"}}},"tags":[{"name":"health","description":"Health check"},{"name":"terms","description":"Term management"},{"name":"inference","description":"Inference engine (rules, facts, backward/forward chaining)"},{"name":"causal","description":"Causal reasoning (Pearl's causal hierarchy: causes, ancestors, d-separation, interventions, counterfactuals)"},{"name":"statistical","description":"Statistical builtins for causal discovery (correlations, CI tests, online observation)"},{"name":"query","description":"Query and search operations"},{"name":"constraints","description":"Constraint solving and sessions"},{"name":"control","description":"Control flow, assignments, and module system"},{"name":"execution","description":"Wild_Life execution engine (trail, goals, currying, residuation)"},{"name":"spaces","description":"Computation spaces for constraint solving and search"},{"name":"sorts","description":"Sort/type hierarchy management"},{"name":"namespaces","description":"Namespace management"},{"name":"strings","description":"String operations"},{"name":"arithmetic","description":"Arithmetic operations"},{"name":"types","description":"Type hierarchy navigation"},{"name":"communities","description":"Community detection"},{"name":"row-polymorphism","description":"Structural typing queries - search by features, not by sort"},{"name":"reviews","description":"Human-in-the-loop reviews"},{"name":"discovery","description":"Effect discovery from time series"},{"name":"ilp","description":"Inductive Logic Programming - learn patterns from examples"},{"name":"scheduling","description":"Scheduling feasibility via capacitated bipartite b-matching (staff rostering, assignment problems)"},{"name":"fuzzy","description":"Fuzzy unification and similarity search"},{"name":"rag","description":"Ontology RAG - True OSF-based retrieval augmented generation"},{"name":"copy","description":"Term copying operations"},{"name":"extraction","description":"NER entity extraction using GLiNER2 with sort names as labels"},{"name":"reasoning","description":"Fuzzy reasoning, subsumption, and merging"},{"name":"collections","description":"Hierarchical collection management"},{"name":"proof_engine","description":"Term store, rule store, and evaluation"},{"name":"cognitive","description":"Cognitive agents - BDI sense-think-act-learn cycle"},{"name":"Cognitive Agents - Plan Library","description":"Plan storage and reuse for cognitive agents"},{"name":"Cognitive Agents - HTN","description":"Hierarchical Task Network decomposition"},{"name":"Cognitive Agents - Messaging","description":"Inter-agent messaging"},{"name":"Cognitive Agents - Episodic Memory","description":"Episode recording and retrieval"},{"name":"visualization","description":"Visualization of sort hierarchy, constraints, hypergraphs, and residuation state"},{"name":"structured_ingestion","description":"Structured data ingestion from external sources (CSV, Parquet, SQL, Neo4j, MCP, REST, GraphQL)"},{"name":"scenarios","description":"Scenario generation and materialization from natural language"},{"name":"admin","description":"Administrative operations (factory reset, data management)"},{"name":"snapshots","description":"Tenant data snapshots (point-in-time capture and restore)"},{"name":"oversight","description":"Agentic oversight verification (FormalJudge) - trajectory analysis, multi-layer safety verification, live streaming sessions"},{"name":"rl-training","description":"Reinforcement learning training - standalone or cognitive-RL bridge"},{"name":"neuro-symbolic","description":"Neuro-symbolic admin - training, diagnostics, embeddings, GFlowNet"},{"name":"preferences","description":"Preference learning - record selections, predict preferences"},{"name":"functions","description":"User-defined functions - register and evaluate LIFE-style functions"},{"name":"ontology","description":"Ontology generation from natural language task descriptions"},{"name":"ontology_bridge","description":"Ontology-SQL bridge - OWL import, sort-table bindings, OSFQL transpilation, grounded schema"},{"name":"analysis","description":"Attribute exploration and sort discovery (FCA-based analysis)"},{"name":"webhook-actions","description":"External action registration, invocation, and webhook callbacks"},{"name":"synthetic","description":"Synthetic data generation, export, verification, and calibration"},{"name":"cdl","description":"Categorical Deep Learning - differentiable FC, soft unification, monadic fixpoint, safety classification"},{"name":"image-extraction","description":"Image concept extraction using vision LLMs"},{"name":"generation","description":"Evidence-grounded document generation pipeline"},{"name":"conversation","description":"Conversational UI - natural language interaction with the knowledge base"},{"name":"preferences","description":"User preferences - learned UI preferences from conversation interactions"},{"name":"templates","description":"Query templates - saved OSFQL patterns for reuse"},{"name":"context","description":"Context assembly - structured LLM context from knowledge graph"},{"name":"ui","description":"UI descriptor - OSF-native adaptive UI generation"},{"name":"audit","description":"Audit trail - conversation and change tracking"},{"name":"documents","description":"Document analysis and processing"}]}