📚 Satori Rust SDK

A comprehensive Rust client library for interacting with the Satori database via WebSockets. Satori is a powerful in-memory database with support for CRUD operations, advanced queries, graph relationships, encryption, AI-powered semantic search, and mindspace conversations.

✨ Features

Ultra-fast CRUD operations ⚡
Advanced queries using field_array for conditional operations 🔍
Real-time notifications 📢
Graph-like relations (vertices and edges) 🕸️
Data encryption and decryption using AES 🔐
Approximate Nearest Neighbor (ANN) search for semantic similarity 🎯
Mindspace conversations for AI-powered context-aware chat 💬

🚀 Installation

Add the following to your Cargo.toml:

[dependencies]

satori-client = "0.1.8"

tokio = { version = "1.36", features = ["full"] }

serde_json = "1.0"

🏁 Quick Start

use satori_client::Satori;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = Satori::connect(
        "username".to_string(),
        "password".to_string(),
        "ws://localhost:8000".to_string()
    ).await?;

    // Create an object
    client.set(serde_json::json!({
        "key": "user:john",
        "data": { "name": "John Doe", "email": "john@example.com", "age": 30 },
        "type": "user"
    })).await?;

    Ok(())
}

📋 Command Reference

All operations are invoked via WebSocket with a JSON request format. The client provides convenient methods for each operation.

Base Request Structure

{
  "command": "OPERATION_NAME",
  "id": "unique-request-id",
  "username": "optional-username",
  "password": "optional-password",
  "key": "object-key",
  "data": { ... }
}

🗃️ CRUD Operations

SET - Create Data

Creates a new object in the database. If no key is provided, a UUID is automatically generated.

client.set(serde_json::json!({
    "key": "user:john",
    "data": { "name": "John Doe", "email": "john@example.com" },
    "type": "user",
    "expires": false,
    "expiration_time": -1
})).await?;

Parameters:

Parameter	Type	Required	Description
`key`	string	No	Object key. If omitted, a UUID is generated
`data`	JSON	No	Object data content (default: `{}`)
`type`	string	No	Object class/type (default: `"normal"`)
`expires`	boolean	No	Whether object expires (default: `false`)
`expiration_time`	integer	No	Expiration timestamp in milliseconds

GET - Read Data

Retrieves one or more objects from the database. If key is "*", returns all objects in memory.

// Get single object
let user = client.get(serde_json::json!({ "key": "user:john" })).await?;

// Get all objects
let all = client.get(serde_json::json!({ "key": "*" })).await?;

// Query by field
let results = client.get(serde_json::json!({
    "field_array": [
        { "field": "age", "value": 30 }
    ],
    "one": true,
    "max": 10
})).await?;

Parameters:

Parameter	Type	Required	Description
`key`	string	No*	Object key to retrieve. Use `"*"` for all objects
`field_array`	array	No*	Query conditions for field-based search
`one`	boolean	No	Return only first match (default: `false`)
`max`	integer	No	Maximum results to return
`encryption_key`	string	No	Key to decrypt encrypted objects

*Either key or field_array must be provided, but not both.

PUT - Update Data

Updates one or more fields of an existing object.

client.put(serde_json::json!({
    "key": "user:john",
    "replace_field": "age",
    "replace_value": 31
})).await?;

// Batch update using field_array
client.put(serde_json::json!({
    "field_array": [{ "field": "type", "value": "user" }],
    "replace_field": "status",
    "replace_value": "active"
})).await?;

Parameters:

Parameter	Type	Required	Description
`key`	string	No*	Object key to update
`field_array`	array	No*	Query to select objects for batch update
`replace_field`	string	Yes	Field name to update
`replace_value`	any	Yes	New value for the field
`encryption_key`	string	No	Key for encrypted objects

*Either key or field_array must be provided.

DELETE - Remove Data

Removes one or more objects from the database.

client.delete(serde_json::json!({ "key": "user:john" })).await?;

// Delete multiple objects matching a query
client.delete(serde_json::json!({
    "field_array": [{ "field": "status", "value": "inactive" }]
})).await?;

Parameters:

Parameter	Type	Required	Description
`key`	string	No*	Object key to delete
`field_array`	array	No*	Query to select objects for deletion

*Either key or field_array must be provided.

📦 Array Manipulation

PUSH - Add to Array

Appends a value to an array field within an object.

client.push(serde_json::json!({
    "key": "user:john",
    "array": "tags",
    "value": "premium"
})).await?;

POP - Remove Last from Array

Removes and returns the last element from an array field.

