Skip to main content

EdgeQuake Python SDK

Official Python SDK for the EdgeQuake RAG API.

Features

  • Dual API: Synchronous (EdgeQuake) and asynchronous (AsyncEdgeQuake) clients
  • Type-safe: Full Pydantic v2 models for all request/response types
  • Streaming: SSE streaming for query and chat endpoints
  • Auto-pagination: Transparent iteration over paginated results
  • Auth: API key, JWT, and multi-tenant authentication
  • Retry: Automatic exponential backoff on 429/503 errors

Installation

pip install edgequake-sdk

For WebSocket support (async pipeline progress):

pip install edgequake-sdk[ws]

Quick Start

Sync Client

from edgequake import EdgeQuake

client = EdgeQuake(
    base_url="http://localhost:8080",
    api_key="your-api-key",
)

# Check health
health = client.health()
print(f"Status: {health.status}")

# Upload a document
doc = client.documents.upload(
    content="EdgeQuake is an advanced RAG framework...",
    title="About EdgeQuake",
)
print(f"Document ID: {doc.document_id}")

# Query the knowledge graph
result = client.query.execute(query="What is EdgeQuake?")
print(result.answer)

# Stream a query
for event in client.query.stream(query="Explain RAG"):
    if event.chunk:
        print(event.chunk, end="", flush=True)

Async Client

import asyncio
from edgequake import AsyncEdgeQuake

async def main():
    async with AsyncEdgeQuake(
        base_url="http://localhost:8080",
        api_key="your-api-key",
    ) as client:
        health = await client.health()
        print(f"Status: {health.status}")

        result = await client.query.execute(query="What is EdgeQuake?")
        print(result.answer)

asyncio.run(main())

📍 Resource Namespaces

The Python SDK provides access to 20+ resource namespaces:

Namespace Description Example
documents Document upload, retrieval, and management client.documents.upload(content="...")
query RAG query execution (sync and streaming) client.query.execute(query="...")
graph Knowledge graph exploration and traversal client.graph.get()
chat OpenAI-compatible chat completions client.chat.completions(messages=[...])
conversations Multi-turn conversation management client.conversations.create(title="...")
auth Authentication (login, JWT refresh) client.auth.login(email="...", password="...")
operations Long-running operation tracking client.operations.list()
tenants Multi-tenant management (admin only) client.tenants.create(name="...")
workspaces Workspace management client.workspaces.stats(workspace_id="...")

API Coverage: 100+ endpoints across 9 core resources

For complete API reference, see docs/API.md.

⚙️ Configuration

Configure the client with these options:

from edgequake import EdgeQuake

client = EdgeQuake(
    api_key="YOUR_API_KEY",                # Required: API authentication key
    base_url="http://localhost:8080",      # Server URL (default: http://localhost:8080)
    timeout=30,                            # Request timeout in seconds (default: 30)
    max_retries=3,                         # Retry attempts on failure (default: 3)
    workspace_id="my-workspace",           # Optional: Default workspace context
    tenant_id="my-tenant",                 # Optional: Multi-tenant context
)

Configuration Parameters:

Parameter Type Default Description
api_key str - API key for authentication (required)
base_url str http://localhost:8080 EdgeQuake server URL
timeout int 30 Request timeout in seconds
max_retries int 3 Number of retry attempts on failure
workspace_id str None Default workspace for multi-tenancy
tenant_id str None Tenant ID for multi-tenant setup

🌍 Environment Variables

The SDK reads these environment variables automatically:

Variable Purpose Example
EDGEQUAKE_API_KEY API authentication key (overrides parameter) sk-your-api-key-here
EDGEQUAKE_BASE_URL Server URL http://localhost:8080
EDGEQUAKE_URL Alternative to EDGEQUAKE_BASE_URL https://api.edgequake.example.com
EDGEQUAKE_WORKSPACE_ID Default workspace ID my-workspace
EDGEQUAKE_TENANT_ID Tenant ID for multi-tenancy tenant-123
EDGEQUAKE_TIMEOUT Request timeout in seconds 60

Example:

