nebula-client 2.2.2

Official Python SDK for Nebula API

Nebula Python SDK

Persistent memory layer for AI applications. Store, search, and retrieve information with semantic understanding.

Requirements

• Python 3.10 or higher

Installation

pip install nebula-client

Quick Start

from nebula import Nebula

# Initialize client
client = Nebula(api_key="your-api-key")

# Create a collection
collection = client.create_cluster(name="my_notes")

# Store a memory
memory_id = client.store_memory({
    "collection_id": collection.id,
    "content": "Machine learning is transforming healthcare",
    "metadata": {"topic": "AI", "importance": "high"}
})

# Search memories
results = client.search(
    query="machine learning healthcare",
    collection_ids=[collection.id],
)

for result in results:
    print(f"Score: {result.score:.2f}")
    print(f"Content: {result.content}")

Core Operations

Collections

# Create
collection = client.create_cluster(name="my_collection", description="Optional description")

# List
collections = client.list_clusters()

# Get by ID or name
collection = client.get_cluster(collection_id)
collection = client.get_cluster_by_name("my_collection")

# Update
client.update_cluster(collection_id, name="new_name")

# Delete
client.delete_cluster(collection_id)

Store Memories

# Single memory
from nebula import Memory

memory = Memory(
    collection_id=collection.id,
    content="Your content here",
    metadata={"category": "example"}
)
memory_id = client.store_memory(memory)

# Batch storage
memories = [
    Memory(collection_id=collection.id, content="First memory"),
    Memory(collection_id=collection.id, content="Second memory")
]
ids = client.store_memories(memories)

Retrieve Memories

# List memories
memories = client.list_memories(collection_ids=[collection.id], limit=10)

# Filter with metadata
memories = client.list_memories(
    collection_ids=[collection.id],
    metadata_filters={"metadata.category": {"$eq": "example"}}
)

# Get specific memory
memory = client.get_memory("memory_id")

Search

# Semantic search
results = client.search(
    query="your search query",
    collection_ids=[collection.id],
)

Delete

# Single deletion
deleted = client.delete("memory_id")  # Returns True

# Batch deletion
result = client.delete(["id1", "id2", "id3"])  # Returns detailed results

Conversations

# Store conversation messages
user_msg = Memory(
    collection_id=collection.id,
    content="What is machine learning?",
    role="user",
    metadata={"content_type": "conversation"},
)
conv_id = client.store_memory(user_msg)

assistant_msg = Memory(
    collection_id=collection.id,
    content="Machine learning is a subset of AI...",
    role="assistant",
    parent_id=conv_id,
    metadata={"content_type": "conversation"},
)
client.store_memory(assistant_msg)

# List conversation memories (filtering by metadata set above)
conversations = client.list_memories(
    collection_ids=[collection.id],
    metadata_filters={"metadata.content_type": {"$eq": "conversation"}},
)

# Get messages from a conversation memory
conversation = client.get_memory(conv_id)
messages = conversation.chunks or []

Async Client

from nebula import AsyncNebula, Memory

async with AsyncNebula(api_key="your-api-key") as client:
    # All methods available with await
    collection = await client.create_cluster(name="async_collection")
    memory_id = await client.store_memory(Memory(
        collection_id=collection.id,
        content="Async memory"
    ))
    results = await client.search("query", collection_ids=[collection.id])

Documentation

• Full Documentation
• API Reference
• Examples

Support

Email [e-mail]