Skip to content

README.md

Latest commit

 

History

History
153 lines (115 loc) · 4.48 KB

README.md

File metadata and controls

153 lines (115 loc) · 4.48 KB
Raw

SochDB Python SDK Examples

This directory contains practical examples demonstrating SochDB Python SDK usage across various scenarios.

Prerequisites

# Install the SDK
cd sochdb-python-sdk
pip install -e .

# Build the native library (for embedded mode)
cd ..
cargo build --release

Examples Overview

Example Mode Description
01_basic_operations.py Embedded Basic CRUD operations
02_transactions.py Embedded Transaction handling and rollback
03_path_navigation.py Embedded Hierarchical path-based data access
04_scan_and_range.py Embedded Range scans and batch operations
05_user_store.py Embedded Real-world user management example
06_json_documents.py Embedded Storing and querying JSON documents
07_session_cache.py Embedded Session caching use case
08_ipc_client.py IPC Multi-process access via IPC
26_hosted_studio_ingest.py gRPC + Studio Remote write plus hosted Studio event ingestion
27_hosted_remote_smoke.py gRPC Minimal hosted remote smoke test for SDK parity
28_crewai_knowledge_tools.py Embedded + CrewAI CrewAI tools backed by SochDB knowledge search
29_crewai_remote_tools.py gRPC + CrewAI CrewAI tools backed by a remote SochDB collection

Running Examples

Embedded Mode Examples (01-07)

# Set the library path
export SOCHDB_LIB_PATH=/path/to/toon_database/target/release

# Run any example
python examples/01_basic_operations.py

IPC Mode Example (08)

Requires a running SochDB IPC server:

# Start the server first (from sochdb-storage)
cargo run --bin ipc_server -- --socket /tmp/sochdb.sock

# Then run the example
python examples/08_ipc_client.py

Hosted Remote Smoke Test (27)

Runs a minimal hosted gRPC check without requiring Studio event ingestion:

SOCHDB_GRPC_ADDRESS=studio.agentslab.host:50053 \
python examples/27_hosted_remote_smoke.py

There is also a matching manual GitHub Actions workflow at .github/workflows/hosted-smoke.yml for running the same hosted smoke path on demand.

Latest hosted validation:

  • GitHub-hosted workflow passed on May 5, 2026: https://github.com/SaiSandeepKantareddy/sochdb-python-sdk/actions/runs/25357489415

CrewAI Knowledge Tools (28)

Runs a CrewAI agent with SochDB-backed search and remember tools:

pip install -e ".[crewai]"
OPENAI_API_KEY=... python examples/28_crewai_knowledge_tools.py

CrewAI Remote Knowledge Tools (29)

Runs the same CrewAI tool surface against a hosted SochDB collection over gRPC:

pip install -e ".[crewai]"
OPENAI_API_KEY=... \
SOCHDB_GRPC_ADDRESS=studio.agentslab.host:50053 \
python examples/29_crewai_remote_tools.py

If you want to validate just the remote SochDB side before wiring an LLM provider, you can run a storage/search smoke instead:

SOCHDB_GRPC_ADDRESS=studio.agentslab.host:50053 \
SOCHDB_CREWAI_SKIP_KICKOFF=1 \
python examples/29_crewai_remote_tools.py

Directory Structure

examples/
├── README.md           # This file
├── 01_basic_operations.py      # Simple key-value CRUD
├── 02_transactions.py          # ACID transaction examples
├── 03_path_navigation.py       # Path-native API examples
├── 04_scan_and_range.py        # Range queries
├── 05_user_store.py            # User management use case
├── 06_json_documents.py        # JSON document storage
├── 07_session_cache.py         # Session caching pattern
├── 08_ipc_client.py            # IPC client examples
├── 26_hosted_studio_ingest.py  # Remote SochDB + hosted Studio example
├── 27_hosted_remote_smoke.py   # Minimal hosted gRPC smoke test
├── 28_crewai_knowledge_tools.py # CrewAI tools backed by SochDB knowledge
├── 29_crewai_remote_tools.py   # CrewAI tools backed by remote SochDB
└── shared/
    └── mock_server.py          # Mock server for testing

Quick Start

The simplest example to get started:

from sochdb import Database

# Open/create a database
db = Database.open("./my_data")

# Store data
db.put(b"greeting", b"Hello, SochDB!")

# Retrieve data
value = db.get(b"greeting")
print(value)  # b"Hello, SochDB!"

# Clean up
db.close()

Use Case Reference

  • Key-Value Cache: Examples 1, 7
  • User/Entity Management: Example 5
  • Document Storage: Example 6
  • Multi-process Access: Example 8
  • Batch Operations: Example 4
  • Hierarchical Data: Example 3