mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-07-23 20:21:03 +02:00
More services in OpenAPI
This commit is contained in:
Cyber MacGeddon
parent
83d3ad05df
commit
f3ba370fdc
22 changed files with 1666 additions and 0 deletions
59
specs/api/components/schemas/agent/AgentRequest.yaml
Normal file
59
specs/api/components/schemas/agent/AgentRequest.yaml
Normal file
|
|
@ -0,0 +1,59 @@
|
|||
type: object
|
||||
description: |
|
||||
Agent service request - conversational AI agent that can reason and take actions.
|
||||
required:
|
||||
- question
|
||||
properties:
|
||||
question:
|
||||
type: string
|
||||
description: User question or prompt for the agent
|
||||
example: What is the capital of France?
|
||||
state:
|
||||
type: string
|
||||
description: Agent state for continuation (optional, for multi-turn)
|
||||
example: agent-state-12345
|
||||
group:
|
||||
type: array
|
||||
description: Group identifiers for collaborative agents (optional)
|
||||
items:
|
||||
type: string
|
||||
example: ["research-team"]
|
||||
history:
|
||||
type: array
|
||||
description: Conversation history (optional, list of previous agent steps)
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
thought:
|
||||
type: string
|
||||
description: Agent's reasoning
|
||||
example: I need to search for information about Paris
|
||||
action:
|
||||
type: string
|
||||
description: Action taken
|
||||
example: search
|
||||
arguments:
|
||||
type: object
|
||||
description: Action arguments
|
||||
additionalProperties:
|
||||
type: string
|
||||
example:
|
||||
query: "capital of France"
|
||||
observation:
|
||||
type: string
|
||||
description: Result of the action
|
||||
example: "Paris is the capital of France"
|
||||
user:
|
||||
type: string
|
||||
description: User context for this step
|
||||
example: alice
|
||||
user:
|
||||
type: string
|
||||
description: User identifier for multi-tenancy
|
||||
default: trustgraph
|
||||
example: alice
|
||||
streaming:
|
||||
type: boolean
|
||||
description: Enable streaming response delivery
|
||||
default: false
|
||||
example: true
|
||||
51
specs/api/components/schemas/agent/AgentResponse.yaml
Normal file
51
specs/api/components/schemas/agent/AgentResponse.yaml
Normal file
|
|
@ -0,0 +1,51 @@
|
|||
type: object
|
||||
description: Agent service response (streaming or legacy format)
|
||||
properties:
|
||||
chunk-type:
|
||||
type: string
|
||||
description: Type of streaming chunk (streaming mode only)
|
||||
enum:
|
||||
- thought
|
||||
- action
|
||||
- observation
|
||||
- answer
|
||||
- error
|
||||
example: answer
|
||||
content:
|
||||
type: string
|
||||
description: Chunk content (streaming mode only)
|
||||
example: Paris is the capital of France.
|
||||
end-of-message:
|
||||
type: boolean
|
||||
description: Current chunk type is complete (streaming mode)
|
||||
default: false
|
||||
example: true
|
||||
end-of-dialog:
|
||||
type: boolean
|
||||
description: Entire agent dialog is complete (streaming mode)
|
||||
default: false
|
||||
example: true
|
||||
answer:
|
||||
type: string
|
||||
description: Final answer (legacy non-streaming format)
|
||||
example: Paris is the capital of France.
|
||||
thought:
|
||||
type: string
|
||||
description: Agent reasoning (legacy format)
|
||||
example: I should search for information about the capital of France.
|
||||
observation:
|
||||
type: string
|
||||
description: Observation from actions (legacy format)
|
||||
example: Found information about Paris being the capital.
|
||||
error:
|
||||
type: object
|
||||
description: Error details if request failed
|
||||
properties:
|
||||
message:
|
||||
type: string
|
||||
description: Error message
|
||||
example: Failed to process agent request
|
||||
code:
|
||||
type: string
|
||||
description: Error code
|
||||
example: AGENT_ERROR
|
||||
|
|
@ -0,0 +1,58 @@
|
|||
type: object
|
||||
description: |
|
||||
Collection management request.
|
||||
|
||||
Operations: list-collections, update-collection, delete-collection
|
||||
required:
|
||||
- operation
|
||||
properties:
|
||||
operation:
|
||||
type: string
|
||||
enum:
|
||||
- list-collections
|
||||
- update-collection
|
||||
- delete-collection
|
||||
description: |
|
||||
Collection operation:
|
||||
- `list-collections`: List collections for user
|
||||
- `update-collection`: Create or update collection metadata
|
||||
- `delete-collection`: Delete collection
|
||||
user:
|
||||
type: string
|
||||
description: User identifier
|
||||
default: trustgraph
|
||||
example: alice
|
||||
collection:
|
||||
type: string
|
||||
description: Collection identifier (for update, delete)
|
||||
example: research
|
||||
timestamp:
|
||||
type: string
|
||||
description: ISO timestamp
|
||||
format: date-time
|
||||
example: "2024-01-15T10:30:00Z"
|
||||
name:
|
||||
type: string
|
||||
description: Human-readable collection name (for update)
|
||||
example: Research Papers
|
||||
description:
|
||||
type: string
|
||||
description: Collection description (for update)
|
||||
example: Academic research papers on AI and ML
|
||||
tags:
|
||||
type: array
|
||||
description: Collection tags for organization (for update)
|
||||
items:
|
||||
type: string
|
||||
example: ["research", "AI", "academic"]
|
||||
tag-filter:
|
||||
type: array
|
||||
description: Filter collections by tags (for list)
|
||||
items:
|
||||
type: string
|
||||
example: ["research"]
|
||||
limit:
|
||||
type: integer
|
||||
description: Maximum number of results (for list)
|
||||
default: 0
|
||||
example: 100
|
||||
|
|
@ -0,0 +1,39 @@
|
|||
type: object
|
||||
description: Collection management response
|
||||
properties:
|
||||
timestamp:
|
||||
type: string
|
||||
description: ISO timestamp
|
||||
format: date-time
|
||||
example: "2024-01-15T10:30:00Z"
|
||||
collections:
|
||||
type: array
|
||||
description: List of collections (returned by list-collections)
|
||||
items:
|
||||
type: object
|
||||
required:
|
||||
- user
|
||||
- collection
|
||||
properties:
|
||||
user:
|
||||
type: string
|
||||
description: User identifier
|
||||
example: alice
|
||||
collection:
|
||||
type: string
|
||||
description: Collection identifier
|
||||
example: research
|
||||
name:
|
||||
type: string
|
||||
description: Human-readable collection name
|
||||
example: Research Papers
|
||||
description:
|
||||
type: string
|
||||
description: Collection description
|
||||
example: Academic research papers on AI and ML
|
||||
tags:
|
||||
type: array
|
||||
description: Collection tags
|
||||
items:
|
||||
type: string
|
||||
example: ["research", "AI", "academic"]
|
||||
128
specs/api/components/schemas/knowledge/KnowledgeRequest.yaml
Normal file
128
specs/api/components/schemas/knowledge/KnowledgeRequest.yaml
Normal file
|
|
@ -0,0 +1,128 @@
|
|||
type: object
|
||||
description: |
|
||||
Knowledge graph core management request.
|
||||
|
||||
Operations: list-kg-cores, get-kg-core, put-kg-core, delete-kg-core,
|
||||
load-kg-core, unload-kg-core
|
||||
required:
|
||||
- operation
|
||||
properties:
|
||||
operation:
|
||||
type: string
|
||||
enum:
|
||||
- list-kg-cores
|
||||
- get-kg-core
|
||||
- put-kg-core
|
||||
- delete-kg-core
|
||||
- load-kg-core
|
||||
- unload-kg-core
|
||||
description: |
|
||||
Knowledge core operation:
|
||||
- `list-kg-cores`: List knowledge cores for user
|
||||
- `get-kg-core`: Get knowledge core by ID
|
||||
- `put-kg-core`: Store triples and/or embeddings
|
||||
- `delete-kg-core`: Delete knowledge core by ID
|
||||
- `load-kg-core`: Load knowledge core into flow
|
||||
- `unload-kg-core`: Unload knowledge core from flow
|
||||
user:
|
||||
type: string
|
||||
description: User identifier (for list-kg-cores, put-kg-core, delete-kg-core)
|
||||
default: trustgraph
|
||||
example: alice
|
||||
id:
|
||||
type: string
|
||||
description: Knowledge core ID (for get, put, delete, load, unload)
|
||||
example: core-123
|
||||
flow:
|
||||
type: string
|
||||
description: Flow ID (for load-kg-core)
|
||||
example: my-flow
|
||||
collection:
|
||||
type: string
|
||||
description: Collection identifier (for load-kg-core)
|
||||
default: default
|
||||
example: default
|
||||
triples:
|
||||
type: object
|
||||
description: Triples to store (for put-kg-core)
|
||||
required:
|
||||
- metadata
|
||||
- triples
|
||||
properties:
|
||||
metadata:
|
||||
type: object
|
||||
required:
|
||||
- id
|
||||
- user
|
||||
- collection
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
description: Knowledge core ID
|
||||
example: core-123
|
||||
user:
|
||||
type: string
|
||||
description: User identifier
|
||||
example: alice
|
||||
collection:
|
||||
type: string
|
||||
description: Collection identifier
|
||||
example: default
|
||||
metadata:
|
||||
type: array
|
||||
description: Metadata triples
|
||||
items:
|
||||
$ref: '../../common/Triple.yaml'
|
||||
triples:
|
||||
type: array
|
||||
description: Knowledge triples
|
||||
items:
|
||||
$ref: '../../common/Triple.yaml'
|
||||
graph-embeddings:
|
||||
type: object
|
||||
description: Graph embeddings to store (for put-kg-core)
|
||||
required:
|
||||
- metadata
|
||||
- entities
|
||||
properties:
|
||||
metadata:
|
||||
type: object
|
||||
required:
|
||||
- id
|
||||
- user
|
||||
- collection
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
description: Knowledge core ID
|
||||
example: core-123
|
||||
user:
|
||||
type: string
|
||||
description: User identifier
|
||||
example: alice
|
||||
collection:
|
||||
type: string
|
||||
description: Collection identifier
|
||||
example: default
|
||||
metadata:
|
||||
type: array
|
||||
description: Metadata triples
|
||||
items:
|
||||
$ref: '../../common/Triple.yaml'
|
||||
entities:
|
||||
type: array
|
||||
description: Entity embeddings
|
||||
items:
|
||||
type: object
|
||||
required:
|
||||
- entity
|
||||
- vectors
|
||||
properties:
|
||||
entity:
|
||||
$ref: '../../common/RdfValue.yaml'
|
||||
vectors:
|
||||
type: array
|
||||
description: Embedding vectors
|
||||
items:
|
||||
type: number
|
||||
example: [0.1, 0.2, 0.3]
|
||||
|
|
@ -0,0 +1,91 @@
|
|||
type: object
|
||||
description: Knowledge service response
|
||||
properties:
|
||||
ids:
|
||||
type: array
|
||||
description: List of knowledge core IDs (returned by list-kg-cores)
|
||||
items:
|
||||
type: string
|
||||
example: ["core-123", "core-456"]
|
||||
triples:
|
||||
type: object
|
||||
description: Triples data (returned by get-kg-core, streamed)
|
||||
properties:
|
||||
metadata:
|
||||
type: object
|
||||
required:
|
||||
- id
|
||||
- user
|
||||
- collection
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
description: Knowledge core ID
|
||||
example: core-123
|
||||
user:
|
||||
type: string
|
||||
description: User identifier
|
||||
example: alice
|
||||
collection:
|
||||
type: string
|
||||
description: Collection identifier
|
||||
example: default
|
||||
metadata:
|
||||
type: array
|
||||
description: Metadata triples
|
||||
items:
|
||||
$ref: '../../common/Triple.yaml'
|
||||
triples:
|
||||
type: array
|
||||
description: Knowledge triples
|
||||
items:
|
||||
$ref: '../../common/Triple.yaml'
|
||||
graph-embeddings:
|
||||
type: object
|
||||
description: Graph embeddings data (returned by get-kg-core, streamed)
|
||||
properties:
|
||||
metadata:
|
||||
type: object
|
||||
required:
|
||||
- id
|
||||
- user
|
||||
- collection
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
description: Knowledge core ID
|
||||
example: core-123
|
||||
user:
|
||||
type: string
|
||||
description: User identifier
|
||||
example: alice
|
||||
collection:
|
||||
type: string
|
||||
description: Collection identifier
|
||||
example: default
|
||||
metadata:
|
||||
type: array
|
||||
description: Metadata triples
|
||||
items:
|
||||
$ref: '../../common/Triple.yaml'
|
||||
entities:
|
||||
type: array
|
||||
description: Entity embeddings
|
||||
items:
|
||||
type: object
|
||||
required:
|
||||
- entity
|
||||
- vectors
|
||||
properties:
|
||||
entity:
|
||||
$ref: '../../common/RdfValue.yaml'
|
||||
vectors:
|
||||
type: array
|
||||
description: Embedding vectors
|
||||
items:
|
||||
type: number
|
||||
example: [0.1, 0.2, 0.3]
|
||||
eos:
|
||||
type: boolean
|
||||
description: End of stream marker (for streaming responses)
|
||||
example: true
|
||||
79
specs/api/components/schemas/librarian/LibrarianRequest.yaml
Normal file
79
specs/api/components/schemas/librarian/LibrarianRequest.yaml
Normal file
|
|
@ -0,0 +1,79 @@
|
|||
type: object
|
||||
description: |
|
||||
Librarian service request for document library management.
|
||||
|
||||
Operations: add-document, remove-document, list-documents,
|
||||
start-processing, stop-processing, list-processing
|
||||
required:
|
||||
- operation
|
||||
properties:
|
||||
operation:
|
||||
type: string
|
||||
enum:
|
||||
- add-document
|
||||
- remove-document
|
||||
- list-documents
|
||||
- start-processing
|
||||
- stop-processing
|
||||
- list-processing
|
||||
description: |
|
||||
Library operation:
|
||||
- `add-document`: Add document to library
|
||||
- `remove-document`: Remove document from library
|
||||
- `list-documents`: List documents in library
|
||||
- `start-processing`: Start processing library documents
|
||||
- `stop-processing`: Stop library processing
|
||||
- `list-processing`: List processing status
|
||||
flow:
|
||||
type: string
|
||||
description: Flow ID
|
||||
example: my-flow
|
||||
collection:
|
||||
type: string
|
||||
description: Collection identifier
|
||||
default: default
|
||||
example: default
|
||||
user:
|
||||
type: string
|
||||
description: User identifier
|
||||
default: trustgraph
|
||||
example: alice
|
||||
document-id:
|
||||
type: string
|
||||
description: Document identifier
|
||||
example: doc-123
|
||||
processing-id:
|
||||
type: string
|
||||
description: Processing task identifier
|
||||
example: proc-456
|
||||
document-metadata:
|
||||
$ref: '../common/DocumentMetadata.yaml'
|
||||
processing-metadata:
|
||||
$ref: '../common/ProcessingMetadata.yaml'
|
||||
content:
|
||||
type: string
|
||||
description: Document content (for add-document with inline content)
|
||||
example: This is the document content...
|
||||
criteria:
|
||||
type: array
|
||||
description: Search criteria for filtering documents
|
||||
items:
|
||||
type: object
|
||||
required:
|
||||
- key
|
||||
- value
|
||||
- operator
|
||||
properties:
|
||||
key:
|
||||
type: string
|
||||
description: Metadata field name
|
||||
example: author
|
||||
value:
|
||||
type: string
|
||||
description: Value to match
|
||||
example: John Doe
|
||||
operator:
|
||||
type: string
|
||||
enum: [eq, ne, gt, lt, contains]
|
||||
description: Comparison operator
|
||||
example: eq
|
||||
|
|
@ -0,0 +1,18 @@
|
|||
type: object
|
||||
description: Librarian service response
|
||||
properties:
|
||||
document-metadata:
|
||||
$ref: '../common/DocumentMetadata.yaml'
|
||||
content:
|
||||
type: string
|
||||
description: Document content
|
||||
document-metadatas:
|
||||
type: array
|
||||
description: List of documents (returned by list-documents)
|
||||
items:
|
||||
$ref: '../common/DocumentMetadata.yaml'
|
||||
processing-metadatas:
|
||||
type: array
|
||||
description: List of processing tasks (returned by list-processing)
|
||||
items:
|
||||
$ref: '../common/ProcessingMetadata.yaml'
|
||||
33
specs/api/components/schemas/rag/DocumentRagRequest.yaml
Normal file
33
specs/api/components/schemas/rag/DocumentRagRequest.yaml
Normal file
|
|
@ -0,0 +1,33 @@
|
|||
type: object
|
||||
description: |
|
||||
Document RAG (Retrieval-Augmented Generation) query request.
|
||||
Searches document embeddings and generates answer using retrieved context.
|
||||
required:
|
||||
- query
|
||||
properties:
|
||||
query:
|
||||
type: string
|
||||
description: User query or question
|
||||
example: What are the key findings in the research papers?
|
||||
user:
|
||||
type: string
|
||||
description: User identifier for multi-tenancy
|
||||
default: trustgraph
|
||||
example: alice
|
||||
collection:
|
||||
type: string
|
||||
description: Collection to search within
|
||||
default: default
|
||||
example: research
|
||||
doc-limit:
|
||||
type: integer
|
||||
description: Maximum number of documents to retrieve
|
||||
default: 20
|
||||
minimum: 1
|
||||
maximum: 100
|
||||
example: 10
|
||||
streaming:
|
||||
type: boolean
|
||||
description: Enable streaming response delivery
|
||||
default: false
|
||||
example: true
|
||||
24
specs/api/components/schemas/rag/DocumentRagResponse.yaml
Normal file
24
specs/api/components/schemas/rag/DocumentRagResponse.yaml
Normal file
|
|
@ -0,0 +1,24 @@
|
|||
type: object
|
||||
description: Document RAG response
|
||||
properties:
|
||||
response:
|
||||
type: string
|
||||
description: Generated response based on retrieved documents
|
||||
example: The research papers found three key findings...
|
||||
end-of-stream:
|
||||
type: boolean
|
||||
description: Indicates streaming is complete (streaming mode)
|
||||
default: false
|
||||
example: true
|
||||
error:
|
||||
type: object
|
||||
description: Error details if request failed
|
||||
properties:
|
||||
message:
|
||||
type: string
|
||||
description: Error message
|
||||
example: Failed to retrieve documents
|
||||
type:
|
||||
type: string
|
||||
description: Error type
|
||||
example: RETRIEVAL_ERROR
|
||||
54
specs/api/components/schemas/rag/GraphRagRequest.yaml
Normal file
54
specs/api/components/schemas/rag/GraphRagRequest.yaml
Normal file
|
|
@ -0,0 +1,54 @@
|
|||
type: object
|
||||
description: |
|
||||
Graph RAG (Retrieval-Augmented Generation) query request.
|
||||
Searches knowledge graph and generates answer using retrieved subgraph.
|
||||
required:
|
||||
- query
|
||||
properties:
|
||||
query:
|
||||
type: string
|
||||
description: User query or question
|
||||
example: What connections exist between quantum physics and computer science?
|
||||
user:
|
||||
type: string
|
||||
description: User identifier for multi-tenancy
|
||||
default: trustgraph
|
||||
example: alice
|
||||
collection:
|
||||
type: string
|
||||
description: Collection to search within
|
||||
default: default
|
||||
example: research
|
||||
entity-limit:
|
||||
type: integer
|
||||
description: Maximum number of entities to retrieve
|
||||
default: 50
|
||||
minimum: 1
|
||||
maximum: 200
|
||||
example: 30
|
||||
triple-limit:
|
||||
type: integer
|
||||
description: Maximum number of triples to retrieve per entity
|
||||
default: 30
|
||||
minimum: 1
|
||||
maximum: 100
|
||||
example: 20
|
||||
max-subgraph-size:
|
||||
type: integer
|
||||
description: Maximum total subgraph size (triples)
|
||||
default: 1000
|
||||
minimum: 10
|
||||
maximum: 5000
|
||||
example: 500
|
||||
max-path-length:
|
||||
type: integer
|
||||
description: Maximum path length for graph traversal
|
||||
default: 2
|
||||
minimum: 1
|
||||
maximum: 5
|
||||
example: 3
|
||||
streaming:
|
||||
type: boolean
|
||||
description: Enable streaming response delivery
|
||||
default: false
|
||||
example: true
|
||||
24
specs/api/components/schemas/rag/GraphRagResponse.yaml
Normal file
24
specs/api/components/schemas/rag/GraphRagResponse.yaml
Normal file
|
|
@ -0,0 +1,24 @@
|
|||
type: object
|
||||
description: Graph RAG response
|
||||
properties:
|
||||
response:
|
||||
type: string
|
||||
description: Generated response based on retrieved knowledge graph
|
||||
example: Quantum physics and computer science intersect in quantum computing...
|
||||
end-of-stream:
|
||||
type: boolean
|
||||
description: Indicates streaming is complete (streaming mode)
|
||||
default: false
|
||||
example: true
|
||||
error:
|
||||
type: object
|
||||
description: Error details if request failed
|
||||
properties:
|
||||
message:
|
||||
type: string
|
||||
description: Error message
|
||||
example: Failed to retrieve graph data
|
||||
type:
|
||||
type: string
|
||||
description: Error type
|
||||
example: GRAPH_ERROR
|
||||
|
|
@ -0,0 +1,20 @@
|
|||
type: object
|
||||
description: |
|
||||
Text completion request - direct LLM completion without RAG.
|
||||
required:
|
||||
- system
|
||||
- prompt
|
||||
properties:
|
||||
system:
|
||||
type: string
|
||||
description: System prompt that sets behavior and context for the LLM
|
||||
example: You are a helpful assistant that provides concise answers.
|
||||
prompt:
|
||||
type: string
|
||||
description: User prompt or question
|
||||
example: Explain the concept of recursion in programming.
|
||||
streaming:
|
||||
type: boolean
|
||||
description: Enable streaming response delivery
|
||||
default: false
|
||||
example: true
|
||||
|
|
@ -0,0 +1,26 @@
|
|||
type: object
|
||||
description: Text completion response
|
||||
required:
|
||||
- response
|
||||
properties:
|
||||
response:
|
||||
type: string
|
||||
description: Generated text response
|
||||
example: Recursion is a programming technique where a function calls itself...
|
||||
in-token:
|
||||
type: integer
|
||||
description: Number of input tokens consumed
|
||||
example: 45
|
||||
out-token:
|
||||
type: integer
|
||||
description: Number of output tokens generated
|
||||
example: 128
|
||||
model:
|
||||
type: string
|
||||
description: Model used for completion
|
||||
example: gpt-4
|
||||
end-of-stream:
|
||||
type: boolean
|
||||
description: Indicates streaming is complete (streaming mode)
|
||||
default: false
|
||||
example: true
|
||||
|
|
@ -99,6 +99,22 @@ paths:
|
|||
$ref: './paths/config.yaml'
|
||||
/api/v1/flow:
|
||||
$ref: './paths/flow.yaml'
|
||||
/api/v1/librarian:
|
||||
$ref: './paths/librarian.yaml'
|
||||
/api/v1/knowledge:
|
||||
$ref: './paths/knowledge.yaml'
|
||||
/api/v1/collection-management:
|
||||
$ref: './paths/collection-management.yaml'
|
||||
|
||||
# Flow-hosted services (require running flow instance)
|
||||
/api/v1/flow/{flow}/service/agent:
|
||||
$ref: './paths/flow/agent.yaml'
|
||||
/api/v1/flow/{flow}/service/document-rag:
|
||||
$ref: './paths/flow/document-rag.yaml'
|
||||
/api/v1/flow/{flow}/service/graph-rag:
|
||||
$ref: './paths/flow/graph-rag.yaml'
|
||||
/api/v1/flow/{flow}/service/text-completion:
|
||||
$ref: './paths/flow/text-completion.yaml'
|
||||
# More services will be added here as we build them
|
||||
|
||||
components:
|
||||
|
|
|
|||
108
specs/api/paths/collection-management.yaml
Normal file
108
specs/api/paths/collection-management.yaml
Normal file
|
|
@ -0,0 +1,108 @@
|
|||
post:
|
||||
tags:
|
||||
- Collection
|
||||
summary: Collection metadata management
|
||||
description: |
|
||||
Manage collection metadata for organizing documents and knowledge.
|
||||
|
||||
## Collections
|
||||
|
||||
Collections are organizational units for grouping:
|
||||
- Documents in the librarian
|
||||
- Knowledge cores
|
||||
- User data
|
||||
|
||||
Each collection has:
|
||||
- **user**: Owner identifier
|
||||
- **collection**: Unique collection ID
|
||||
- **name**: Human-readable display name
|
||||
- **description**: Purpose and contents
|
||||
- **tags**: Labels for filtering and organization
|
||||
|
||||
## Operations
|
||||
|
||||
### list-collections
|
||||
List all collections for a user. Optionally filter by tags and limit results.
|
||||
Returns array of collection metadata.
|
||||
|
||||
### update-collection
|
||||
Create or update collection metadata. If collection doesn't exist, it's created.
|
||||
If it exists, metadata is updated. Allows setting name, description, and tags.
|
||||
|
||||
### delete-collection
|
||||
Delete a collection by user and collection ID. This removes the metadata but
|
||||
typically does not delete the associated data (documents, knowledge cores).
|
||||
|
||||
operationId: collectionManagementService
|
||||
security:
|
||||
- bearerAuth: []
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '../components/schemas/collection/CollectionRequest.yaml'
|
||||
examples:
|
||||
listCollections:
|
||||
summary: List all collections for user
|
||||
value:
|
||||
operation: list-collections
|
||||
user: alice
|
||||
listCollectionsFiltered:
|
||||
summary: List collections filtered by tags
|
||||
value:
|
||||
operation: list-collections
|
||||
user: alice
|
||||
tag-filter: ["research", "AI"]
|
||||
limit: 50
|
||||
updateCollection:
|
||||
summary: Create/update collection
|
||||
value:
|
||||
operation: update-collection
|
||||
user: alice
|
||||
collection: research
|
||||
name: Research Papers
|
||||
description: Academic research papers on AI and ML
|
||||
tags: ["research", "AI", "academic"]
|
||||
timestamp: "2024-01-15T10:30:00Z"
|
||||
deleteCollection:
|
||||
summary: Delete collection
|
||||
value:
|
||||
operation: delete-collection
|
||||
user: alice
|
||||
collection: research
|
||||
responses:
|
||||
'200':
|
||||
description: Successful response
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '../components/schemas/collection/CollectionResponse.yaml'
|
||||
examples:
|
||||
listCollections:
|
||||
summary: List of collections
|
||||
value:
|
||||
timestamp: "2024-01-15T10:30:00Z"
|
||||
collections:
|
||||
- user: alice
|
||||
collection: research
|
||||
name: Research Papers
|
||||
description: Academic research papers on AI and ML
|
||||
tags: ["research", "AI", "academic"]
|
||||
- user: alice
|
||||
collection: personal
|
||||
name: Personal Documents
|
||||
description: Personal notes and documents
|
||||
tags: ["personal"]
|
||||
updateSuccess:
|
||||
summary: Update successful
|
||||
value:
|
||||
timestamp: "2024-01-15T10:30:00Z"
|
||||
deleteSuccess:
|
||||
summary: Delete successful
|
||||
value:
|
||||
timestamp: "2024-01-15T10:30:00Z"
|
||||
'401':
|
||||
$ref: '../components/responses/Unauthorized.yaml'
|
||||
'500':
|
||||
$ref: '../components/responses/Error.yaml'
|
||||
130
specs/api/paths/flow/agent.yaml
Normal file
130
specs/api/paths/flow/agent.yaml
Normal file
|
|
@ -0,0 +1,130 @@
|
|||
post:
|
||||
tags:
|
||||
- AI Services
|
||||
summary: Agent service - conversational AI with reasoning
|
||||
description: |
|
||||
AI agent that can understand questions, reason about them, and take actions.
|
||||
|
||||
## Agent Overview
|
||||
|
||||
The agent service provides a conversational AI that:
|
||||
- Understands natural language questions
|
||||
- Reasons about problems using thoughts
|
||||
- Takes actions to gather information
|
||||
- Provides coherent answers
|
||||
|
||||
## Request Format
|
||||
|
||||
Send a question with optional:
|
||||
- **state**: Continue from previous conversation
|
||||
- **history**: Previous agent steps for context
|
||||
- **group**: Collaborative agent identifiers
|
||||
- **streaming**: Enable streaming responses
|
||||
|
||||
## Response Modes
|
||||
|
||||
### Streaming Mode (streaming: true)
|
||||
Responses arrive as chunks with `chunk-type`:
|
||||
- `thought`: Agent's reasoning process
|
||||
- `action`: Action being taken
|
||||
- `observation`: Result from action
|
||||
- `answer`: Final response to user
|
||||
- `error`: Error occurred
|
||||
|
||||
Each chunk may have multiple messages. Check flags:
|
||||
- `end-of-message`: Current chunk type complete
|
||||
- `end-of-dialog`: Entire conversation complete
|
||||
|
||||
### Legacy Mode (streaming: false)
|
||||
Single response with:
|
||||
- `answer`: Complete answer
|
||||
- `thought`: Reasoning (if any)
|
||||
- `observation`: Observations (if any)
|
||||
|
||||
## Multi-turn Conversations
|
||||
|
||||
Include `history` array with previous steps to maintain context.
|
||||
Each step has: thought, action, arguments, observation.
|
||||
|
||||
operationId: agentService
|
||||
security:
|
||||
- bearerAuth: []
|
||||
parameters:
|
||||
- name: flow
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
description: Flow instance ID
|
||||
example: my-flow
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '../../components/schemas/agent/AgentRequest.yaml'
|
||||
examples:
|
||||
simpleQuestion:
|
||||
summary: Simple question
|
||||
value:
|
||||
question: What is the capital of France?
|
||||
user: alice
|
||||
streamingQuestion:
|
||||
summary: Question with streaming enabled
|
||||
value:
|
||||
question: Explain quantum computing
|
||||
user: alice
|
||||
streaming: true
|
||||
conversationWithHistory:
|
||||
summary: Multi-turn conversation
|
||||
value:
|
||||
question: And what about its population?
|
||||
user: alice
|
||||
history:
|
||||
- thought: User is asking about the capital of France
|
||||
action: search
|
||||
arguments:
|
||||
query: "capital of France"
|
||||
observation: "Paris is the capital of France"
|
||||
user: alice
|
||||
responses:
|
||||
'200':
|
||||
description: Successful response
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '../../components/schemas/agent/AgentResponse.yaml'
|
||||
examples:
|
||||
streamingThought:
|
||||
summary: Streaming thought chunk
|
||||
value:
|
||||
chunk-type: thought
|
||||
content: I need to search for information about quantum computing
|
||||
end-of-message: false
|
||||
end-of-dialog: false
|
||||
streamingAnswer:
|
||||
summary: Streaming answer chunk
|
||||
value:
|
||||
chunk-type: answer
|
||||
content: Quantum computing uses quantum mechanics principles...
|
||||
end-of-message: false
|
||||
end-of-dialog: false
|
||||
streamingComplete:
|
||||
summary: Streaming complete marker
|
||||
value:
|
||||
chunk-type: answer
|
||||
content: ""
|
||||
end-of-message: true
|
||||
end-of-dialog: true
|
||||
legacyResponse:
|
||||
summary: Legacy non-streaming response
|
||||
value:
|
||||
answer: Paris is the capital of France.
|
||||
thought: User is asking about the capital of France
|
||||
observation: ""
|
||||
end-of-message: false
|
||||
end-of-dialog: false
|
||||
'401':
|
||||
$ref: '../../components/responses/Unauthorized.yaml'
|
||||
'500':
|
||||
$ref: '../../components/responses/Error.yaml'
|
||||
107
specs/api/paths/flow/document-rag.yaml
Normal file
107
specs/api/paths/flow/document-rag.yaml
Normal file
|
|
@ -0,0 +1,107 @@
|
|||
post:
|
||||
tags:
|
||||
- AI Services
|
||||
summary: Document RAG - retrieve and generate from documents
|
||||
description: |
|
||||
Retrieval-Augmented Generation over document embeddings.
|
||||
|
||||
## Document RAG Overview
|
||||
|
||||
Document RAG combines:
|
||||
1. **Retrieval**: Search document embeddings using semantic similarity
|
||||
2. **Generation**: Use LLM to synthesize answer from retrieved documents
|
||||
|
||||
This provides grounded answers based on your document corpus.
|
||||
|
||||
## Query Process
|
||||
|
||||
1. Convert query to embedding
|
||||
2. Search document embeddings for most similar chunks
|
||||
3. Retrieve top N document chunks (configurable via doc-limit)
|
||||
4. Pass query + retrieved context to LLM
|
||||
5. Generate answer grounded in documents
|
||||
|
||||
## Streaming
|
||||
|
||||
Enable `streaming: true` to receive the answer as it's generated:
|
||||
- Multiple messages with `response` content
|
||||
- Final message with `end-of-stream: true`
|
||||
|
||||
Without streaming, returns complete answer in single response.
|
||||
|
||||
## Parameters
|
||||
|
||||
- **doc-limit**: Controls retrieval depth (1-100, default 20)
|
||||
- Higher = more context but slower
|
||||
- Lower = faster but may miss relevant info
|
||||
- **collection**: Target specific document collection
|
||||
- **user**: Multi-tenant isolation
|
||||
|
||||
operationId: documentRagService
|
||||
security:
|
||||
- bearerAuth: []
|
||||
parameters:
|
||||
- name: flow
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
description: Flow instance ID
|
||||
example: my-flow
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '../../components/schemas/rag/DocumentRagRequest.yaml'
|
||||
examples:
|
||||
basicQuery:
|
||||
summary: Basic document query
|
||||
value:
|
||||
query: What are the key findings in the research papers?
|
||||
user: alice
|
||||
collection: research
|
||||
streamingQuery:
|
||||
summary: Streaming query
|
||||
value:
|
||||
query: Summarize the main conclusions
|
||||
user: alice
|
||||
collection: research
|
||||
doc-limit: 15
|
||||
streaming: true
|
||||
limitedRetrieval:
|
||||
summary: Query with limited retrieval
|
||||
value:
|
||||
query: What is quantum entanglement?
|
||||
doc-limit: 5
|
||||
responses:
|
||||
'200':
|
||||
description: Successful response
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '../../components/schemas/rag/DocumentRagResponse.yaml'
|
||||
examples:
|
||||
completeResponse:
|
||||
summary: Complete non-streaming response
|
||||
value:
|
||||
response: |
|
||||
The research papers present three key findings:
|
||||
1. Quantum entanglement exhibits non-local correlations
|
||||
2. Bell's inequality is violated in experimental tests
|
||||
3. Applications in quantum cryptography are promising
|
||||
end-of-stream: false
|
||||
streamingChunk:
|
||||
summary: Streaming response chunk
|
||||
value:
|
||||
response: "The research papers present three"
|
||||
end-of-stream: false
|
||||
streamingComplete:
|
||||
summary: Streaming complete marker
|
||||
value:
|
||||
response: ""
|
||||
end-of-stream: true
|
||||
'401':
|
||||
$ref: '../../components/responses/Unauthorized.yaml'
|
||||
'500':
|
||||
$ref: '../../components/responses/Error.yaml'
|
||||
127
specs/api/paths/flow/graph-rag.yaml
Normal file
127
specs/api/paths/flow/graph-rag.yaml
Normal file
|
|
@ -0,0 +1,127 @@
|
|||
post:
|
||||
tags:
|
||||
- AI Services
|
||||
summary: Graph RAG - retrieve and generate from knowledge graph
|
||||
description: |
|
||||
Retrieval-Augmented Generation over knowledge graph.
|
||||
|
||||
## Graph RAG Overview
|
||||
|
||||
Graph RAG combines:
|
||||
1. **Retrieval**: Find relevant entities and subgraph from knowledge graph
|
||||
2. **Generation**: Use LLM to reason over graph structure and generate answer
|
||||
|
||||
This provides graph-aware answers that leverage relationships and structure.
|
||||
|
||||
## Query Process
|
||||
|
||||
1. Identify relevant entities from query (using embeddings)
|
||||
2. Retrieve connected subgraph around entities
|
||||
3. Optionally traverse paths up to max-path-length hops
|
||||
4. Limit subgraph size to stay within context window
|
||||
5. Pass query + graph structure to LLM
|
||||
6. Generate answer incorporating graph relationships
|
||||
|
||||
## Streaming
|
||||
|
||||
Enable `streaming: true` to receive the answer as it's generated:
|
||||
- Multiple messages with `response` content
|
||||
- Final message with `end-of-stream: true`
|
||||
|
||||
Without streaming, returns complete answer in single response.
|
||||
|
||||
## Parameters
|
||||
|
||||
Control retrieval scope with multiple knobs:
|
||||
- **entity-limit**: How many starting entities to find (1-200, default 50)
|
||||
- **triple-limit**: Triples per entity (1-100, default 30)
|
||||
- **max-subgraph-size**: Total subgraph cap (10-5000, default 1000)
|
||||
- **max-path-length**: Graph traversal depth (1-5, default 2)
|
||||
|
||||
Higher limits = more context but:
|
||||
- Slower retrieval
|
||||
- Larger context for LLM
|
||||
- May hit context window limits
|
||||
|
||||
## Use Cases
|
||||
|
||||
Best for queries requiring:
|
||||
- Relationship understanding ("How are X and Y connected?")
|
||||
- Multi-hop reasoning ("What's the path from A to B?")
|
||||
- Structural analysis ("What are the main entities related to X?")
|
||||
|
||||
operationId: graphRagService
|
||||
security:
|
||||
- bearerAuth: []
|
||||
parameters:
|
||||
- name: flow
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
description: Flow instance ID
|
||||
example: my-flow
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '../../components/schemas/rag/GraphRagRequest.yaml'
|
||||
examples:
|
||||
basicQuery:
|
||||
summary: Basic graph query
|
||||
value:
|
||||
query: What connections exist between quantum physics and computer science?
|
||||
user: alice
|
||||
collection: research
|
||||
streamingQuery:
|
||||
summary: Streaming query with custom limits
|
||||
value:
|
||||
query: Trace the historical development of AI from Turing to modern LLMs
|
||||
user: alice
|
||||
collection: research
|
||||
entity-limit: 40
|
||||
triple-limit: 25
|
||||
max-subgraph-size: 800
|
||||
max-path-length: 3
|
||||
streaming: true
|
||||
focusedQuery:
|
||||
summary: Focused query with tight limits
|
||||
value:
|
||||
query: What is the immediate relationship between entity A and B?
|
||||
entity-limit: 10
|
||||
triple-limit: 15
|
||||
max-subgraph-size: 200
|
||||
max-path-length: 1
|
||||
responses:
|
||||
'200':
|
||||
description: Successful response
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '../../components/schemas/rag/GraphRagResponse.yaml'
|
||||
examples:
|
||||
completeResponse:
|
||||
summary: Complete non-streaming response
|
||||
value:
|
||||
response: |
|
||||
Quantum physics and computer science intersect primarily through quantum computing.
|
||||
The knowledge graph shows connections through:
|
||||
- Quantum algorithms (Shor's algorithm, Grover's algorithm)
|
||||
- Quantum information theory
|
||||
- Computational complexity theory
|
||||
end-of-stream: false
|
||||
streamingChunk:
|
||||
summary: Streaming response chunk
|
||||
value:
|
||||
response: "Quantum physics and computer science intersect"
|
||||
end-of-stream: false
|
||||
streamingComplete:
|
||||
summary: Streaming complete marker
|
||||
value:
|
||||
response: ""
|
||||
end-of-stream: true
|
||||
'401':
|
||||
$ref: '../../components/responses/Unauthorized.yaml'
|
||||
'500':
|
||||
$ref: '../../components/responses/Error.yaml'
|
||||
125
specs/api/paths/flow/text-completion.yaml
Normal file
125
specs/api/paths/flow/text-completion.yaml
Normal file
|
|
@ -0,0 +1,125 @@
|
|||
post:
|
||||
tags:
|
||||
- AI Services
|
||||
summary: Text completion - direct LLM generation
|
||||
description: |
|
||||
Direct text completion using LLM without retrieval augmentation.
|
||||
|
||||
## Text Completion Overview
|
||||
|
||||
Pure LLM generation for:
|
||||
- General knowledge questions
|
||||
- Creative writing
|
||||
- Code generation
|
||||
- Analysis and reasoning
|
||||
- Any task not requiring specific document/graph context
|
||||
|
||||
## System vs Prompt
|
||||
|
||||
- **system**: Sets LLM behavior, role, constraints
|
||||
- "You are a helpful assistant"
|
||||
- "You are an expert Python developer"
|
||||
- "Respond in JSON format"
|
||||
- **prompt**: The actual user request/question
|
||||
|
||||
## Streaming
|
||||
|
||||
Enable `streaming: true` to receive tokens as generated:
|
||||
- Multiple messages with partial `response`
|
||||
- Final message with `end-of-stream: true`
|
||||
|
||||
Without streaming, returns complete response in single message.
|
||||
|
||||
## Token Counting
|
||||
|
||||
Response includes token usage:
|
||||
- `in-token`: Input tokens (system + prompt)
|
||||
- `out-token`: Generated tokens
|
||||
- Useful for cost tracking and optimization
|
||||
|
||||
## When to Use
|
||||
|
||||
Use text-completion when:
|
||||
- No specific context needed (general knowledge)
|
||||
- System prompt provides sufficient context
|
||||
- Want direct control over prompting
|
||||
|
||||
Use document-rag/graph-rag when:
|
||||
- Need to ground response in specific documents
|
||||
- Want to leverage knowledge graph relationships
|
||||
- Require citations or provenance
|
||||
|
||||
operationId: textCompletionService
|
||||
security:
|
||||
- bearerAuth: []
|
||||
parameters:
|
||||
- name: flow
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
description: Flow instance ID
|
||||
example: my-flow
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '../../components/schemas/text-completion/TextCompletionRequest.yaml'
|
||||
examples:
|
||||
basicCompletion:
|
||||
summary: Basic text completion
|
||||
value:
|
||||
system: You are a helpful assistant that provides concise answers.
|
||||
prompt: Explain the concept of recursion in programming.
|
||||
codeGeneration:
|
||||
summary: Code generation with streaming
|
||||
value:
|
||||
system: You are an expert Python developer. Provide clean, well-documented code.
|
||||
prompt: Write a function to calculate the Fibonacci sequence using memoization.
|
||||
streaming: true
|
||||
jsonResponse:
|
||||
summary: Structured output request
|
||||
value:
|
||||
system: You are a JSON API. Respond only with valid JSON, no other text.
|
||||
prompt: |
|
||||
Extract key information from this text and return as JSON with fields:
|
||||
title, author, year, summary.
|
||||
|
||||
Text: "The Theory of Everything by Stephen Hawking (2006) explores..."
|
||||
responses:
|
||||
'200':
|
||||
description: Successful response
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '../../components/schemas/text-completion/TextCompletionResponse.yaml'
|
||||
examples:
|
||||
completeResponse:
|
||||
summary: Complete non-streaming response
|
||||
value:
|
||||
response: |
|
||||
Recursion is a programming technique where a function calls itself
|
||||
to solve a problem by breaking it down into smaller, similar subproblems.
|
||||
Each recursive call works on a simpler version until reaching a base case.
|
||||
in-token: 45
|
||||
out-token: 128
|
||||
model: gpt-4
|
||||
end-of-stream: false
|
||||
streamingChunk:
|
||||
summary: Streaming response chunk
|
||||
value:
|
||||
response: "Recursion is a programming technique"
|
||||
end-of-stream: false
|
||||
streamingComplete:
|
||||
summary: Streaming complete with tokens
|
||||
value:
|
||||
response: ""
|
||||
in-token: 45
|
||||
out-token: 128
|
||||
model: gpt-4
|
||||
end-of-stream: true
|
||||
'401':
|
||||
$ref: '../../components/responses/Unauthorized.yaml'
|
||||
'500':
|
||||
$ref: '../../components/responses/Error.yaml'
|
||||
196
specs/api/paths/knowledge.yaml
Normal file
196
specs/api/paths/knowledge.yaml
Normal file
|
|
@ -0,0 +1,196 @@
|
|||
post:
|
||||
tags:
|
||||
- Knowledge
|
||||
summary: Knowledge graph core management
|
||||
description: |
|
||||
Manage knowledge graph cores - persistent storage of triples and embeddings.
|
||||
|
||||
## Knowledge Cores
|
||||
|
||||
Knowledge cores are the foundational storage units for:
|
||||
- **Triples**: RDF triples representing knowledge graph data
|
||||
- **Graph Embeddings**: Vector embeddings for entities
|
||||
- **Metadata**: Descriptive information about the knowledge
|
||||
|
||||
Each core has an ID, user, and collection for organization.
|
||||
|
||||
## Operations
|
||||
|
||||
### list-kg-cores
|
||||
List all knowledge cores for a user. Returns array of core IDs.
|
||||
|
||||
### get-kg-core
|
||||
Retrieve a knowledge core by ID. Returns triples and/or graph embeddings.
|
||||
Response is streamed - may receive multiple messages followed by EOS marker.
|
||||
|
||||
### put-kg-core
|
||||
Store triples and/or graph embeddings. Creates new core or updates existing.
|
||||
Can store triples only, embeddings only, or both together.
|
||||
|
||||
### delete-kg-core
|
||||
Delete a knowledge core by ID. Removes all associated data.
|
||||
|
||||
### load-kg-core
|
||||
Load a knowledge core into a running flow's collection.
|
||||
Makes the data available for querying within that flow instance.
|
||||
|
||||
### unload-kg-core
|
||||
Unload a knowledge core from a flow's collection.
|
||||
Removes data from flow instance but doesn't delete the core.
|
||||
|
||||
## Streaming Responses
|
||||
|
||||
The `get-kg-core` operation streams data in chunks:
|
||||
1. Multiple messages with `triples` or `graph-embeddings`
|
||||
2. Final message with `eos: true` to signal completion
|
||||
|
||||
operationId: knowledgeService
|
||||
security:
|
||||
- bearerAuth: []
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '../components/schemas/knowledge/KnowledgeRequest.yaml'
|
||||
examples:
|
||||
listKnowledgeCores:
|
||||
summary: List knowledge cores
|
||||
value:
|
||||
operation: list-kg-cores
|
||||
user: alice
|
||||
getKnowledgeCore:
|
||||
summary: Get knowledge core
|
||||
value:
|
||||
operation: get-kg-core
|
||||
id: core-123
|
||||
putTriplesOnly:
|
||||
summary: Store triples
|
||||
value:
|
||||
operation: put-kg-core
|
||||
triples:
|
||||
metadata:
|
||||
id: core-123
|
||||
user: alice
|
||||
collection: default
|
||||
metadata:
|
||||
- s: {v: "https://example.com/core-123", e: true}
|
||||
p: {v: "https://www.w3.org/1999/02/22-rdf-syntax-ns#type", e: true}
|
||||
o: {v: "https://trustgraph.ai/e/knowledge-core", e: true}
|
||||
triples:
|
||||
- s: {v: "https://example.com/entity1", e: true}
|
||||
p: {v: "https://www.w3.org/2000/01/rdf-schema#label", e: true}
|
||||
o: {v: "Entity 1", e: false}
|
||||
- s: {v: "https://example.com/entity1", e: true}
|
||||
p: {v: "https://example.com/relatedTo", e: true}
|
||||
o: {v: "https://example.com/entity2", e: true}
|
||||
putEmbeddingsOnly:
|
||||
summary: Store embeddings
|
||||
value:
|
||||
operation: put-kg-core
|
||||
graph-embeddings:
|
||||
metadata:
|
||||
id: core-123
|
||||
user: alice
|
||||
collection: default
|
||||
metadata: []
|
||||
entities:
|
||||
- entity: {v: "https://example.com/entity1", e: true}
|
||||
vectors: [0.1, 0.2, 0.3, 0.4, 0.5]
|
||||
- entity: {v: "https://example.com/entity2", e: true}
|
||||
vectors: [0.6, 0.7, 0.8, 0.9, 1.0]
|
||||
putTriplesAndEmbeddings:
|
||||
summary: Store triples and embeddings together
|
||||
value:
|
||||
operation: put-kg-core
|
||||
triples:
|
||||
metadata:
|
||||
id: core-456
|
||||
user: bob
|
||||
collection: research
|
||||
metadata: []
|
||||
triples:
|
||||
- s: {v: "https://example.com/doc1", e: true}
|
||||
p: {v: "http://purl.org/dc/terms/title", e: true}
|
||||
o: {v: "Research Paper", e: false}
|
||||
graph-embeddings:
|
||||
metadata:
|
||||
id: core-456
|
||||
user: bob
|
||||
collection: research
|
||||
metadata: []
|
||||
entities:
|
||||
- entity: {v: "https://example.com/doc1", e: true}
|
||||
vectors: [0.11, 0.22, 0.33]
|
||||
deleteKnowledgeCore:
|
||||
summary: Delete knowledge core
|
||||
value:
|
||||
operation: delete-kg-core
|
||||
id: core-123
|
||||
user: alice
|
||||
loadKnowledgeCore:
|
||||
summary: Load core into flow
|
||||
value:
|
||||
operation: load-kg-core
|
||||
id: core-123
|
||||
flow: my-flow
|
||||
collection: default
|
||||
unloadKnowledgeCore:
|
||||
summary: Unload core from flow
|
||||
value:
|
||||
operation: unload-kg-core
|
||||
id: core-123
|
||||
responses:
|
||||
'200':
|
||||
description: Successful response
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '../components/schemas/knowledge/KnowledgeResponse.yaml'
|
||||
examples:
|
||||
listKnowledgeCores:
|
||||
summary: List of knowledge cores
|
||||
value:
|
||||
ids:
|
||||
- core-123
|
||||
- core-456
|
||||
- core-789
|
||||
getKnowledgeCoreTriples:
|
||||
summary: Knowledge core triples (streaming)
|
||||
value:
|
||||
triples:
|
||||
metadata:
|
||||
id: core-123
|
||||
user: alice
|
||||
collection: default
|
||||
metadata:
|
||||
- s: {v: "https://example.com/core-123", e: true}
|
||||
p: {v: "https://www.w3.org/1999/02/22-rdf-syntax-ns#type", e: true}
|
||||
o: {v: "https://trustgraph.ai/e/knowledge-core", e: true}
|
||||
triples:
|
||||
- s: {v: "https://example.com/entity1", e: true}
|
||||
p: {v: "https://www.w3.org/2000/01/rdf-schema#label", e: true}
|
||||
o: {v: "Entity 1", e: false}
|
||||
getKnowledgeCoreEmbeddings:
|
||||
summary: Knowledge core embeddings (streaming)
|
||||
value:
|
||||
graph-embeddings:
|
||||
metadata:
|
||||
id: core-123
|
||||
user: alice
|
||||
collection: default
|
||||
metadata: []
|
||||
entities:
|
||||
- entity: {v: "https://example.com/entity1", e: true}
|
||||
vectors: [0.1, 0.2, 0.3, 0.4, 0.5]
|
||||
endOfStream:
|
||||
summary: End of stream marker
|
||||
value:
|
||||
eos: true
|
||||
deleteSuccess:
|
||||
summary: Delete successful (empty response)
|
||||
value: {}
|
||||
'401':
|
||||
$ref: '../components/responses/Unauthorized.yaml'
|
||||
'500':
|
||||
$ref: '../components/responses/Error.yaml'
|
||||
153
specs/api/paths/librarian.yaml
Normal file
153
specs/api/paths/librarian.yaml
Normal file
|
|
@ -0,0 +1,153 @@
|
|||
post:
|
||||
tags:
|
||||
- Librarian
|
||||
summary: Document library management
|
||||
description: |
|
||||
Manage document library: add, remove, list documents, and control processing.
|
||||
|
||||
## Document Library
|
||||
|
||||
The librarian service manages a persistent library of documents that can be:
|
||||
- Added with metadata for organization
|
||||
- Queried and filtered by criteria
|
||||
- Processed through flows on-demand or continuously
|
||||
- Tracked for processing status
|
||||
|
||||
## Operations
|
||||
|
||||
### add-document
|
||||
Add a document to the library with metadata (URL, title, author, etc.).
|
||||
Documents can be added by URL or with inline content.
|
||||
|
||||
### remove-document
|
||||
Remove a document from the library by document ID or URL.
|
||||
|
||||
### list-documents
|
||||
List all documents in the library, optionally filtered by criteria.
|
||||
|
||||
### start-processing
|
||||
Start processing library documents through a flow. Documents are queued
|
||||
for processing and handled asynchronously.
|
||||
|
||||
### stop-processing
|
||||
Stop ongoing library document processing.
|
||||
|
||||
### list-processing
|
||||
List current processing tasks and their status.
|
||||
|
||||
operationId: librarianService
|
||||
security:
|
||||
- bearerAuth: []
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '../components/schemas/librarian/LibrarianRequest.yaml'
|
||||
examples:
|
||||
addDocumentByUrl:
|
||||
summary: Add document by URL
|
||||
value:
|
||||
operation: add-document
|
||||
flow: my-flow
|
||||
collection: default
|
||||
document-metadata:
|
||||
url: https://example.com/document.pdf
|
||||
title: Example Document
|
||||
author: John Doe
|
||||
metadata:
|
||||
department: Engineering
|
||||
category: Technical
|
||||
addDocumentInline:
|
||||
summary: Add document with inline content
|
||||
value:
|
||||
operation: add-document
|
||||
flow: my-flow
|
||||
collection: default
|
||||
content: "This is the document content..."
|
||||
document-metadata:
|
||||
title: Inline Document
|
||||
author: Jane Smith
|
||||
removeDocument:
|
||||
summary: Remove document
|
||||
value:
|
||||
operation: remove-document
|
||||
flow: my-flow
|
||||
collection: default
|
||||
document-metadata:
|
||||
url: https://example.com/document.pdf
|
||||
listDocuments:
|
||||
summary: List all documents
|
||||
value:
|
||||
operation: list-documents
|
||||
flow: my-flow
|
||||
collection: default
|
||||
listDocumentsFiltered:
|
||||
summary: List documents with criteria
|
||||
value:
|
||||
operation: list-documents
|
||||
flow: my-flow
|
||||
collection: default
|
||||
criteria:
|
||||
- key: author
|
||||
value: John Doe
|
||||
operator: eq
|
||||
- key: department
|
||||
value: Engineering
|
||||
operator: eq
|
||||
startProcessing:
|
||||
summary: Start processing library documents
|
||||
value:
|
||||
operation: start-processing
|
||||
flow: my-flow
|
||||
collection: default
|
||||
stopProcessing:
|
||||
summary: Stop processing
|
||||
value:
|
||||
operation: stop-processing
|
||||
flow: my-flow
|
||||
collection: default
|
||||
listProcessing:
|
||||
summary: List processing status
|
||||
value:
|
||||
operation: list-processing
|
||||
flow: my-flow
|
||||
collection: default
|
||||
responses:
|
||||
'200':
|
||||
description: Successful response
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '../components/schemas/librarian/LibrarianResponse.yaml'
|
||||
examples:
|
||||
listDocuments:
|
||||
summary: List of documents
|
||||
value:
|
||||
document-metadatas:
|
||||
- url: https://example.com/doc1.pdf
|
||||
title: Document 1
|
||||
author: John Doe
|
||||
metadata:
|
||||
department: Engineering
|
||||
- url: https://example.com/doc2.pdf
|
||||
title: Document 2
|
||||
author: Jane Smith
|
||||
metadata:
|
||||
department: Research
|
||||
listProcessing:
|
||||
summary: Processing status
|
||||
value:
|
||||
processing-metadatas:
|
||||
- flow: my-flow
|
||||
collection: default
|
||||
status: processing
|
||||
timestamp: "2024-01-15T10:30:00Z"
|
||||
- flow: my-flow
|
||||
collection: default
|
||||
status: completed
|
||||
timestamp: "2024-01-15T10:25:00Z"
|
||||
'401':
|
||||
$ref: '../components/responses/Unauthorized.yaml'
|
||||
'500':
|
||||
$ref: '../components/responses/Error.yaml'
|
||||
Loading…
Add table
Add a link
Reference in a new issue