export EDGEQUAKE_API_KEY="your-api-key"
export EDGEQUAKE_BASE_URL="http://localhost:8080"
python your_script.py

Then in your code:

from edgequake import EdgeQuake

# Reads from environment variables automatically
client = EdgeQuake()

💡 Examples

See the examples/ directory for complete, runnable examples:

Example Description
basic_usage.py Hello world — client setup, health check, simple query
document_upload.py Document management (upload, track, list, delete)
graph_exploration.py Navigate the knowledge graph
query_demo.py Different query modes (simple, hybrid, chat)
streaming_query.py Real-time streaming responses (SSE)
error_handling.py Graceful error handling patterns
configuration.py Advanced configuration and multi-environment setup
multi_tenant.py Tenant and workspace management

Run any example:

export EDGEQUAKE_API_KEY="your-key"
python examples/basic_usage.py

For detailed example descriptions, see examples/README.md.

Authentication

# API Key (recommended for server-side)
client = EdgeQuake(base_url="...", api_key="your-key")

# JWT Bearer token
client = EdgeQuake(base_url="...", jwt="eyJhbGciOi...")

# Multi-tenant
client = EdgeQuake(
    base_url="...",
    api_key="your-key",
    tenant_id="tenant-abc",
    workspace_id="workspace-xyz",
)

Requirements

  • Python >= 3.10
  • httpx >= 0.27
  • pydantic >= 2.0

🔧 Troubleshooting

Connection Errors

Problem: ConnectionError: [Errno 61] Connection refused
Solution: Ensure EdgeQuake server is running on base_url

# Check if server is reachable
curl http://localhost:8080/health

Authentication Errors

Problem: 401 Unauthorized
Solution: Verify that EDGEQUAKE_API_KEY is set correctly

echo $EDGEQUAKE_API_KEY  # Should print your API key

Timeout Errors

Problem: ReadTimeout: HTTPSConnectionPool
Solution: Increase timeout for long-running operations:

client = EdgeQuake(
    api_key="your-key",
    timeout=60  # Increase to 60 seconds
)

Streaming Issues

Problem: SSE connection drops or no output
Solution:

  1. Ensure output is flushed: print(chunk, end="", flush=True)
  2. Check network stability
  3. See docs/STREAMING.md for reconnection strategies

Import Errors

Problem: ModuleNotFoundError: No module named 'edgequake'
Solution: Install the SDK:

pip install edgequake-sdk

Empty Query Results

Problem: Queries return empty or "I don't know" responses
Solution: Upload and process documents first:

doc = client.documents.upload(content="...", title="...")
# Wait for processing to complete (check track_id status)

For more troubleshooting, see:

📚 Documentation

License

Apache License 2.0

Metadata

Release files for edgequake-sdk 0.4.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for edgequake-sdk 0.4.1
File Size Uploaded Provenance Actions
edgequake_sdk-0.4.1.tar.gz 153.6 kB Without provenance Details for edgequake_sdk-0.4.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for edgequake-sdk 0.4.1
File Interpreter ABI Platform Actions
edgequake_sdk-0.4.1-py3-none-any.whl Python 3 none any Details for edgequake_sdk-0.4.1-py3-none-any.whl

Total release size: 218.4 kB

Release files / edgequake_sdk-0.4.1.tar.gz

Download URL edgequake_sdk-0.4.1.tar.gz
Size 153.6 kB
Tags Source
SHA-256 checksum
How to use checksums
e619fb648402212ba08e417a8bd022441b9301e4c2c106d548e13d6d2d7ff8a5
BLAKE2b-256 checksum
How to use checksums
857b54d03d4fef24a1759f2d1f3fb93c4fa448aeb1279e449167d034a87593bd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.5.13

Release files / edgequake_sdk-0.4.1-py3-none-any.whl

Download URL edgequake_sdk-0.4.1-py3-none-any.whl
Size 64.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5deb54dab49fe751bc43fddf91e9292e665da0d57e567ebb356f7836b3231ce4
BLAKE2b-256 checksum
How to use checksums
8f28ab2baa9786d902be7926d9860e8886cd99142a8fe052240e5f1c193c09d8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.5.13

Security for edgequake-sdk 0.4.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page