apunkt/trustgraph
1
0
Fork 0
mirror of https://github.com/trustgraph-ai/trustgraph.git synced 2026-04-26 00:46:22 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Python API docs (#614)

Browse source 
* Python API docs working

* Python API doc generation
This commit is contained in:
cybermaggedon 2026-01-15 15:12:32 +00:00 • committed by GitHub
parent 8a17375603
commit 1c006d5b14
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
14 changed files with 5508 additions and 64 deletions
Download patch file Download diff file Expand all files Collapse all files

52
trustgraph-base/trustgraph/api/__init__.py
View file

@ -1,3 +1,55 @@
"""
TrustGraph API Client Library
This package provides Python client interfaces for interacting with TrustGraph services.
TrustGraph is a knowledge graph and RAG (Retrieval-Augmented Generation) platform that
combines graph databases, vector embeddings, and LLM capabilities.
The library offers both synchronous and asynchronous APIs for:
- Flow management and execution
- Knowledge graph operations (triples, entities, embeddings)
- RAG queries (graph-based and document-based)
- Agent interactions with streaming support
- WebSocket-based real-time communication
- Bulk import/export operations
- Configuration and collection management
Quick Start:
```python
from trustgraph.api import Api
# Create API client
api = Api(url="http://localhost:8088/")
# Get a flow instance
flow = api.flow().id("default")
# Execute a graph RAG query
response = flow.graph_rag(
query="What are the main topics?",
user="trustgraph",
collection="default"
)
```
For streaming and async operations:
```python
# WebSocket streaming
socket = api.socket()
flow = socket.flow("default")
for chunk in flow.agent(question="Hello", user="trustgraph"):
print(chunk.content)
# Async operations
async with Api(url="http://localhost:8088/") as api:
async_flow = api.async_flow()
result = await async_flow.id("default").text_completion(
system="You are helpful",
prompt="Hello"
)
```
"""
# Core API
from .api import Api

388
trustgraph-base/trustgraph/api/api.py
View file

@ -1,3 +1,8 @@
"""
TrustGraph API Client
Core API client for interacting with TrustGraph services via REST and WebSocket protocols.
"""
import requests
import json
@ -26,8 +31,47 @@ def check_error(response):
raise ApplicationException(f"{tp}: {msg}")
class Api:
"""
Main TrustGraph API client for synchronous and asynchronous operations.
This class provides access to all TrustGraph services including flow management,
knowledge graph operations, document processing, RAG queries, and more. It supports
both REST-based and WebSocket-based communication patterns.
The client can be used as a context manager for automatic resource cleanup:
```python
with Api(url="http://localhost:8088/") as api:
result = api.flow().id("default").graph_rag(query="test")
```
Attributes:
url: Base URL for the TrustGraph API endpoint
timeout: Request timeout in seconds
token: Optional bearer token for authentication
"""
def __init__(self, url="http://localhost:8088/", timeout=60, token: Optional[str] = None):
"""
Initialize the TrustGraph API client.
Args:
url: Base URL for TrustGraph API (default: "http://localhost:8088/")
timeout: Request timeout in seconds (default: 60)
token: Optional bearer token for authentication
Example:
```python
# Local development
api = Api()
# Production with authentication
api = Api(
url="https://trustgraph.example.com/",
timeout=120,
token="your-api-token"
)
```
"""
self.url = url
@ -49,15 +93,97 @@ class Api:
self._async_metrics = None
def flow(self):
"""
Get a Flow client for managing and interacting with flows.
Flows are the primary execution units in TrustGraph, providing access to
services like agents, RAG queries, embeddings, and document processing.
Returns:
Flow: Flow management client
Example:
```python
flow_client = api.flow()
# List available blueprints
blueprints = flow_client.list_blueprints()
# Get a specific flow instance
flow_instance = flow_client.id("default")
response = flow_instance.text_completion(
system="You are helpful",
prompt="Hello"
)
```
"""
return Flow(api=self)
def config(self):
"""
Get a Config client for managing configuration settings.
Returns:
Config: Configuration management client
Example:
```python
config = api.config()
# Get configuration values
values = config.get([ConfigKey(type="llm", key="model")])
# Set configuration
config.put([ConfigValue(type="llm", key="model", value="gpt-4")])
```
"""
return Config(api=self)
def knowledge(self):
"""
Get a Knowledge client for managing knowledge graph cores.
Returns:
Knowledge: Knowledge graph management client
Example:
```python
knowledge = api.knowledge()
# List available KG cores
cores = knowledge.list_kg_cores(user="trustgraph")
# Load a KG core
knowledge.load_kg_core(id="core-123", user="trustgraph")
```
"""
return Knowledge(api=self)
def request(self, path, request):
"""
Make a low-level REST API request.
This method is primarily for internal use but can be used for direct
API access when needed.
Args:
path: API endpoint path (relative to base URL)
request: Request payload as a dictionary
Returns:
dict: Response object
Raises:
ProtocolException: If the response status is not 200 or response is not JSON
ApplicationException: If the response contains an error
Example:
```python
response = api.request("flow", {
"operation": "list-flows"
})
```
"""
url = f"{self.url}{path}"
@ -83,14 +209,90 @@ class Api:
return object
def library(self):
"""
Get a Library client for document management.
The library provides document storage, metadata management, and
processing workflow coordination.
Returns:
Library: Document library management client
Example:
```python
library = api.library()
# Add a document
library.add_document(
document=b"Document content",
id="doc-123",
metadata=[],
user="trustgraph",
title="My Document",
comments="Test document"
)
# List documents
docs = library.get_documents(user="trustgraph")
```
"""
return Library(self)
def collection(self):
"""
Get a Collection client for managing data collections.
Collections organize documents and knowledge graph data into
logical groupings for isolation and access control.
Returns:
Collection: Collection management client
Example:
```python
collection = api.collection()
# List collections
colls = collection.list_collections(user="trustgraph")
# Update collection metadata
collection.update_collection(
user="trustgraph",
collection="default",
name="Default Collection",
description="Main data collection"
)
```
"""
return Collection(self)
# New synchronous methods
def socket(self):
"""Synchronous WebSocket-based interface for streaming operations"""
"""
Get a synchronous WebSocket client for streaming operations.
WebSocket connections provide streaming support for real-time responses
from agents, RAG queries, and text completions. This method returns a
synchronous wrapper around the WebSocket protocol.
Returns:
SocketClient: Synchronous WebSocket client
Example:
```python
socket = api.socket()
flow = socket.flow("default")
# Stream agent responses
for chunk in flow.agent(
question="Explain quantum computing",
user="trustgraph",
streaming=True
):
if hasattr(chunk, 'content'):
print(chunk.content, end='', flush=True)
```
"""
if self._socket_client is None:
from . socket_client import SocketClient
# Extract base URL (remove api/v1/ suffix)
@ -99,7 +301,31 @@ class Api:
return self._socket_client
def bulk(self):
"""Synchronous bulk operations interface for import/export"""
"""
Get a synchronous bulk operations client for import/export.
Bulk operations allow efficient transfer of large datasets via WebSocket
connections, including triples, embeddings, entity contexts, and objects.
Returns:
BulkClient: Synchronous bulk operations client
Example:
```python
bulk = api.bulk()
# Export triples
for triple in bulk.export_triples(flow="default"):
print(f"{triple.s} {triple.p} {triple.o}")
# Import triples
def triple_generator():
yield Triple(s="subj", p="pred", o="obj")
# ... more triples
bulk.import_triples(flow="default", triples=triple_generator())
```
"""
if self._bulk_client is None:
from . bulk_client import BulkClient
# Extract base URL (remove api/v1/ suffix)
@ -108,7 +334,22 @@ class Api:
return self._bulk_client
def metrics(self):
"""Synchronous metrics interface"""
"""
Get a synchronous metrics client for monitoring.
Retrieves Prometheus-formatted metrics from the TrustGraph service
for monitoring and observability.
Returns:
Metrics: Synchronous metrics client
Example:
```python
metrics = api.metrics()
prometheus_text = metrics.get()
print(prometheus_text)
```
"""
if self._metrics is None:
from . metrics import Metrics
# Extract base URL (remove api/v1/ suffix)
@ -118,14 +359,60 @@ class Api:
# New asynchronous methods
def async_flow(self):
"""Asynchronous REST-based flow interface"""
"""
Get an asynchronous REST-based flow client.
Provides async/await style access to flow operations. This is preferred
for async Python applications and frameworks (FastAPI, aiohttp, etc.).
Returns:
AsyncFlow: Asynchronous flow client
Example:
```python
async_flow = api.async_flow()
# List flows
flow_ids = await async_flow.list()
# Execute operations
instance = async_flow.id("default")
result = await instance.text_completion(
system="You are helpful",
prompt="Hello"
)
```
"""
if self._async_flow is None:
from . async_flow import AsyncFlow
self._async_flow = AsyncFlow(self.url, self.timeout, self.token)
return self._async_flow
def async_socket(self):
"""Asynchronous WebSocket-based interface for streaming operations"""
"""
Get an asynchronous WebSocket client for streaming operations.
Provides async/await style WebSocket access with streaming support.
This is the preferred method for async streaming in Python.
Returns:
AsyncSocketClient: Asynchronous WebSocket client
Example:
```python
async_socket = api.async_socket()
flow = async_socket.flow("default")
# Stream agent responses
async for chunk in flow.agent(
question="Explain quantum computing",
user="trustgraph",
streaming=True
):
if hasattr(chunk, 'content'):
print(chunk.content, end='', flush=True)
```
"""
if self._async_socket_client is None:
from . async_socket_client import AsyncSocketClient
# Extract base URL (remove api/v1/ suffix)
@ -134,7 +421,34 @@ class Api:
return self._async_socket_client
def async_bulk(self):
"""Asynchronous bulk operations interface for import/export"""
"""
Get an asynchronous bulk operations client.
Provides async/await style bulk import/export operations via WebSocket
for efficient handling of large datasets.
Returns:
AsyncBulkClient: Asynchronous bulk operations client
Example:
```python
async_bulk = api.async_bulk()
# Export triples asynchronously
async for triple in async_bulk.export_triples(flow="default"):
print(f"{triple.s} {triple.p} {triple.o}")
# Import with async generator
async def triple_gen():
yield Triple(s="subj", p="pred", o="obj")
# ... more triples
await async_bulk.import_triples(
flow="default",
triples=triple_gen()
)
```
"""
if self._async_bulk_client is None:
from . async_bulk_client import AsyncBulkClient
# Extract base URL (remove api/v1/ suffix)
@ -143,7 +457,21 @@ class Api:
return self._async_bulk_client
def async_metrics(self):
"""Asynchronous metrics interface"""
"""
Get an asynchronous metrics client.
Provides async/await style access to Prometheus metrics.
Returns:
AsyncMetrics: Asynchronous metrics client
Example:
```python
async_metrics = api.async_metrics()
prometheus_text = await async_metrics.get()
print(prometheus_text)
```
"""
if self._async_metrics is None:
from . async_metrics import AsyncMetrics
# Extract base URL (remove api/v1/ suffix)
@ -153,14 +481,52 @@ class Api:
# Resource management
def close(self):
"""Close all synchronous connections"""
"""
Close all synchronous client connections.
This method closes WebSocket and bulk operation connections.
It is automatically called when exiting a context manager.
Example:
```python
api = Api()
socket = api.socket()
# ... use socket
api.close() # Clean up connections
# Or use context manager (automatic cleanup)
with Api() as api:
socket = api.socket()
# ... use socket
# Automatically closed
```
"""
if self._socket_client:
self._socket_client.close()
if self._bulk_client:
self._bulk_client.close()
async def aclose(self):
"""Close all asynchronous connections"""
"""
Close all asynchronous client connections.
This method closes async WebSocket, bulk operation, and flow connections.
It is automatically called when exiting an async context manager.
Example:
```python
api = Api()
async_socket = api.async_socket()
# ... use async_socket
await api.aclose() # Clean up connections
# Or use async context manager (automatic cleanup)
async with Api() as api:
async_socket = api.async_socket()
# ... use async_socket
# Automatically closed
```
"""
if self._async_socket_client:
await self._async_socket_client.aclose()
if self._async_bulk_client:
@ -170,13 +536,17 @@ class Api:
# Context manager support
def __enter__(self):
"""Enter synchronous context manager."""
return self
def __exit__(self, *args):
"""Exit synchronous context manager and close connections."""
self.close()
async def __aenter__(self):
"""Enter asynchronous context manager."""
return self
async def __aexit__(self, *args):
"""Exit asynchronous context manager and close connections."""
await self.aclose()

