Python SDK Quickstart

superinstance-fleet — Semantic crate discovery for your Python projects

Installation

pip install superinstance-fleet

Requires Python 3.8+. Uses httpx for async HTTP under the hood.

Quick Start

from superinstance_fleet import FleetClient

client = FleetClient(
    base_url="https://fleet-vector-api.casey-digennaro.workers.dev",
)

# Search for crates by natural language
results = client.search("HTTP client with retry logic")
for crate in results:
    print(f"{crate.name:} (score: {crate.score::.2f})")

# Find crates similar to a known crate
similar = client.similar("reqwest", top_k=5)
print(similar)

# Get personalized recommendations
recs = client.recommend(context="web scraping")
print(recs)

# Check index stats
stats = client.stats()
print(stats)  # → IndexStats(vector_count=..., dimensions=...)

Async Usage

import asyncio
from superinstance_fleet import AsyncFleetClient

async def main():
    client = AsyncFleetClient()
    results = await client.search("async database driver")
    print(results)

asyncio.run(main())

API Reference

search(query, *, top_k=10, threshold=0.5)

Perform a semantic search across all indexed crates.

Parameter	Type	Default	Description
`query`	`str`	—	Natural language search query
`top_k`	`int`	`10`	Max results to return
`threshold`	`float`	`0.5`	Minimum similarity score (0–1)

results = client.search("async runtime", top_k=5, threshold=0.7)

Returns list[CrateResult].

similar(name, *, top_k=10)

Find crates similar to a known crate by name.

Parameter	Type	Default	Description
`name`	`str`	—	Exact crate name to find similar items for
`top_k`	`int`	`10`	Max results to return

alike = client.similar("tokio", top_k=3)

recommend(*, context, top_k=5)

Get crate recommendations based on a context or use case.

Parameter	Type	Default	Description
`context`	`str`	—	Description of your project or use case
`top_k`	`int`	`5`	Max results to return

picks = client.recommend(context="CLI tool with config parsing")

stats()

Retrieve index statistics.

stats = client.stats()
print(stats.vector_count, stats.dimensions)

Returns IndexStats.

Configuration

Option	Type	Default	Description
`base_url`	`str`	`'https://fleet-vector-api.casey-digennaro.workers.dev'`	API endpoint URL
`timeout`	`float`	`10.0`	Request timeout in seconds
`api_key`	`str \| None`	`None`	Optional API key for authenticated endpoints

import os
from superinstance_fleet import FleetClient

client = FleetClient(
    base_url=os.environ["FLEET_API_URL"],
    timeout=5.0,
    api_key=os.environ.get("FLEET_API_KEY"),
)

Error Handling

from superinstance_fleet import FleetClient, FleetError

client = FleetClient()

try:
    results = client.search("database ORM")
except FleetError as e:
    if e.code == "TIMEOUT":
        print("Request timed out")
    elif e.code == "NOT_FOUND":
        print("Crate not found")
    elif e.code == "INVALID_QUERY":
        print("Bad query")
    elif e.code == "SERVER_ERROR":
        print(f"Server error (status {e.status_code})")
except Exception as e:
    print(f"Unexpected error: {e}")

Exception Classes

Exception	Code	Description
`FleetError`	`TIMEOUT`	Request exceeded the configured timeout
`FleetError`	`NOT_FOUND`	Requested crate or resource not found
`FleetError`	`INVALID_QUERY`	Malformed or empty query string
`FleetError`	`SERVER_ERROR`	Upstream server returned 5xx