client.pop(serde_json::json!({
    "key": "user:john",
    "array": "notifications"
})).await?;

SPLICE - Remove First from Array

Removes the first element from an array field.

client.splice(serde_json::json!({
    "key": "user:john",
    "array": "notifications"
})).await?;

REMOVE - Remove Specific Value

Removes a specific value from an array field by finding and removing the first matching element.

client.remove(serde_json::json!({
    "key": "user:john",
    "array": "tags",
    "value": "premium"
})).await?;

Common Parameters:

Parameter	Type	Required	Description
`key`	string	No*	Object key
`field_array`	array	No*	Query for batch operation
`array`	string	Yes	Name of the array field
`value`	any	Yes*	Value to add/remove
`encryption_key`	string	No	Key for encrypted objects

*Required for PUSH and REMOVE; not required for POP and SPLICE.

🔐 Encryption

ENCRYPT

Encrypts the data field of an object using AES encryption.

client.encrypt(serde_json::json!({
    "key": "user:john",
    "encryption_key": "secret-key-123"
})).await?;

DECRYPT

Decrypts an encrypted object's data using the provided encryption key.

client.decrypt(serde_json::json!({
    "key": "user:john",
    "encryption_key": "secret-key-123"
})).await?;

🕸️ Graph Operations

SET_VERTEX

Adds vertices (connections) to an object for graph relationships.

// Simple vertex
client.set_vertex(serde_json::json!({
    "key": "user:john",
    "vertex": "user:jane"
})).await?;

// Vertex with relation
client.set_vertex(serde_json::json!({
    "key": "user:john",
    "vertex": { "vertex": "user:jane", "relation": "friend", "weight": 1.0 }
})).await?;

// Multiple vertices
client.set_vertex(serde_json::json!({
    "key": "user:john",
    "vertex": ["user:jane", "user:alice"]
})).await?;

GET_VERTEX

Retrieves all vertices from an object.

let vertices = client.get_vertex(serde_json::json!({
    "key": "user:john"
})).await?;

DELETE_VERTEX

Removes a specific vertex from an object.

client.delete_vertex(serde_json::json!({
    "key": "user:john",
    "vertex": "user:jane"
})).await?;

DFS - Depth-First Search

Traverses the graph starting from a given node using depth-first search.

let results = client.dfs(serde_json::json!({
    "node": "user:john",
    "relation": "friend"
})).await?;

GRAPH_BFS - Breadth-First Search

Returns all nodes reachable from a starting node using breadth-first search.

let results = client.graph_bfs(serde_json::json!({
    "node": "user:john"
})).await?;

GRAPH_DFS - Graph Depth-First Search

Returns all nodes reachable from a starting node using depth-first search.

let results = client.graph_dfs(serde_json::json!({
    "node": "user:john"
})).await?;

GRAPH_SHORTEST_PATH

Finds the shortest path between a start node and end node using Dijkstra's algorithm.

let path = client.graph_shortest_path(serde_json::json!({
    "node": "user:john",
    "target": "post:123"
})).await?;

GRAPH_CONNECTED_COMPONENTS

Identifies all connected components in the graph (groups of nodes where each node is reachable from any other node in the group).

let components = client.graph_connected_components(serde_json::json!({
    "id": "req-001"
})).await?;

GRAPH_SCC - Strongly Connected Components

Identifies strongly connected components using Tarjan's algorithm.

let scc = client.graph_scc(serde_json::json!({
    "id": "req-001"
})).await?;

GRAPH_DEGREE_CENTRALITY

Calculates the degree centrality (number of connections) for each node in the graph.

let centrality = client.graph_degree_centrality(serde_json::json!({
    "id": "req-001"
})).await?;

GRAPH_CLOSENESS_CENTRALITY

Calculates closeness centrality for each node, which measures how close a node is to all other nodes.

let centrality = client.graph_closeness_centrality(serde_json::json!({
    "id": "req-001"
})).await?;

GRAPH_CENTROID

Finds the node with the highest closeness centrality (the most central node in the graph).

let centroid = client.graph_centroid(serde_json::json!({
    "id": "req-001"
})).await?;

🤖 AI Operations

ANN / GET_SIMILAR

Performs approximate nearest neighbor search to find semantically similar objects using vector embeddings.

// Search by vector
let similar = client.ann(serde_json::json!({
    "vector": [0.1, 0.2, 0.3, ...],
    "k": 10,
    "ef": 25
})).await?;

// Search by existing object's embedding
let similar = client.get_similar(serde_json::json!({
    "key": "user:john",
    "use": "embedding",
    "k": 10
})).await?;