563
trustgraph-base/trustgraph/api/async_flow.py
View file

@ -1,3 +1,14 @@
"""
TrustGraph Asynchronous Flow Management
This module provides async/await based interfaces for managing and interacting
with TrustGraph flows using REST API calls. Unlike async_socket_client which
provides streaming support, this module is focused on non-streaming operations
that return complete responses.
For streaming support (e.g., real-time agent responses, streaming RAG), use
AsyncSocketClient instead.
"""
import aiohttp
import json
@ -18,15 +29,47 @@ def check_error(response):
class AsyncFlow:
"""Asynchronous REST-based flow interface"""
"""
Asynchronous flow management client using REST API.
Provides async/await based flow management operations including listing,
starting, stopping flows, and managing flow class definitions. Also provides
access to flow-scoped services like agents, RAG, and queries via non-streaming
REST endpoints.
Note: For streaming support, use AsyncSocketClient instead.
"""
def __init__(self, url: str, timeout: int, token: Optional[str]) -> None:
"""
Initialize async flow client.
Args:
url: Base URL for TrustGraph API
timeout: Request timeout in seconds
token: Optional bearer token for authentication
"""
self.url: str = url
self.timeout: int = timeout
self.token: Optional[str] = token
async def request(self, path: str, request_data: Dict[str, Any]) -> Dict[str, Any]:
"""Make async HTTP request to Gateway API"""
"""
Make async HTTP POST request to Gateway API.
Internal method for making authenticated requests to the TrustGraph API.
Args:
path: API endpoint path (relative to base URL)
request_data: Request payload dictionary
Returns:
dict: Response object from API
Raises:
ProtocolException: If HTTP status is not 200 or response is not valid JSON
ApplicationException: If API returns an error response
"""
url = f"{self.url}{path}"
headers = {"Content-Type": "application/json"}
@ -49,12 +92,49 @@ class AsyncFlow:
return obj
async def list(self) -> List[str]:
"""List all flows"""
"""
List all flow identifiers.
Retrieves IDs of all flows currently deployed in the system.
Returns:
list[str]: List of flow identifiers
Example:
```python
async_flow = await api.async_flow()
# List all flows
flows = await async_flow.list()
print(f"Available flows: {flows}")
```
"""
result = await self.request("flow", {"operation": "list-flows"})
return result.get("flow-ids", [])
async def get(self, id: str) -> Dict[str, Any]:
"""Get flow definition"""
"""
Get flow definition.
Retrieves the complete flow configuration including its class name,
description, and parameters.
Args:
id: Flow identifier
Returns:
dict: Flow definition object
Example:
```python
async_flow = await api.async_flow()
# Get flow definition
flow_def = await async_flow.get("default")
print(f"Flow class: {flow_def.get('class-name')}")
print(f"Description: {flow_def.get('description')}")
```
"""
result = await self.request("flow", {
"operation": "get-flow",
"flow-id": id
@ -62,7 +142,31 @@ class AsyncFlow:
return json.loads(result.get("flow", "{}"))
async def start(self, class_name: str, id: str, description: str, parameters: Optional[Dict] = None):
"""Start a flow"""
"""
Start a new flow instance.
Creates and starts a flow from a flow class definition with the specified
parameters.
Args:
class_name: Flow class name to instantiate
id: Identifier for the new flow instance
description: Human-readable description of the flow
parameters: Optional configuration parameters for the flow
Example:
```python
async_flow = await api.async_flow()
# Start a flow from a class
await async_flow.start(
class_name="default",
id="my-flow",
description="Custom flow instance",
parameters={"model": "claude-3-opus"}
)
```
"""
request_data = {
"operation": "start-flow",
"flow-id": id,
@ -75,19 +179,70 @@ class AsyncFlow:
await self.request("flow", request_data)
async def stop(self, id: str):
"""Stop a flow"""
"""
Stop a running flow.
Stops and removes a flow instance, freeing its resources.
Args:
id: Flow identifier to stop
Example:
```python
async_flow = await api.async_flow()
# Stop a flow
await async_flow.stop("my-flow")
```
"""
await self.request("flow", {
"operation": "stop-flow",
"flow-id": id
})
async def list_classes(self) -> List[str]:
"""List flow classes"""
"""
List all flow class names.
Retrieves names of all flow classes (blueprints) available in the system.
Returns:
list[str]: List of flow class names
Example:
```python
async_flow = await api.async_flow()
# List available flow classes
classes = await async_flow.list_classes()
print(f"Available flow classes: {classes}")
```
"""
result = await self.request("flow", {"operation": "list-classes"})
return result.get("class-names", [])
async def get_class(self, class_name: str) -> Dict[str, Any]:
"""Get flow class definition"""
"""
Get flow class definition.
Retrieves the blueprint definition for a flow class, including its
configuration schema and service bindings.
Args:
class_name: Flow class name
Returns:
dict: Flow class definition object
Example:
```python
async_flow = await api.async_flow()
# Get flow class definition
class_def = await async_flow.get_class("default")
print(f"Services: {class_def.get('services')}")
```
"""
result = await self.request("flow", {
"operation": "get-class",
"class-name": class_name
@ -95,7 +250,29 @@ class AsyncFlow:
return json.loads(result.get("class-definition", "{}"))
async def put_class(self, class_name: str, definition: Dict[str, Any]):
"""Create/update flow class"""
"""
Create or update a flow class definition.
Stores a flow class blueprint that can be used to instantiate flows.
Args:
class_name: Flow class name
definition: Flow class definition object
Example:
```python
async_flow = await api.async_flow()
# Create a custom flow class
class_def = {
"services": {
"agent": {"module": "agent", "config": {...}},
"graph-rag": {"module": "graph-rag", "config": {...}}
}
}
await async_flow.put_class("custom-flow", class_def)
```
"""
await self.request("flow", {
"operation": "put-class",
"class-name": class_name,
@ -103,35 +280,145 @@ class AsyncFlow:
})
async def delete_class(self, class_name: str):
"""Delete flow class"""
"""
Delete a flow class definition.
Removes a flow class blueprint from the system. Does not affect
running flow instances.
Args:
class_name: Flow class name to delete
Example:
```python
async_flow = await api.async_flow()
# Delete a flow class
await async_flow.delete_class("old-flow-class")
```
"""
await self.request("flow", {
"operation": "delete-class",
"class-name": class_name
})
def id(self, flow_id: str):
"""Get async flow instance"""
"""
Get an async flow instance client.
Returns a client for interacting with a specific flow's services
(agent, RAG, queries, embeddings, etc.).
Args:
flow_id: Flow identifier
Returns:
AsyncFlowInstance: Client for flow-specific operations
Example:
```python
async_flow = await api.async_flow()
# Get flow instance
flow = async_flow.id("default")
# Use flow services
result = await flow.graph_rag(
query="What is TrustGraph?",
user="trustgraph",
collection="default"
)
```
"""
return AsyncFlowInstance(self, flow_id)
async def aclose(self) -> None:
"""Close connection (cleanup handled by aiohttp session)"""
"""
Close async client and cleanup resources.
Note: Cleanup is handled automatically by aiohttp session context managers.
This method is provided for consistency with other async clients.
"""
pass
class AsyncFlowInstance:
"""Asynchronous REST flow instance"""
"""
Asynchronous flow instance client.
Provides async/await access to flow-scoped services including agents,
RAG queries, embeddings, and graph queries. All operations return complete
responses (non-streaming).
Note: For streaming support, use AsyncSocketFlowInstance instead.
"""
def __init__(self, flow: AsyncFlow, flow_id: str):
"""
Initialize async flow instance.
Args:
flow: Parent AsyncFlow client
flow_id: Flow identifier
"""
self.flow = flow
self.flow_id = flow_id
async def request(self, service: str, request_data: Dict[str, Any]) -> Dict[str, Any]:
"""Make request to flow-scoped service"""
"""
Make request to a flow-scoped service.
Internal method for calling services within this flow instance.
Args:
service: Service name (e.g., "agent", "graph-rag", "triples")
request_data: Service request payload
Returns:
dict: Service response object
Raises:
ProtocolException: If request fails or response is invalid
ApplicationException: If service returns an error
"""
return await self.flow.request(f"flow/{self.flow_id}/service/{service}", request_data)
async def agent(self, question: str, user: str, state: Optional[Dict] = None,
group: Optional[str] = None, history: Optional[List] = None, **kwargs: Any) -> Dict[str, Any]:
"""Execute agent (non-streaming, use async_socket for streaming)"""
"""
Execute an agent operation (non-streaming).
Runs an agent to answer a question, with optional conversation state and
history. Returns the complete response after the agent has finished
processing.
Note: This method does not support streaming. For real-time agent thoughts
and observations, use AsyncSocketFlowInstance.agent() instead.
Args:
question: User question or instruction
user: User identifier
state: Optional state dictionary for conversation context
group: Optional group identifier for session management
history: Optional conversation history list
**kwargs: Additional service-specific parameters
Returns:
dict: Complete agent response including answer and metadata
Example:
```python
async_flow = await api.async_flow()
flow = async_flow.id("default")
# Execute agent
result = await flow.agent(
question="What is the capital of France?",
user="trustgraph"
)
print(f"Answer: {result.get('response')}")
```
"""
request_data = {
"question": question,
"user": user,
@ -148,7 +435,36 @@ class AsyncFlowInstance:
return await self.request("agent", request_data)
async def text_completion(self, system: str, prompt: str, **kwargs: Any) -> str:
"""Text completion (non-streaming, use async_socket for streaming)"""
"""
Generate text completion (non-streaming).
Generates a text response from an LLM given a system prompt and user prompt.
Returns the complete response text.
Note: This method does not support streaming. For streaming text generation,
use AsyncSocketFlowInstance.text_completion() instead.
Args:
system: System prompt defining the LLM's behavior
prompt: User prompt or question
**kwargs: Additional service-specific parameters
Returns:
str: Complete generated text response
Example:
```python
async_flow = await api.async_flow()
flow = async_flow.id("default")
# Generate text
response = await flow.text_completion(
system="You are a helpful assistant.",
prompt="Explain quantum computing in simple terms."
)
print(response)
```
"""
request_data = {
"system": system,
"prompt": prompt,
@ -162,7 +478,43 @@ class AsyncFlowInstance:
async def graph_rag(self, query: str, user: str, collection: str,
max_subgraph_size: int = 1000, max_subgraph_count: int = 5,
max_entity_distance: int = 3, **kwargs: Any) -> str:
"""Graph RAG (non-streaming, use async_socket for streaming)"""
"""
Execute graph-based RAG query (non-streaming).
Performs Retrieval-Augmented Generation using knowledge graph data.
Identifies relevant entities and their relationships, then generates a
response grounded in the graph structure. Returns complete response.
Note: This method does not support streaming. For streaming RAG responses,
use AsyncSocketFlowInstance.graph_rag() instead.
Args:
query: User query text
user: User identifier
collection: Collection identifier containing the knowledge graph
max_subgraph_size: Maximum number of triples per subgraph (default: 1000)
max_subgraph_count: Maximum number of subgraphs to retrieve (default: 5)
max_entity_distance: Maximum graph distance for entity expansion (default: 3)
**kwargs: Additional service-specific parameters
Returns:
str: Complete generated response grounded in graph data
Example:
```python
async_flow = await api.async_flow()
flow = async_flow.id("default")
# Query knowledge graph
response = await flow.graph_rag(
query="What are the relationships between these entities?",
user="trustgraph",
collection="medical-kb",
max_subgraph_count=3
)
print(response)
```
"""
request_data = {
"query": query,
"user": user,
@ -179,7 +531,41 @@ class AsyncFlowInstance:
async def document_rag(self, query: str, user: str, collection: str,
doc_limit: int = 10, **kwargs: Any) -> str:
"""Document RAG (non-streaming, use async_socket for streaming)"""
"""
Execute document-based RAG query (non-streaming).
Performs Retrieval-Augmented Generation using document embeddings.
Retrieves relevant document chunks via semantic search, then generates
a response grounded in the retrieved documents. Returns complete response.
Note: This method does not support streaming. For streaming RAG responses,
use AsyncSocketFlowInstance.document_rag() instead.
Args:
query: User query text
user: User identifier
collection: Collection identifier containing documents
doc_limit: Maximum number of document chunks to retrieve (default: 10)
**kwargs: Additional service-specific parameters
Returns:
str: Complete generated response grounded in document data
Example:
```python
async_flow = await api.async_flow()
flow = async_flow.id("default")
# Query documents
response = await flow.document_rag(
query="What does the documentation say about authentication?",
user="trustgraph",
collection="docs",
doc_limit=5
)
print(response)
```
"""
request_data = {
"query": query,
"user": user,
@ -193,7 +579,39 @@ class AsyncFlowInstance:
return result.get("response", "")
async def graph_embeddings_query(self, text: str, user: str, collection: str, limit: int = 10, **kwargs: Any):
"""Query graph embeddings for semantic search"""
"""
Query graph embeddings for semantic entity search.
Performs semantic search over graph entity embeddings to find entities
most relevant to the input text. Returns entities ranked by similarity.
Args:
text: Query text for semantic search
user: User identifier
collection: Collection identifier containing graph embeddings
limit: Maximum number of results to return (default: 10)
**kwargs: Additional service-specific parameters
Returns:
dict: Response containing ranked entity matches with similarity scores
Example:
```python
async_flow = await api.async_flow()
flow = async_flow.id("default")
# Find related entities
results = await flow.graph_embeddings_query(
text="machine learning algorithms",
user="trustgraph",
collection="tech-kb",
limit=5
)
for entity in results.get("entities", []):
print(f"{entity['name']}: {entity['score']}")
```
"""
request_data = {
"text": text,
"user": user,
@ -205,14 +623,72 @@ class AsyncFlowInstance:
return await self.request("graph-embeddings", request_data)
async def embeddings(self, text: str, **kwargs: Any):
"""Generate text embeddings"""
"""
Generate embeddings for input text.
Converts text into a numerical vector representation using the flow's
configured embedding model. Useful for semantic search and similarity
comparisons.
Args:
text: Input text to embed
**kwargs: Additional service-specific parameters
Returns:
dict: Response containing embedding vector and metadata
Example:
```python
async_flow = await api.async_flow()
flow = async_flow.id("default")
# Generate embeddings
result = await flow.embeddings(text="Sample text to embed")
vector = result.get("embedding")
print(f"Embedding dimension: {len(vector)}")
```
"""
request_data = {"text": text}
request_data.update(kwargs)
return await self.request("embeddings", request_data)
async def triples_query(self, s=None, p=None, o=None, user=None, collection=None, limit=100, **kwargs: Any):
"""Triple pattern query"""
"""
Query RDF triples using pattern matching.
Searches for triples matching the specified subject, predicate, and/or
object patterns. Patterns use None as a wildcard to match any value.
Args:
s: Subject pattern (None for wildcard)
p: Predicate pattern (None for wildcard)
o: Object pattern (None for wildcard)
user: User identifier (None for all users)
collection: Collection identifier (None for all collections)
limit: Maximum number of triples to return (default: 100)
**kwargs: Additional service-specific parameters
Returns:
dict: Response containing matching triples
Example:
```python
async_flow = await api.async_flow()
flow = async_flow.id("default")
# Find all triples with a specific predicate
results = await flow.triples_query(
p="knows",
user="trustgraph",
collection="social",
limit=50
)
for triple in results.get("triples", []):
print(f"{triple['s']} knows {triple['o']}")
```
"""
request_data = {"limit": limit}
if s is not None:
request_data["s"] = str(s)
@ -230,7 +706,50 @@ class AsyncFlowInstance:
async def objects_query(self, query: str, user: str, collection: str, variables: Optional[Dict] = None,
operation_name: Optional[str] = None, **kwargs: Any):
"""GraphQL query"""
"""
Execute a GraphQL query on stored objects.
Queries structured data objects using GraphQL syntax. Supports complex
queries with variables and named operations.
Args:
query: GraphQL query string
user: User identifier
collection: Collection identifier containing objects
variables: Optional GraphQL query variables
operation_name: Optional operation name for multi-operation queries
**kwargs: Additional service-specific parameters
Returns:
dict: GraphQL response with data and/or errors
Example:
```python
async_flow = await api.async_flow()
flow = async_flow.id("default")
# Execute GraphQL query
query = '''
query GetUsers($status: String!) {
users(status: $status) {
id
name
email
}
}
'''
result = await flow.objects_query(
query=query,
user="trustgraph",
collection="users",
variables={"status": "active"}
)
for user in result.get("data", {}).get("users", []):
print(f"{user['name']}: {user['email']}")
```
"""
request_data = {
"query": query,
"user": user,

257
trustgraph-base/trustgraph/api/bulk_client.py
View file

@ -1,3 +1,10 @@
"""
TrustGraph Synchronous Bulk Operations Client
This module provides synchronous bulk import/export operations via WebSocket
for efficient transfer of large datasets including triples, embeddings,
entity contexts, and objects.
"""
import json
import asyncio
@ -9,9 +16,24 @@ from . exceptions import ProtocolException
class BulkClient:
"""Synchronous bulk operations client"""
"""
Synchronous bulk operations client for import/export.
Provides efficient bulk data transfer via WebSocket for large datasets.
Wraps async WebSocket operations with synchronous generators for ease of use.
Note: For true async support, use AsyncBulkClient instead.
"""
def __init__(self, url: str, timeout: int, token: Optional[str]) -> None:
"""
Initialize synchronous bulk client.
Args:
url: Base URL for TrustGraph API (HTTP/HTTPS will be converted to WS/WSS)
timeout: WebSocket timeout in seconds
token: Optional bearer token for authentication
"""
self.url: str = self._convert_to_ws_url(url)
self.timeout: int = timeout
self.token: Optional[str] = token
@ -41,7 +63,32 @@ class BulkClient:
return loop.run_until_complete(coro)
def import_triples(self, flow: str, triples: Iterator[Triple], **kwargs: Any) -> None:
"""Bulk import triples via WebSocket"""
"""
Bulk import RDF triples into a flow.
Efficiently uploads large numbers of triples via WebSocket streaming.
Args:
flow: Flow identifier
triples: Iterator yielding Triple objects
**kwargs: Additional parameters (reserved for future use)
Example:
```python
from trustgraph.api import Triple
bulk = api.bulk()
# Generate triples to import
def triple_generator():
yield Triple(s="subj1", p="pred", o="obj1")
yield Triple(s="subj2", p="pred", o="obj2")
# ... more triples
# Import triples
bulk.import_triples(flow="default", triples=triple_generator())
```
"""
self._run_async(self._import_triples_async(flow, triples))
async def _import_triples_async(self, flow: str, triples: Iterator[Triple]) -> None:
@ -60,7 +107,27 @@ class BulkClient:
await websocket.send(json.dumps(message))
def export_triples(self, flow: str, **kwargs: Any) -> Iterator[Triple]:
"""Bulk export triples via WebSocket"""
"""
Bulk export RDF triples from a flow.
Efficiently downloads all triples via WebSocket streaming.
Args:
flow: Flow identifier
**kwargs: Additional parameters (reserved for future use)
Returns:
Iterator[Triple]: Stream of Triple objects
Example:
```python
bulk = api.bulk()
# Export and process triples
for triple in bulk.export_triples(flow="default"):
print(f"{triple.s} -> {triple.p} -> {triple.o}")
```
"""
async_gen = self._export_triples_async(flow)
try:
@ -101,7 +168,32 @@ class BulkClient:
)
def import_graph_embeddings(self, flow: str, embeddings: Iterator[Dict[str, Any]], **kwargs: Any) -> None:
"""Bulk import graph embeddings via WebSocket"""
"""
Bulk import graph embeddings into a flow.
Efficiently uploads graph entity embeddings via WebSocket streaming.
Args:
flow: Flow identifier
embeddings: Iterator yielding embedding dictionaries
**kwargs: Additional parameters (reserved for future use)
Example:
```python
bulk = api.bulk()
# Generate embeddings to import
def embedding_generator():
yield {"entity": "entity1", "embedding": [0.1, 0.2, ...]}
yield {"entity": "entity2", "embedding": [0.3, 0.4, ...]}
# ... more embeddings
bulk.import_graph_embeddings(
flow="default",
embeddings=embedding_generator()
)
```
"""
self._run_async(self._import_graph_embeddings_async(flow, embeddings))
async def _import_graph_embeddings_async(self, flow: str, embeddings: Iterator[Dict[str, Any]]) -> None:
@ -115,7 +207,29 @@ class BulkClient:
await websocket.send(json.dumps(embedding))
def export_graph_embeddings(self, flow: str, **kwargs: Any) -> Iterator[Dict[str, Any]]:
"""Bulk export graph embeddings via WebSocket"""
"""
Bulk export graph embeddings from a flow.
Efficiently downloads all graph entity embeddings via WebSocket streaming.
Args:
flow: Flow identifier
**kwargs: Additional parameters (reserved for future use)
Returns:
Iterator[Dict[str, Any]]: Stream of embedding dictionaries
Example:
```python
bulk = api.bulk()
# Export and process embeddings
for embedding in bulk.export_graph_embeddings(flow="default"):
entity = embedding.get("entity")
vector = embedding.get("embedding")
print(f"{entity}: {len(vector)} dimensions")
```
"""
async_gen = self._export_graph_embeddings_async(flow)
try:
@ -151,7 +265,33 @@ class BulkClient:
yield json.loads(raw_message)
def import_document_embeddings(self, flow: str, embeddings: Iterator[Dict[str, Any]], **kwargs: Any) -> None:
"""Bulk import document embeddings via WebSocket"""
"""
Bulk import document embeddings into a flow.
Efficiently uploads document chunk embeddings via WebSocket streaming
for use in document RAG queries.
Args:
flow: Flow identifier
embeddings: Iterator yielding embedding dictionaries
**kwargs: Additional parameters (reserved for future use)
Example:
```python
bulk = api.bulk()
# Generate document embeddings to import
def doc_embedding_generator():
yield {"id": "doc1-chunk1", "embedding": [0.1, 0.2, ...]}
yield {"id": "doc1-chunk2", "embedding": [0.3, 0.4, ...]}
# ... more embeddings
bulk.import_document_embeddings(
flow="default",
embeddings=doc_embedding_generator()
)
```
"""
self._run_async(self._import_document_embeddings_async(flow, embeddings))
async def _import_document_embeddings_async(self, flow: str, embeddings: Iterator[Dict[str, Any]]) -> None:
@ -165,7 +305,29 @@ class BulkClient:
await websocket.send(json.dumps(embedding))
def export_document_embeddings(self, flow: str, **kwargs: Any) -> Iterator[Dict[str, Any]]:
"""Bulk export document embeddings via WebSocket"""
"""
Bulk export document embeddings from a flow.
Efficiently downloads all document chunk embeddings via WebSocket streaming.
Args:
flow: Flow identifier
**kwargs: Additional parameters (reserved for future use)
Returns:
Iterator[Dict[str, Any]]: Stream of embedding dictionaries
Example:
```python
bulk = api.bulk()
# Export and process document embeddings
for embedding in bulk.export_document_embeddings(flow="default"):
doc_id = embedding.get("id")
vector = embedding.get("embedding")
print(f"{doc_id}: {len(vector)} dimensions")
```
"""
async_gen = self._export_document_embeddings_async(flow)
try:
@ -201,7 +363,34 @@ class BulkClient:
yield json.loads(raw_message)
def import_entity_contexts(self, flow: str, contexts: Iterator[Dict[str, Any]], **kwargs: Any) -> None:
"""Bulk import entity contexts via WebSocket"""
"""
Bulk import entity contexts into a flow.
Efficiently uploads entity context information via WebSocket streaming.
Entity contexts provide additional textual context about graph entities
for improved RAG performance.
Args:
flow: Flow identifier
contexts: Iterator yielding context dictionaries
**kwargs: Additional parameters (reserved for future use)
Example:
```python
bulk = api.bulk()
# Generate entity contexts to import
def context_generator():
yield {"entity": "entity1", "context": "Description of entity1..."}
yield {"entity": "entity2", "context": "Description of entity2..."}
# ... more contexts
bulk.import_entity_contexts(
flow="default",
contexts=context_generator()
)
```
"""
self._run_async(self._import_entity_contexts_async(flow, contexts))
async def _import_entity_contexts_async(self, flow: str, contexts: Iterator[Dict[str, Any]]) -> None:
@ -215,7 +404,29 @@ class BulkClient:
await websocket.send(json.dumps(context))
def export_entity_contexts(self, flow: str, **kwargs: Any) -> Iterator[Dict[str, Any]]:
"""Bulk export entity contexts via WebSocket"""
"""
Bulk export entity contexts from a flow.
Efficiently downloads all entity context information via WebSocket streaming.
Args:
flow: Flow identifier
**kwargs: Additional parameters (reserved for future use)
Returns:
Iterator[Dict[str, Any]]: Stream of context dictionaries
Example:
```python
bulk = api.bulk()
# Export and process entity contexts
for context in bulk.export_entity_contexts(flow="default"):
entity = context.get("entity")
text = context.get("context")
print(f"{entity}: {text[:100]}...")
```
"""
async_gen = self._export_entity_contexts_async(flow)
try:
@ -251,7 +462,33 @@ class BulkClient:
yield json.loads(raw_message)
def import_objects(self, flow: str, objects: Iterator[Dict[str, Any]], **kwargs: Any) -> None:
"""Bulk import objects via WebSocket"""
"""
Bulk import structured objects into a flow.
Efficiently uploads structured data objects via WebSocket streaming
for use in GraphQL queries.
Args:
flow: Flow identifier
objects: Iterator yielding object dictionaries
**kwargs: Additional parameters (reserved for future use)
Example:
```python
bulk = api.bulk()
# Generate objects to import
def object_generator():
yield {"id": "obj1", "name": "Object 1", "value": 100}
yield {"id": "obj2", "name": "Object 2", "value": 200}
# ... more objects
bulk.import_objects(
flow="default",
objects=object_generator()
)
```
"""
self._run_async(self._import_objects_async(flow, objects))
async def _import_objects_async(self, flow: str, objects: Iterator[Dict[str, Any]]) -> None:

128
trustgraph-base/trustgraph/api/collection.py
View file

@ -1,3 +1,11 @@
"""
TrustGraph Collection Management
This module provides interfaces for managing data collections in TrustGraph.
Collections provide logical grouping and isolation for documents and knowledge
graph data.
"""
import datetime
import logging
@ -7,14 +15,71 @@ from . exceptions import *
logger = logging.getLogger(__name__)
class Collection:
"""
Collection management client.
Provides methods for managing data collections, including listing,
updating metadata, and deleting collections. Collections organize
documents and knowledge graph data into logical groupings for
isolation and access control.
"""
def __init__(self, api):
"""
Initialize Collection client.
Args:
api: Parent Api instance for making requests
"""
self.api = api
def request(self, request):
"""
Make a collection-scoped API request.
Args:
request: Request payload dictionary
Returns:
dict: Response object
"""
return self.api.request(f"collection-management", request)
def list_collections(self, user, tag_filter=None):
"""
List all collections for a user.
Retrieves metadata for all collections owned by the specified user,
with optional filtering by tags.
Args:
user: User identifier
tag_filter: Optional list of tags to filter collections (default: None)
Returns:
list[CollectionMetadata]: List of collection metadata objects
Raises:
ProtocolException: If response format is invalid
Example:
```python
collection = api.collection()
# List all collections
all_colls = collection.list_collections(user="trustgraph")
for coll in all_colls:
print(f"{coll.collection}: {coll.name}")
print(f" Description: {coll.description}")
print(f" Tags: {', '.join(coll.tags)}")
# List collections with specific tags
research_colls = collection.list_collections(
user="trustgraph",
tag_filter=["research", "published"]
)
```
"""
input = {
"operation": "list-collections",
@ -50,6 +115,46 @@ class Collection:
raise ProtocolException(f"Response not formatted correctly")
def update_collection(self, user, collection, name=None, description=None, tags=None):
"""
Update collection metadata.
Updates the name, description, and/or tags for an existing collection.
Only provided fields are updated; others remain unchanged.
Args:
user: User identifier
collection: Collection identifier
name: New collection name (optional)
description: New collection description (optional)
tags: New list of tags (optional)
Returns:
CollectionMetadata: Updated collection metadata, or None if not found
Raises:
ProtocolException: If response format is invalid
Example:
```python
collection_api = api.collection()
# Update collection metadata
updated = collection_api.update_collection(
user="trustgraph",
collection="default",
name="Default Collection",
description="Main data collection for general use",
tags=["default", "production"]
)
# Update only specific fields
updated = collection_api.update_collection(
user="trustgraph",
collection="research",
description="Updated description"
)
```
"""
input = {
"operation": "update-collection",
@ -82,6 +187,29 @@ class Collection:
raise ProtocolException(f"Response not formatted correctly")
def delete_collection(self, user, collection):
"""
Delete a collection.
Removes a collection and all its associated data from the system.
Args:
user: User identifier
collection: Collection identifier to delete
Returns:
dict: Empty response object
Example:
```python
collection_api = api.collection()
# Delete a collection
collection_api.delete_collection(
user="trustgraph",
collection="old-collection"
)
```
"""
input = {
"operation": "delete-collection",

179
trustgraph-base/trustgraph/api/config.py
View file

@ -1,3 +1,9 @@
"""
TrustGraph Configuration Management
This module provides interfaces for managing TrustGraph configuration settings,
including retrieving, updating, and deleting configuration values.
"""
import logging
@ -7,14 +13,67 @@ from . types import ConfigValue
logger = logging.getLogger(__name__)
class Config:
"""
Configuration management client.
Provides methods for managing TrustGraph configuration settings across
different types (llm, embedding, etc.), with support for get, put, delete,
and list operations.
"""
def __init__(self, api):
"""
Initialize Config client.
Args:
api: Parent Api instance for making requests
"""
self.api = api
def request(self, request):
"""
Make a configuration-scoped API request.
Args:
request: Request payload dictionary
Returns:
dict: Response object
"""
return self.api.request("config", request)
def get(self, keys):
"""
Get configuration values for specified keys.
Retrieves the configuration values for one or more configuration keys.
Args:
keys: List of ConfigKey objects specifying which values to retrieve
Returns:
list[ConfigValue]: List of configuration values
Raises:
ProtocolException: If response format is invalid
Example:
```python
from trustgraph.api import ConfigKey
config = api.config()
# Get specific configuration values
values = config.get([
ConfigKey(type="llm", key="model"),
ConfigKey(type="llm", key="temperature"),
ConfigKey(type="embedding", key="model")
])
for val in values:
print(f"{val.type}.{val.key} = {val.value}")
```
"""
# The input consists of system and prompt strings
input = {
@ -41,6 +100,28 @@ class Config:
raise ProtocolException("Response not formatted correctly")
def put(self, values):
"""
Set configuration values.
Updates or creates configuration values for the specified keys.
Args:
values: List of ConfigValue objects with type, key, and value
Example:
```python
from trustgraph.api import ConfigValue
config = api.config()
# Set configuration values
config.put([
ConfigValue(type="llm", key="model", value="gpt-4"),
ConfigValue(type="llm", key="temperature", value="0.7"),
ConfigValue(type="embedding", key="model", value="text-embedding-3-small")
])
```
"""
# The input consists of system and prompt strings
input = {
@ -54,6 +135,27 @@ class Config:
self.request(input)
def delete(self, keys):
"""
Delete configuration values.
Removes configuration values for the specified keys.
Args:
keys: List of ConfigKey objects specifying which values to delete
Example:
```python
from trustgraph.api import ConfigKey
config = api.config()
# Delete configuration values
config.delete([
ConfigKey(type="llm", key="old-setting"),
ConfigKey(type="embedding", key="deprecated")
])
```
"""
# The input consists of system and prompt strings
input = {
@ -67,6 +169,31 @@ class Config:
self.request(input)
def list(self, type):
"""
List all configuration keys for a given type.
Retrieves a list of all configuration key names within a specific
configuration type.
Args:
type: Configuration type (e.g., "llm", "embedding", "storage")
Returns:
list[str]: List of configuration key names
Example:
```python
config = api.config()
# List all LLM configuration keys
llm_keys = config.list(type="llm")
print(f"LLM configuration keys: {llm_keys}")
# List all embedding configuration keys
embedding_keys = config.list(type="embedding")
print(f"Embedding configuration keys: {embedding_keys}")
```
"""
# The input consists of system and prompt strings
input = {
@ -77,6 +204,36 @@ class Config:
return self.request(input)["directory"]
def get_values(self, type):
"""
Get all configuration values for a given type.
Retrieves all configuration key-value pairs within a specific
configuration type.
Args:
type: Configuration type (e.g., "llm", "embedding", "storage")
Returns:
list[ConfigValue]: List of all configuration values for the type
Raises:
ProtocolException: If response format is invalid
Example:
```python
config = api.config()
# Get all LLM configuration
llm_config = config.get_values(type="llm")
for val in llm_config:
print(f"{val.key} = {val.value}")
# Get all embedding configuration
embedding_config = config.get_values(type="embedding")
for val in embedding_config:
print(f"{val.key} = {val.value}")
```
"""
# The input consists of system and prompt strings
input = {
@ -99,6 +256,28 @@ class Config:
raise ProtocolException(f"Response not formatted correctly")
def all(self):
"""
Get complete configuration and version.
Retrieves the entire configuration object along with its version number.
Returns:
tuple: (config_dict, version_string) - Complete configuration and version
Raises:
ProtocolException: If response format is invalid
Example:
```python
config = api.config()
# Get complete configuration
config_data, version = config.all()
print(f"Configuration version: {version}")
print(f"Configuration: {config_data}")
```
"""
# The input consists of system and prompt strings
input = {

580
trustgraph-base/trustgraph/api/flow.py
View file

@ -1,3 +1,10 @@
"""
TrustGraph Flow Management
This module provides interfaces for managing and executing TrustGraph flows.
Flows are the primary execution units that provide access to various services
including LLM operations, RAG queries, knowledge graph management, and more.
"""
import json
import base64
@ -11,11 +18,38 @@ def to_value(x):
return Literal(x["v"])
class Flow:
"""
Flow management client for blueprint and flow instance operations.
This class provides methods for managing flow blueprints (templates) and
flow instances (running flows). Blueprints define the structure and
parameters of flows, while instances represent active flows that can
execute services.
"""
def __init__(self, api):
"""
Initialize Flow client.
Args:
api: Parent Api instance for making requests
"""
self.api = api
def request(self, path=None, request=None):
"""
Make a flow-scoped API request.
Args:
path: Optional path suffix for flow endpoints
request: Request payload dictionary
Returns:
dict: Response object
Raises:
RuntimeError: If request parameter is not specified
"""
if request is None:
raise RuntimeError("request must be specified")
@ -26,9 +60,39 @@ class Flow:
return self.api.request(f"flow", request)
def id(self, id="default"):
"""
Get a FlowInstance for executing operations on a specific flow.
Args:
id: Flow identifier (default: "default")
Returns:
FlowInstance: Flow instance for service operations
Example:
```python
flow = api.flow().id("my-flow")
response = flow.text_completion(
system="You are helpful",
prompt="Hello"
)
```
"""
return FlowInstance(api=self, id=id)
def list_blueprints(self):
"""
List all available flow blueprints.
Returns:
list[str]: List of blueprint names
Example:
```python
blueprints = api.flow().list_blueprints()
print(blueprints) # ['default', 'custom-flow', ...]
```
"""
# The input consists of system and prompt strings
input = {
@ -38,6 +102,21 @@ class Flow:
return self.request(request = input)["blueprint-names"]
def get_blueprint(self, blueprint_name):
"""
Get a flow blueprint definition by name.
Args:
blueprint_name: Name of the blueprint to retrieve
Returns:
dict: Blueprint definition as a dictionary
Example:
```python
blueprint = api.flow().get_blueprint("default")
print(blueprint) # Blueprint configuration
```
"""
# The input consists of system and prompt strings
input = {
@ -48,6 +127,22 @@ class Flow:
return json.loads(self.request(request = input)["blueprint-definition"])
def put_blueprint(self, blueprint_name, definition):
"""
Create or update a flow blueprint.
Args:
blueprint_name: Name for the blueprint
definition: Blueprint definition dictionary
Example:
```python
definition = {
"services": ["text-completion", "graph-rag"],
"parameters": {"model": "gpt-4"}
}
api.flow().put_blueprint("my-blueprint", definition)
```
"""
# The input consists of system and prompt strings
input = {
@ -59,6 +154,17 @@ class Flow:
self.request(request = input)
def delete_blueprint(self, blueprint_name):
"""
Delete a flow blueprint.
Args:
blueprint_name: Name of the blueprint to delete
Example:
```python
api.flow().delete_blueprint("old-blueprint")
```
"""
# The input consists of system and prompt strings
input = {
@ -69,6 +175,18 @@ class Flow:
self.request(request = input)
def list(self):
"""
List all active flow instances.
Returns:
list[str]: List of flow instance IDs
Example:
```python
flows = api.flow().list()
print(flows) # ['default', 'flow-1', 'flow-2', ...]
```
"""
# The input consists of system and prompt strings
input = {
@ -78,6 +196,21 @@ class Flow:
return self.request(request = input)["flow-ids"]
def get(self, id):
"""
Get the definition of a running flow instance.
Args:
id: Flow instance ID
Returns:
dict: Flow instance definition
Example:
```python
flow_def = api.flow().get("default")
print(flow_def)
```
"""
# The input consists of system and prompt strings
input = {
@ -88,6 +221,25 @@ class Flow:
return json.loads(self.request(request = input)["flow"])
def start(self, blueprint_name, id, description, parameters=None):
"""
Start a new flow instance from a blueprint.
Args:
blueprint_name: Name of the blueprint to instantiate
id: Unique identifier for the flow instance
description: Human-readable description
parameters: Optional parameters dictionary
Example:
```python
api.flow().start(
blueprint_name="default",
id="my-flow",
description="My custom flow",
parameters={"model": "gpt-4"}
)
```
"""
# The input consists of system and prompt strings
input = {
@ -103,6 +255,17 @@ class Flow:
self.request(request = input)
def stop(self, id):
"""
Stop a running flow instance.
Args:
id: Flow instance ID to stop
Example:
```python
api.flow().stop("my-flow")
```
"""
# The input consists of system and prompt strings
input = {
@ -111,18 +274,70 @@ class Flow:
}
self.request(request = input)
class FlowInstance:
"""
Flow instance client for executing services on a specific flow.
This class provides access to all TrustGraph services including:
- Text completion and embeddings
- Agent operations with state management
- Graph and document RAG queries
- Knowledge graph operations (triples, objects)
- Document loading and processing
- Natural language to GraphQL query conversion
- Structured data analysis and schema detection
- MCP tool execution
- Prompt templating
Services are accessed through a running flow instance identified by ID.
"""
def __init__(self, api, id):
"""
Initialize FlowInstance.
Args:
api: Parent Flow client
id: Flow instance identifier
"""
self.api = api
self.id = id
def request(self, path, request):
"""
Make a service request on this flow instance.
Args:
path: Service path (e.g., "service/text-completion")
request: Request payload dictionary
Returns:
dict: Service response
"""
return self.api.request(path = f"{self.id}/{path}", request = request)
def text_completion(self, system, prompt):
"""
Execute text completion using the flow's LLM.
Args:
system: System prompt defining the assistant's behavior
prompt: User prompt/question
Returns:
str: Generated response text
Example:
```python
flow = api.flow().id("default")
response = flow.text_completion(
system="You are a helpful assistant",
prompt="What is quantum computing?"
)
print(response)
```
"""
# The input consists of system and prompt strings
input = {
@ -136,6 +351,44 @@ class FlowInstance:
)["response"]
def agent(self, question, user="trustgraph", state=None, group=None, history=None):
"""
Execute an agent operation with reasoning and tool use capabilities.
Agents can perform multi-step reasoning, use tools, and maintain conversation
state across interactions. This is a synchronous non-streaming version.
Args:
question: User question or instruction
user: User identifier (default: "trustgraph")
state: Optional state dictionary for stateful conversations
group: Optional group identifier for multi-user contexts
history: Optional conversation history as list of message dicts
Returns:
str: Agent's final answer
Example:
```python
flow = api.flow().id("default")
# Simple question
answer = flow.agent(
question="What is the capital of France?",
user="trustgraph"
)
# With conversation history
history = [
{"role": "user", "content": "Hello"},
{"role": "assistant", "content": "Hi! How can I help?"}
]
answer = flow.agent(
question="Tell me about Paris",
user="trustgraph",
history=history
)
```
"""
# The input consists of a question and optional context
input = {
@ -164,6 +417,37 @@ class FlowInstance:
entity_limit=50, triple_limit=30, max_subgraph_size=150,
max_path_length=2,
):
"""
Execute graph-based Retrieval-Augmented Generation (RAG) query.
Graph RAG uses knowledge graph structure to find relevant context by
traversing entity relationships, then generates a response using an LLM.
Args:
query: Natural language query
user: User/keyspace identifier (default: "trustgraph")
collection: Collection identifier (default: "default")
entity_limit: Maximum entities to retrieve (default: 50)
triple_limit: Maximum triples per entity (default: 30)
max_subgraph_size: Maximum total triples in subgraph (default: 150)
max_path_length: Maximum traversal depth (default: 2)
Returns:
str: Generated response incorporating graph context
Example:
```python
flow = api.flow().id("default")
response = flow.graph_rag(
query="Tell me about Marie Curie's discoveries",
user="trustgraph",
collection="scientists",
entity_limit=20,
max_path_length=3
)
print(response)
```
"""
# The input consists of a question
input = {
@ -185,6 +469,33 @@ class FlowInstance:
self, query, user="trustgraph", collection="default",
doc_limit=10,
):
"""
Execute document-based Retrieval-Augmented Generation (RAG) query.
Document RAG uses vector embeddings to find relevant document chunks,
then generates a response using an LLM with those chunks as context.
Args:
query: Natural language query
user: User/keyspace identifier (default: "trustgraph")
collection: Collection identifier (default: "default")
doc_limit: Maximum document chunks to retrieve (default: 10)
Returns:
str: Generated response incorporating document context
Example:
```python
flow = api.flow().id("default")
response = flow.document_rag(
query="Summarize the key findings",
user="trustgraph",
collection="research-papers",
doc_limit=5
)
print(response)
```
"""
# The input consists of a question
input = {
@ -200,6 +511,25 @@ class FlowInstance:
)["response"]
def embeddings(self, text):
"""
Generate vector embeddings for text.
Converts text into dense vector representations suitable for semantic
search and similarity comparison.
Args:
text: Input text to embed
Returns:
list[float]: Vector embedding
Example:
```python
flow = api.flow().id("default")
vectors = flow.embeddings("quantum computing")
print(f"Embedding dimension: {len(vectors)}")
```
"""
# The input consists of a text block
input = {
@ -212,6 +542,32 @@ class FlowInstance:
)["vectors"]
def graph_embeddings_query(self, text, user, collection, limit=10):
"""
Query knowledge graph entities using semantic similarity.
Finds entities in the knowledge graph whose descriptions are semantically
similar to the input text, using vector embeddings.
Args:
text: Query text for semantic search
user: User/keyspace identifier
collection: Collection identifier
limit: Maximum number of results (default: 10)
Returns:
dict: Query results with similar entities
Example:
```python
flow = api.flow().id("default")
results = flow.graph_embeddings_query(
text="physicist who discovered radioactivity",
user="trustgraph",
collection="scientists",
limit=5
)
```
"""
# Query graph embeddings for semantic search
input = {
@ -227,6 +583,39 @@ class FlowInstance:
)
def prompt(self, id, variables):
"""
Execute a prompt template with variable substitution.
Prompt templates allow reusable prompt patterns with dynamic variable
substitution, useful for consistent prompt engineering.
Args:
id: Prompt template identifier
variables: Dictionary of variable name to value mappings
Returns:
str or dict: Rendered prompt result (text or structured object)
Raises:
ProtocolException: If response format is invalid
Example:
```python
flow = api.flow().id("default")
# Text template
result = flow.prompt(
id="summarize-template",
variables={"topic": "quantum computing", "length": "brief"}
)
# Structured template
result = flow.prompt(
id="extract-entities",
variables={"text": "Marie Curie won Nobel Prizes"}
)
```
"""
input = {
"id": id,
@ -252,6 +641,33 @@ class FlowInstance:
raise ProtocolException("Response not formatted correctly")
def mcp_tool(self, name, parameters={}):
"""
Execute a Model Context Protocol (MCP) tool.
MCP tools provide extensible functionality for agents and workflows,
allowing integration with external systems and services.
Args:
name: Tool name/identifier
parameters: Tool parameters dictionary (default: {})
Returns:
str or dict: Tool execution result
Raises:
ProtocolException: If response format is invalid
Example:
```python
flow = api.flow().id("default")
# Execute a tool
result = flow.mcp_tool(
name="search-web",
parameters={"query": "latest AI news", "limit": 5}
)
```
"""
# The input consists of name and parameters
input = {
@ -281,6 +697,46 @@ class FlowInstance:
self, s=None, p=None, o=None,
user=None, collection=None, limit=10000
):
"""
Query knowledge graph triples using pattern matching.
Searches for RDF triples matching the given subject, predicate, and/or
object patterns. Unspecified parameters act as wildcards.
Args:
s: Subject URI (optional, use None for wildcard)
p: Predicate URI (optional, use None for wildcard)
o: Object URI or Literal (optional, use None for wildcard)
user: User/keyspace identifier (optional)
collection: Collection identifier (optional)
limit: Maximum results to return (default: 10000)
Returns:
list[Triple]: List of matching Triple objects
Raises:
RuntimeError: If s or p is not a Uri, or o is not Uri/Literal
Example:
```python
from trustgraph.knowledge import Uri, Literal
flow = api.flow().id("default")
# Find all triples about a specific subject
triples = flow.triples_query(
s=Uri("http://example.org/person/marie-curie"),
user="trustgraph",
collection="scientists"
)
# Find all instances of a specific relationship
triples = flow.triples_query(
p=Uri("http://example.org/ontology/discovered"),
limit=100
)
```
"""
input = {
"limit": limit
@ -325,6 +781,39 @@ class FlowInstance:
self, document, id=None, metadata=None, user=None,
collection=None,
):
"""
Load a binary document for processing.
Uploads a document (PDF, DOCX, images, etc.) for extraction and
processing through the flow's document pipeline.
Args:
document: Document content as bytes
id: Optional document identifier (auto-generated if None)
metadata: Optional metadata (list of Triples or object with emit method)
user: User/keyspace identifier (optional)
collection: Collection identifier (optional)
Returns:
dict: Processing response
Raises:
RuntimeError: If metadata is provided without id
Example:
```python
flow = api.flow().id("default")
# Load a PDF document
with open("research.pdf", "rb") as f:
result = flow.load_document(
document=f.read(),
id="research-001",
user="trustgraph",
collection="papers"
)
```
"""
if id is None:
@ -372,6 +861,41 @@ class FlowInstance:
self, text, id=None, metadata=None, charset="utf-8",
user=None, collection=None,
):
"""
Load text content for processing.
Uploads text content for extraction and processing through the flow's
text pipeline.
Args:
text: Text content as bytes
id: Optional document identifier (auto-generated if None)
metadata: Optional metadata (list of Triples or object with emit method)
charset: Character encoding (default: "utf-8")
user: User/keyspace identifier (optional)
collection: Collection identifier (optional)
Returns:
dict: Processing response
Raises:
RuntimeError: If metadata is provided without id
Example:
```python
flow = api.flow().id("default")
# Load text content
text_content = b"This is the document content..."
result = flow.load_text(
text=text_content,
id="text-001",
charset="utf-8",
user="trustgraph",
collection="documents"
)
```
"""
if id is None:
@ -417,6 +941,60 @@ class FlowInstance:
self, query, user="trustgraph", collection="default",
variables=None, operation_name=None
):
"""
Execute a GraphQL query against structured objects in the knowledge graph.
Queries structured data using GraphQL syntax, allowing complex queries
with filtering, aggregation, and relationship traversal.
Args:
query: GraphQL query string
user: User/keyspace identifier (default: "trustgraph")
collection: Collection identifier (default: "default")
variables: Optional query variables dictionary
operation_name: Optional operation name for multi-operation documents
Returns:
dict: GraphQL response with 'data', 'errors', and/or 'extensions' fields
Raises:
ProtocolException: If system-level error occurs
Example:
```python
flow = api.flow().id("default")
# Simple query
query = '''
{
scientists(limit: 10) {
name
field
discoveries
}
}
'''
result = flow.objects_query(
query=query,
user="trustgraph",
collection="scientists"
)
# Query with variables
query = '''
query GetScientist($name: String!) {
scientists(name: $name) {
name
nobelPrizes
}
}
'''
result = flow.objects_query(
query=query,
variables={"name": "Marie Curie"}
)
```
"""
# The input consists of a GraphQL query and optional variables
input = {

122
trustgraph-base/trustgraph/api/knowledge.py
View file

@ -1,3 +1,10 @@
"""
TrustGraph Knowledge Graph Core Management
This module provides interfaces for managing knowledge graph cores in TrustGraph.
KG cores are pre-built knowledge graph datasets that can be loaded and unloaded
into flows for use in queries and RAG operations.
"""
import json
import base64
@ -10,15 +17,56 @@ def to_value(x):
return Literal(x["v"])
class Knowledge:
"""
Knowledge graph core management client.
Provides methods for managing knowledge graph cores, including listing
available cores, loading them into flows, and unloading them. KG cores
are pre-built knowledge graph datasets that enhance RAG capabilities.
"""
def __init__(self, api):
"""
Initialize Knowledge client.
Args:
api: Parent Api instance for making requests
"""
self.api = api
def request(self, request):
"""
Make a knowledge-scoped API request.
Args:
request: Request payload dictionary
Returns:
dict: Response object
"""
return self.api.request(f"knowledge", request)
def list_kg_cores(self, user="trustgraph"):
"""
List all available knowledge graph cores.
Retrieves the IDs of all KG cores available for the specified user.
Args:
user: User identifier (default: "trustgraph")
Returns:
list[str]: List of KG core identifiers
Example:
```python
knowledge = api.knowledge()
# List available KG cores
cores = knowledge.list_kg_cores(user="trustgraph")
print(f"Available KG cores: {cores}")
```
"""
# The input consists of system and prompt strings
input = {
@ -29,6 +77,24 @@ class Knowledge:
return self.request(request = input)["ids"]
def delete_kg_core(self, id, user="trustgraph"):
"""
Delete a knowledge graph core.
Removes a KG core from storage. This does not affect currently loaded
cores in flows.
Args:
id: KG core identifier to delete
user: User identifier (default: "trustgraph")
Example:
```python
knowledge = api.knowledge()
# Delete a KG core
knowledge.delete_kg_core(id="medical-kb-v1", user="trustgraph")
```
"""
# The input consists of system and prompt strings
input = {
@ -41,6 +107,39 @@ class Knowledge:
def load_kg_core(self, id, user="trustgraph", flow="default",
collection="default"):
"""
Load a knowledge graph core into a flow.
Makes a KG core available for use in queries and RAG operations within
the specified flow and collection.
Args:
id: KG core identifier to load
user: User identifier (default: "trustgraph")
flow: Flow instance to load into (default: "default")
collection: Collection to associate with (default: "default")
Example:
```python
knowledge = api.knowledge()
# Load a medical knowledge base into the default flow
knowledge.load_kg_core(
id="medical-kb-v1",
user="trustgraph",
flow="default",
collection="medical"
)
# Now the flow can use this KG core for RAG queries
flow = api.flow().id("default")
response = flow.graph_rag(
query="What are the symptoms of diabetes?",
user="trustgraph",
collection="medical"
)
```
"""
# The input consists of system and prompt strings
input = {
@ -54,6 +153,29 @@ class Knowledge:
self.request(request = input)
def unload_kg_core(self, id, user="trustgraph", flow="default"):
"""
Unload a knowledge graph core from a flow.
Removes a KG core from active use in the specified flow, freeing
resources while keeping the core available in storage.
Args:
id: KG core identifier to unload
user: User identifier (default: "trustgraph")
flow: Flow instance to unload from (default: "default")
Example:
```python
knowledge = api.knowledge()
# Unload a KG core when no longer needed
knowledge.unload_kg_core(
id="medical-kb-v1",
user="trustgraph",
flow="default"
)
```
"""
# The input consists of system and prompt strings
input = {

252
trustgraph-base/trustgraph/api/library.py
View file

@ -1,3 +1,9 @@
"""
TrustGraph Document Library Management
This module provides interfaces for managing documents in the TrustGraph library,
including document storage, metadata management, and processing workflow coordination.
"""
import datetime
import time
@ -15,17 +21,79 @@ def to_value(x):
return Literal(x["v"])
class Library:
"""
Document library management client.
Provides methods for managing documents in the TrustGraph library, including
adding, retrieving, updating, and removing documents, as well as managing
document processing workflows.
"""
def __init__(self, api):
"""
Initialize Library client.
Args:
api: Parent Api instance for making requests
"""
self.api = api
def request(self, request):
"""
Make a library-scoped API request.
Args:
request: Request payload dictionary
Returns:
dict: Response object
"""
return self.api.request(f"librarian", request)
def add_document(
self, document, id, metadata, user, title, comments,
kind="text/plain", tags=[],
kind="text/plain", tags=[],
):
"""
Add a document to the library.
Stores a document with associated metadata in the library for
retrieval and processing.
Args:
document: Document content as bytes
id: Document identifier (auto-generated if None)
metadata: Document metadata as list of Triple objects or object with emit method
user: User/owner identifier
title: Document title
comments: Document description or comments
kind: MIME type of the document (default: "text/plain")
tags: List of tags for categorization (default: [])
Returns:
dict: Response from the add operation
Raises:
RuntimeError: If metadata is provided without an id
Example:
```python
library = api.library()
# Add a PDF document
with open("research.pdf", "rb") as f:
library.add_document(
document=f.read(),
id="research-001",
metadata=[],
user="trustgraph",
title="Research Paper",
comments="Key findings in quantum computing",
kind="application/pdf",
tags=["research", "physics"]
)
```
"""
if id is None:
@ -85,6 +153,31 @@ class Library:
return self.request(input)
def get_documents(self, user):
"""
List all documents for a user.
Retrieves metadata for all documents owned by the specified user.
Args:
user: User identifier
Returns:
list[DocumentMetadata]: List of document metadata objects
Raises:
ProtocolException: If response format is invalid
Example:
```python
library = api.library()
docs = library.get_documents(user="trustgraph")
for doc in docs:
print(f"{doc.id}: {doc.title} ({doc.kind})")
print(f" Uploaded: {doc.time}")
print(f" Tags: {', '.join(doc.tags)}")
```
"""
input = {
"operation": "list-documents",
@ -119,6 +212,29 @@ class Library:
raise ProtocolException(f"Response not formatted correctly")
def get_document(self, user, id):
"""
Get metadata for a specific document.
Retrieves the metadata for a single document by ID.
Args:
user: User identifier
id: Document identifier
Returns:
DocumentMetadata: Document metadata object
Raises:
ProtocolException: If response format is invalid
Example:
```python
library = api.library()
doc = library.get_document(user="trustgraph", id="doc-123")
print(f"Title: {doc.title}")
print(f"Comments: {doc.comments}")
```
"""
input = {
"operation": "get-document",
@ -152,6 +268,42 @@ class Library:
raise ProtocolException(f"Response not formatted correctly")
def update_document(self, user, id, metadata):
"""
Update document metadata.
Updates the metadata for an existing document in the library.
Args:
user: User identifier
id: Document identifier
metadata: Updated DocumentMetadata object
Returns:
DocumentMetadata: Updated document metadata
Raises:
ProtocolException: If response format is invalid
Example:
```python
library = api.library()
# Get existing document
doc = library.get_document(user="trustgraph", id="doc-123")
# Update metadata
doc.title = "Updated Title"
doc.comments = "Updated description"
doc.tags.append("reviewed")
# Save changes
updated_doc = library.update_document(
user="trustgraph",
id="doc-123",
metadata=doc
)
```
"""
input = {
"operation": "update-document",
@ -199,6 +351,24 @@ class Library:
raise ProtocolException(f"Response not formatted correctly")
def remove_document(self, user, id):
"""
Remove a document from the library.
Deletes a document and its metadata from the library.
Args:
user: User identifier
id: Document identifier to remove
Returns:
dict: Empty response object
Example:
```python
library = api.library()
library.remove_document(user="trustgraph", id="doc-123")
```
"""
input = {
"operation": "remove-document",
@ -214,6 +384,38 @@ class Library:
self, id, document_id, flow="default",
user="trustgraph", collection="default", tags=[],
):
"""
Start a document processing workflow.
Initiates processing of a document through a specified flow, tracking
the processing job with metadata.
Args:
id: Unique processing job identifier
document_id: ID of the document to process
flow: Flow instance to use for processing (default: "default")
user: User identifier (default: "trustgraph")
collection: Target collection for processed data (default: "default")
tags: List of tags for the processing job (default: [])
Returns:
dict: Empty response object
Example:
```python
library = api.library()
# Start processing a document
library.start_processing(
id="proc-001",
document_id="doc-123",
flow="default",
user="trustgraph",
collection="research",
tags=["automated", "extract"]
)
```
"""
input = {
"operation": "add-processing",
@ -233,8 +435,26 @@ class Library:
return {}
def stop_processing(
self, id, user="trustgraph",
self, id, user="trustgraph",
):
"""
Stop a running document processing job.
Terminates an active document processing workflow and removes its metadata.
Args:
id: Processing job identifier to stop
user: User identifier (default: "trustgraph")
Returns:
dict: Empty response object
Example:
```python
library = api.library()
library.stop_processing(id="proc-001", user="trustgraph")
```
"""
input = {
"operation": "remove-processing",
@ -247,6 +467,34 @@ class Library:
return {}
def get_processings(self, user="trustgraph"):
"""
List all active document processing jobs.
Retrieves metadata for all currently running document processing workflows
for the specified user.
Args:
user: User identifier (default: "trustgraph")
Returns:
list[ProcessingMetadata]: List of processing job metadata objects
Raises:
ProtocolException: If response format is invalid
Example:
```python
library = api.library()
jobs = library.get_processings(user="trustgraph")
for job in jobs:
print(f"Job {job.id}:")
print(f" Document: {job.document_id}")
print(f" Flow: {job.flow}")
print(f" Collection: {job.collection}")
print(f" Started: {job.time}")
```
"""
input = {
"operation": "list-processing",

381
trustgraph-base/trustgraph/api/socket_client.py
View file

@ -1,3 +1,9 @@
"""
TrustGraph Synchronous WebSocket Client
This module provides synchronous WebSocket-based access to TrustGraph services with
streaming support for real-time responses from agents, RAG queries, and text completions.
"""
import json
import asyncio
@ -10,9 +16,26 @@ from . exceptions import ProtocolException, raise_from_error_dict
class SocketClient:
"""Synchronous WebSocket client (wraps async websockets library)"""
"""
Synchronous WebSocket client for streaming operations.
Provides a synchronous interface to WebSocket-based TrustGraph services,
wrapping async websockets library with synchronous generators for ease of use.
Supports streaming responses from agents, RAG queries, and text completions.
Note: This is a synchronous wrapper around async WebSocket operations. For
true async support, use AsyncSocketClient instead.
"""
def __init__(self, url: str, timeout: int, token: Optional[str]) -> None:
"""
Initialize synchronous WebSocket client.
Args:
url: Base URL for TrustGraph API (HTTP/HTTPS will be converted to WS/WSS)
timeout: WebSocket timeout in seconds
token: Optional bearer token for authentication
"""
self.url: str = self._convert_to_ws_url(url)
self.timeout: int = timeout
self.token: Optional[str] = token
@ -22,7 +45,15 @@ class SocketClient:
self._loop: Optional[asyncio.AbstractEventLoop] = None
def _convert_to_ws_url(self, url: str) -> str:
"""Convert HTTP URL to WebSocket URL"""
"""
Convert HTTP URL to WebSocket URL.
Args:
url: HTTP/HTTPS or WS/WSS URL
Returns:
str: WebSocket URL (ws:// or wss://)
"""
if url.startswith("http://"):
return url.replace("http://", "ws://", 1)
elif url.startswith("https://"):
@ -34,7 +65,25 @@ class SocketClient:
return f"ws://{url}"
def flow(self, flow_id: str) -> "SocketFlowInstance":
"""Get flow instance for WebSocket operations"""
"""
Get a flow instance for WebSocket streaming operations.
Args:
flow_id: Flow identifier
Returns:
SocketFlowInstance: Flow instance with streaming methods
Example:
```python
socket = api.socket()
flow = socket.flow("default")
# Stream agent responses
for chunk in flow.agent(question="Hello", user="trustgraph", streaming=True):
print(chunk.content, end='', flush=True)
```
"""
return SocketFlowInstance(self, flow_id)
def _send_request_sync(
@ -242,15 +291,32 @@ class SocketClient:
)
def close(self) -> None:
"""Close WebSocket connection"""
"""
Close WebSocket connections.
Note: Cleanup is handled automatically by context managers in async code.
"""
# Cleanup handled by context manager in async code
pass
class SocketFlowInstance:
"""Synchronous WebSocket flow instance with same interface as REST FlowInstance"""
"""
Synchronous WebSocket flow instance for streaming operations.
Provides the same interface as REST FlowInstance but with WebSocket-based
streaming support for real-time responses. All methods support an optional
`streaming` parameter to enable incremental result delivery.
"""
def __init__(self, client: SocketClient, flow_id: str) -> None:
"""
Initialize socket flow instance.
Args:
client: Parent SocketClient
flow_id: Flow identifier
"""
self.client: SocketClient = client
self.flow_id: str = flow_id
@ -264,7 +330,44 @@ class SocketFlowInstance:
streaming: bool = False,
**kwargs: Any
) -> Union[Dict[str, Any], Iterator[StreamingChunk]]:
"""Agent with optional streaming"""
"""
Execute an agent operation with streaming support.
Agents can perform multi-step reasoning with tool use. This method always
returns streaming chunks (thoughts, observations, answers) even when
streaming=False, to show the agent's reasoning process.
Args:
question: User question or instruction
user: User identifier
state: Optional state dictionary for stateful conversations
group: Optional group identifier for multi-user contexts
history: Optional conversation history as list of message dicts
streaming: Enable streaming mode (default: False)
**kwargs: Additional parameters passed to the agent service
Returns:
Iterator[StreamingChunk]: Stream of agent thoughts, observations, and answers
Example:
```python
socket = api.socket()
flow = socket.flow("default")
# Stream agent reasoning
for chunk in flow.agent(
question="What is quantum computing?",
user="trustgraph",
streaming=True
):
if isinstance(chunk, AgentThought):
print(f"[Thinking] {chunk.content}")
elif isinstance(chunk, AgentObservation):
print(f"[Observation] {chunk.content}")
elif isinstance(chunk, AgentAnswer):
print(f"[Answer] {chunk.content}")
```
"""
request = {
"question": question,
"user": user,
@ -283,7 +386,40 @@ class SocketFlowInstance:
return self.client._send_request_sync("agent", self.flow_id, request, streaming=True)
def text_completion(self, system: str, prompt: str, streaming: bool = False, **kwargs) -> Union[str, Iterator[str]]:
"""Text completion with optional streaming"""
"""
Execute text completion with optional streaming.
Args:
system: System prompt defining the assistant's behavior
prompt: User prompt/question
streaming: Enable streaming mode (default: False)
**kwargs: Additional parameters passed to the service
Returns:
Union[str, Iterator[str]]: Complete response or stream of text chunks
Example:
```python
socket = api.socket()
flow = socket.flow("default")
# Non-streaming
response = flow.text_completion(
system="You are helpful",
prompt="Explain quantum computing",
streaming=False
)
print(response)
# Streaming
for chunk in flow.text_completion(
system="You are helpful",
prompt="Explain quantum computing",
streaming=True
):
print(chunk, end='', flush=True)
```
"""
request = {
"system": system,
"prompt": prompt,
@ -316,7 +452,40 @@ class SocketFlowInstance:
streaming: bool = False,
**kwargs: Any
) -> Union[str, Iterator[str]]:
"""Graph RAG with optional streaming"""
"""
Execute graph-based RAG query with optional streaming.
Uses knowledge graph structure to find relevant context, then generates
a response using an LLM. Streaming mode delivers results incrementally.
Args:
query: Natural language query
user: User/keyspace identifier
collection: Collection identifier
max_subgraph_size: Maximum total triples in subgraph (default: 1000)
max_subgraph_count: Maximum number of subgraphs (default: 5)
max_entity_distance: Maximum traversal depth (default: 3)
streaming: Enable streaming mode (default: False)
**kwargs: Additional parameters passed to the service
Returns:
Union[str, Iterator[str]]: Complete response or stream of text chunks
Example:
```python
socket = api.socket()
flow = socket.flow("default")
# Streaming graph RAG
for chunk in flow.graph_rag(
query="Tell me about Marie Curie",
user="trustgraph",
collection="scientists",
streaming=True
):
print(chunk, end='', flush=True)
```
"""
request = {
"query": query,
"user": user,
@ -344,7 +513,39 @@ class SocketFlowInstance:
streaming: bool = False,
**kwargs: Any
) -> Union[str, Iterator[str]]:
"""Document RAG with optional streaming"""
"""
Execute document-based RAG query with optional streaming.
Uses vector embeddings to find relevant document chunks, then generates
a response using an LLM. Streaming mode delivers results incrementally.
Args:
query: Natural language query
user: User/keyspace identifier
collection: Collection identifier
doc_limit: Maximum document chunks to retrieve (default: 10)
streaming: Enable streaming mode (default: False)
**kwargs: Additional parameters passed to the service
Returns:
Union[str, Iterator[str]]: Complete response or stream of text chunks
Example:
```python
socket = api.socket()
flow = socket.flow("default")
# Streaming document RAG
for chunk in flow.document_rag(
query="Summarize the key findings",
user="trustgraph",
collection="research-papers",
doc_limit=5,
streaming=True
):
print(chunk, end='', flush=True)
```
"""
request = {
"query": query,
"user": user,
@ -374,7 +575,32 @@ class SocketFlowInstance:
streaming: bool = False,
**kwargs: Any
) -> Union[str, Iterator[str]]:
"""Execute prompt with optional streaming"""
"""
Execute a prompt template with optional streaming.
Args:
id: Prompt template identifier
variables: Dictionary of variable name to value mappings
streaming: Enable streaming mode (default: False)
**kwargs: Additional parameters passed to the service
Returns:
Union[str, Iterator[str]]: Complete response or stream of text chunks
Example:
```python
socket = api.socket()
flow = socket.flow("default")
# Streaming prompt execution
for chunk in flow.prompt(
id="summarize-template",
variables={"topic": "quantum computing", "length": "brief"},
streaming=True
):
print(chunk, end='', flush=True)
```
"""
request = {
"id": id,
"variables": variables,
@ -397,7 +623,32 @@ class SocketFlowInstance:
limit: int = 10,
**kwargs: Any
) -> Dict[str, Any]:
"""Query graph embeddings for semantic search"""
"""
Query knowledge graph entities using semantic similarity.
Args:
text: Query text for semantic search
user: User/keyspace identifier
collection: Collection identifier
limit: Maximum number of results (default: 10)
**kwargs: Additional parameters passed to the service
Returns:
dict: Query results with similar entities
Example:
```python
socket = api.socket()
flow = socket.flow("default")
results = flow.graph_embeddings_query(
text="physicist who discovered radioactivity",
user="trustgraph",
collection="scientists",
limit=5
)
```
"""
request = {
"text": text,
"user": user,
@ -409,7 +660,25 @@ class SocketFlowInstance:
return self.client._send_request_sync("graph-embeddings", self.flow_id, request, False)
def embeddings(self, text: str, **kwargs: Any) -> Dict[str, Any]:
"""Generate text embeddings"""
"""
Generate vector embeddings for text.
Args:
text: Input text to embed
**kwargs: Additional parameters passed to the service
Returns:
dict: Response containing vectors
Example:
```python
socket = api.socket()
flow = socket.flow("default")
result = flow.embeddings("quantum computing")
vectors = result.get("vectors", [])
```
"""
request = {"text": text}
request.update(kwargs)
@ -425,7 +694,34 @@ class SocketFlowInstance:
limit: int = 100,
**kwargs: Any
) -> Dict[str, Any]:
"""Triple pattern query"""
"""
Query knowledge graph triples using pattern matching.
Args:
s: Subject URI (optional, use None for wildcard)
p: Predicate URI (optional, use None for wildcard)
o: Object URI or Literal (optional, use None for wildcard)
user: User/keyspace identifier (optional)
collection: Collection identifier (optional)
limit: Maximum results to return (default: 100)
**kwargs: Additional parameters passed to the service
Returns:
dict: Query results with matching triples
Example:
```python
socket = api.socket()
flow = socket.flow("default")
# Find all triples about a specific subject
result = flow.triples_query(
s="http://example.org/person/marie-curie",
user="trustgraph",
collection="scientists"
)
```
"""
request = {"limit": limit}
if s is not None:
request["s"] = str(s)
@ -450,7 +746,41 @@ class SocketFlowInstance:
operation_name: Optional[str] = None,
**kwargs: Any
) -> Dict[str, Any]:
"""GraphQL query"""
"""
Execute a GraphQL query against structured objects.
Args:
query: GraphQL query string
user: User/keyspace identifier
collection: Collection identifier
variables: Optional query variables dictionary
operation_name: Optional operation name for multi-operation documents
**kwargs: Additional parameters passed to the service
Returns:
dict: GraphQL response with data, errors, and/or extensions
Example:
```python
socket = api.socket()
flow = socket.flow("default")
query = '''
{
scientists(limit: 10) {
name
field
discoveries
}
}
'''
result = flow.objects_query(
query=query,
user="trustgraph",
collection="scientists"
)
```
"""
request = {
"query": query,
"user": user,
@ -470,7 +800,28 @@ class SocketFlowInstance:
parameters: Dict[str, Any],
**kwargs: Any
) -> Dict[str, Any]:
"""Execute MCP tool"""
"""
Execute a Model Context Protocol (MCP) tool.
Args:
name: Tool name/identifier
parameters: Tool parameters dictionary
**kwargs: Additional parameters passed to the service
Returns:
dict: Tool execution result
Example:
```python
socket = api.socket()
flow = socket.flow("default")
result = flow.mcp_tool(
name="search-web",
parameters={"query": "latest AI news", "limit": 5}
)
```
"""
request = {
"name": name,
"parameters": parameters

128
trustgraph-base/trustgraph/api/types.py
View file

@ -1,3 +1,9 @@
"""
TrustGraph API Type Definitions
Data classes and type definitions for TrustGraph API objects including knowledge
graph elements, metadata structures, and streaming response chunks.
"""
import dataclasses
import datetime
@ -6,23 +12,59 @@ from .. knowledge import hash, Uri, Literal
@dataclasses.dataclass
class Triple:
"""
RDF triple representing a knowledge graph statement.
Attributes:
s: Subject (entity URI or value)
p: Predicate (relationship URI)
o: Object (entity URI, literal value, or typed value)
"""
s : str
p : str
o : str
@dataclasses.dataclass
class ConfigKey:
"""
Configuration key identifier.
Attributes:
type: Configuration type/category (e.g., "llm", "embedding")
key: Specific configuration key within the type
"""
type : str
key : str
@dataclasses.dataclass
class ConfigValue:
"""
Configuration key-value pair.
Attributes:
type: Configuration type/category
key: Specific configuration key
value: Configuration value as string
"""
type : str
key : str
value : str
@dataclasses.dataclass
class DocumentMetadata:
"""
Metadata for a document in the library.
Attributes:
id: Unique document identifier
time: Document creation/upload timestamp
kind: Document MIME type (e.g., "application/pdf", "text/plain")
title: Document title
comments: Additional comments or description
metadata: List of RDF triples providing structured metadata
user: User/owner identifier
tags: List of tags for categorization
"""
id : str
time : datetime.datetime
kind : str
@ -34,6 +76,18 @@ class DocumentMetadata:
@dataclasses.dataclass
class ProcessingMetadata:
"""
Metadata for an active document processing job.
Attributes:
id: Unique processing job identifier
document_id: ID of the document being processed
time: Processing start timestamp
flow: Flow instance handling the processing
user: User identifier
collection: Target collection for processed data
tags: List of tags for categorization
"""
id : str
document_id : str
time : datetime.datetime
@ -44,6 +98,19 @@ class ProcessingMetadata:
@dataclasses.dataclass
class CollectionMetadata:
"""
Metadata for a data collection.
Collections provide logical grouping and isolation for documents and
knowledge graph data.
Attributes:
user: User/owner identifier
collection: Collection identifier
name: Human-readable collection name
description: Collection description
tags: List of tags for categorization
"""
user : str
collection : str
name : str
@ -54,29 +121,80 @@ class CollectionMetadata:
@dataclasses.dataclass
class StreamingChunk:
"""Base class for streaming chunks"""
"""
Base class for streaming response chunks.
Used for WebSocket-based streaming operations where responses are delivered
incrementally as they are generated.
Attributes:
content: The text content of this chunk
end_of_message: True if this is the final chunk of a message segment
"""
content: str
end_of_message: bool = False
@dataclasses.dataclass
class AgentThought(StreamingChunk):
"""Agent reasoning chunk"""
"""
Agent reasoning/thought process chunk.
Represents the agent's internal reasoning or planning steps during execution.
These chunks show how the agent is thinking about the problem.
Attributes:
content: Agent's thought text
end_of_message: True if this completes the current thought
chunk_type: Always "thought"
"""
chunk_type: str = "thought"
@dataclasses.dataclass
class AgentObservation(StreamingChunk):
"""Agent tool observation chunk"""
"""
Agent tool execution observation chunk.
Represents the result or observation from executing a tool or action.
These chunks show what the agent learned from using tools.
Attributes:
content: Observation text describing tool results
end_of_message: True if this completes the current observation
chunk_type: Always "observation"
"""
chunk_type: str = "observation"
@dataclasses.dataclass
class AgentAnswer(StreamingChunk):
"""Agent final answer chunk"""
"""
Agent final answer chunk.
Represents the agent's final response to the user's query after completing
its reasoning and tool use.
Attributes:
content: Answer text
end_of_message: True if this completes the current answer segment
end_of_dialog: True if this completes the entire agent interaction
chunk_type: Always "final-answer"
"""
chunk_type: str = "final-answer"
end_of_dialog: bool = False
@dataclasses.dataclass
class RAGChunk(StreamingChunk):
"""RAG streaming chunk"""
"""
RAG (Retrieval-Augmented Generation) streaming chunk.
Used for streaming responses from graph RAG, document RAG, text completion,
and other generative services.
Attributes:
content: Generated text content
end_of_stream: True if this is the final chunk of the stream
error: Optional error information if an error occurred
chunk_type: Always "rag"
"""
chunk_type: str = "rag"
end_of_stream: bool = False
error: Optional[Dict[str, str]] = None