Skip to main content

Python SDK

The official Python SDK for the OfSelf API.

Installation​

pip install ofself

Requirements:

  • Python 3.8+

Quick Start​

from ofself import OfSelfClient

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

# Create a node
node = client.nodes.create(
    user_id="user-123",
    title="My First Note",
    value="Hello, OfSelf!",
    node_type="note"
)

print(f"Created: {node['id']}")

Configuration​

from ofself import OfSelfClient

client = OfSelfClient(
    api_key="your-api-key",
    base_url="https://api.ofself.ai/api/v1",  # Default
    timeout=30.0  # Request timeout in seconds
)

Environment Variables​

# .env
OFSELF_API_KEY=ofs_key_xxxxxxxxxxxxx
import os
from ofself import OfSelfClient

client = OfSelfClient(api_key=os.environ["OFSELF_API_KEY"])

Resources​

Nodes​

# Create
node = client.nodes.create(
    user_id="user-123",
    title="Meeting Notes",
    value="Content...",
    node_type="note",
    tag_ids=["tag_work"]
)

# List
result = client.nodes.list(
    user_id="user-123",
    node_type="note",
    page=1,
    per_page=20
)

# Get
node = client.nodes.get(user_id="user-123", node_id="node_abc")

# Update
node = client.nodes.update(
    user_id="user-123",
    node_id="node_abc",
    title="Updated Title"
)

# Delete
client.nodes.delete(user_id="user-123", node_id="node_abc")

# Vector search
results = client.nodes.vector_search(
    user_id="user-123",
    query="project deadlines",
    limit=10
)

Tags​

# Create
tag = client.tags.create(
    user_id="user-123",
    name="Work",
    color="#3B82F6"
)

# List
result = client.tags.list(user_id="user-123")

# Get nodes with tag
nodes = client.tags.get_nodes(user_id="user-123", tag_id="tag_work")

# Add tag to node
client.nodes.add_tag(user_id="user-123", node_id="node_abc", tag_id="tag_work")

Files​

# Upload
file = client.files.upload(
    user_id="user-123",
    file="/path/to/document.pdf",
    tag_ids=["tag_documents"]
)

# List
result = client.files.list(user_id="user-123")

# Download
content = client.files.download(user_id="user-123", file_id="file_abc")
with open("downloaded.pdf", "wb") as f:
    f.write(content)

Proposals​

# Create proposal
proposal = client.proposals.create(
    user_id="user-123",
    proposal_type="create_node",
    canonical_data={
        "entities": [{
            "title": "Imported Note",
            "value": "Content",
            "node_type": "note"
        }]
    }
)

# List pending
result = client.proposals.list(user_id="user-123", status="pending")

# Approve (as user)
client.proposals.approve(user_id="user-123", proposal_id="prop_abc")

Graph​

# Get snapshot for visualization
graph = client.graph.snapshot(user_id="user-123")

print(f"Nodes: {len(graph['nodes'])}")
print(f"Edges: {len(graph['edges'])}")

Error Handling​

from ofself import OfSelfClient
from ofself.exceptions import (
    OfSelfError,
    AuthenticationError,
    PermissionDenied,
    NotFoundError,
    ValidationError,
    RateLimitError,
    ServerError,
)

client = OfSelfClient(api_key="your-key")

try:
    node = client.nodes.get(user_id="user-123", node_id="invalid")
except AuthenticationError:
    print("Invalid API key")
except PermissionDenied:
    print("User hasn't authorized your app")
except NotFoundError:
    print("Node not found")
except ValidationError as e:
    print(f"Validation failed: {e.errors}")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except ServerError:
    print("Server error - try again later")
except OfSelfError as e:
    print(f"API error: {e}")

Context Manager​

with OfSelfClient(api_key="your-key") as client:
    nodes = client.nodes.list(user_id="user-123")
# Client is automatically closed

Type Hints​

The SDK is fully typed. Use with IDE for autocomplete:

from ofself import OfSelfClient
from ofself.types import Node, Tag, Proposal

client = OfSelfClient(api_key="key")

# IDE knows return types
node: dict = client.nodes.create(...)

Pagination​

# Iterate through all pages
page = 1
all_nodes = []

while True:
    result = client.nodes.list(
        user_id="user-123",
        page=page,
        per_page=100
    )
    all_nodes.extend(result['items'])
    
    if not result['has_next']:
        break
    page += 1