Parameters:

Parameter	Type	Required	Description
`vector`	array	No*	Query vector as array of floats
`key`	string	No*	Use embedding from existing object
`k`	integer	No	Number of neighbors to return (default: 5)
`ef`	integer	No	Search width parameter (default: 25)
`use`	string	No	For key-based search: `"data"` or `"embedding"`

*Either vector or key must be provided.

ASK

Uses AI to answer complex questions about the database. The system automatically gathers relevant context.

let response = client.ask(serde_json::json!({
    "question": "Which user has the most posts?",
    "session": "global",
    "backend": "ollama"
})).await?;

Note: This operation requires a valid license.

💬 Mindspace Operations

Mindspaces provide cognitive contexts for AI-powered conversations and semantic operations.

SET_MINDSPACE / CREATE_MINDSPACE

Creates a new mindspace.

let mindspace_id = client.set_mindspace(serde_json::json!({
    "mindspace_id": "conversation-1"
})).await?;

// Or use alias
let mindspace_id = client.create_mindspace(serde_json::json!({
    "mindspace_id": "conversation-1"
})).await?;

DELETE_MINDSPACE

Removes a mindspace and all its associated context.

client.delete_mindspace(serde_json::json!({
    "mindspace_id": "conversation-1"
})).await?;

CHAT_MINDSPACE

Sends a message to a mindspace and receives an AI-generated response. The mindspace maintains conversation context.

let response = client.chat_mindspace(serde_json::json!({
    "mindspace_id": "conversation-1",
    "message": "What do you know about users?"
})).await?;

LECTURE_MINDSPACE

Imports text corpus into a mindspace for semantic search and context retrieval.

client.lecture_mindspace(serde_json::json!({
    "mindspace_id": "conversation-1",
    "corpus": "User John Doe is a software engineer who specializes in Rust and distributed systems..."
})).await?;

📊 Analytics Operations

GET_OPERATIONS

Returns a log of recent database operations.

let operations = client.get_operations().await?;

GET_ACCESS_FREQUENCY

Returns the query count (access frequency) for a specific object.

let frequency = client.get_access_frequency(serde_json::json!({
    "key": "user:john"
})).await?;

🔔 Real-time Notifications

Receive automatic updates when an object changes:

client.set_notify("user:john", |data| {
    println!("User updated! {:?}", data);
}).await?;

📝 Response Format

All successful responses follow this general structure:

{
  "type": "SUCCESS",
  "message": "OK",
  "id": "request-id",
  "key": "optional-key",
  "data": { ... }
}

Error responses:

{
  "type": "ERROR",
  "message": "Error description",
  "id": "request-id"
}

🧠 Key Concepts

Concept	Description
key	Unique identifier of the object
type	Object type (e.g., 'user', 'post')
data	The actual content stored in the object
field_array	Advanced filters for conditional operations
vertices	Graph-like relationships between objects
encryption_key	Key used for AES encryption/decryption
mindspace	Cognitive context for AI conversations

🤝 Contributing

Questions or suggestions? Feel free to open an issue or contribute!

Made with ❤️ from the Satori team

satori-client 0.1.9

📚 Satori Rust SDK

✨ Features

🚀 Installation

🏁 Quick Start

📋 Command Reference

Base Request Structure

🗃️ CRUD Operations

SET - Create Data

GET - Read Data

PUT - Update Data

DELETE - Remove Data

📦 Array Manipulation

PUSH - Add to Array

POP - Remove Last from Array

SPLICE - Remove First from Array

REMOVE - Remove Specific Value

🔐 Encryption

ENCRYPT

DECRYPT

🕸️ Graph Operations

SET_VERTEX

GET_VERTEX

DELETE_VERTEX

DFS - Depth-First Search

GRAPH_BFS - Breadth-First Search

GRAPH_DFS - Graph Depth-First Search

GRAPH_SHORTEST_PATH

GRAPH_CONNECTED_COMPONENTS

GRAPH_SCC - Strongly Connected Components

GRAPH_DEGREE_CENTRALITY

GRAPH_CLOSENESS_CENTRALITY

GRAPH_CENTROID

🤖 AI Operations

ANN / GET_SIMILAR

ASK

💬 Mindspace Operations

SET_MINDSPACE / CREATE_MINDSPACE

DELETE_MINDSPACE

CHAT_MINDSPACE

LECTURE_MINDSPACE

📊 Analytics Operations

GET_OPERATIONS

GET_ACCESS_FREQUENCY

🔔 Real-time Notifications

📝 Response Format

🧠 Key Concepts

🤝 Contributing