VectorAI Python SDK (vectorai-sdk)
Official Python SDK for VectorAI by AcadmyAI — High-Performance, Stateless Multi-Modal Vector Storage, Document Chunking & Hybrid Semantic Search Gateway.
⚡ Key Features
- Mandatory Authentication & Security: Secure Bearer API key authentication with SHA-256 validation.
- Multi-Modal Document Parsing: Ingest raw text strings, local files (PDF, DOCX, CSV, Text, Code), or remote URLs.
- Configurable Chunking: Built-in
recursive,sentence,paragraph,fixed, andsemanticchunking strategies. - Sub-45ms Semantic Search: Hybrid BM25 Reciprocal Rank Fusion (RRF) and Cohere neural reranking.
- Programmatic Quota & Balance: Track remaining chunk balances, API call volumes, subscription status, and renewal dates.
- Framework Adapters: 1-line integrations for LangChain and LlamaIndex.
- Dual Sync & Async: Synchronous
VectorClientand asynchronousAsyncVectorClientfor FastAPI / asyncio microservices. - Terminal CLI: Run vector searches and ingest files directly from the command line (
vectorai).
📦 Installation
# Standard SDK installation
pip install vectorai-sdk
# With LangChain support
pip install "vectorai-sdk[langchain]"
# With LlamaIndex support
pip install "vectorai-sdk[llamaindex]"
🚀 Quickstart
1. Initialize Client (API Key is Mandatory)
Get your API key from the VectorAI Console.
from vectorai import VectorClient
# Option A: Pass api_key directly
client = VectorClient(api_key="sk-lvl1-9988aabbcc...")
# Option B: Or set the environment variable
# export VECTORAI_API_KEY="sk-lvl1-..."
client = VectorClient()
2. Ingest Content (Text or Files)
# Ingest raw text
result = client.ingest(
raw_text="AcadmyAI provides enterprise AI security, vector retrieval, and market telemetry.",
collection_name="enterprise_kb",
chunking_strategy="recursive",
chunk_size=512,
chunk_overlap=64,
metadata={"author": "Team", "version": "1.0"}
)
print(f"Ingested {result.chunks_created} chunks into collection: {result.collection_name}")
# Ingest local file directly (PDF, DOCX, CSV, TXT, Markdown)
file_result = client.ingest_file(
file_path="./quarterly_report.pdf",
collection_name="financial_docs"
)
3. Semantic & Hybrid Search
results = client.search(
query="What products does AcadmyAI offer?",
collection_name="enterprise_kb",
limit=5,
hybrid=True, # Combines BM25 lexical keyword search with dense vectors
rerank=True # Applies cross-encoder neural reranking
)
for item in results:
print(f"[{item.score:.4f}] Chunk #{item.chunk_index}: {item.text}")
4. Check Account Quota & Left-Over Balances
balance = client.get_usage()
print(f"Tier: {balance.subscription.tier}")
print(f"Days Left: {balance.subscription.days_remaining}")
print(f"Chunks Stored: {balance.quota.total_chunks_stored} / {balance.quota.max_chunks_allowed}")
print(f"Chunks Remaining: {balance.quota.chunks_remaining}")
⚡ Asynchronous Client (AsyncVectorClient)
For high-throughput async microservices (FastAPI, aiohttp, Celery):
import asyncio
from vectorai import AsyncVectorClient
async def main():
async with AsyncVectorClient(api_key="sk-lvl1-...") as client:
# Ingest
await client.ingest(
raw_text="Real-time knowledge streaming...",
collection_name="live_stream"
)
# Search
res = await client.search(
query="knowledge streaming",
collection_name="live_stream",
limit=3
)
for r in res.results:
print(r.score, r.text)
asyncio.run(main())
🔗 LangChain Integration
from vectorai.integrations.langchain import VectorAIStore
vectorstore = VectorAIStore(
api_key="sk-lvl1-...",
collection_name="langchain_kb"
)
# Add texts
vectorstore.add_texts(["LangChain makes LLM agents easy", "VectorAI stores high-dimensional embeddings"])
# Retrieve
retriever = vectorstore.as_retriever(search_kwargs={"k": 2, "hybrid": True})
docs = retriever.get_relevant_documents("How to use VectorAI with LangChain?")
💻 Terminal CLI (vectorai)
The package includes a command-line interface:
# Ingest local file
vectorai ingest ./annual_report.pdf --collection finance --strategy recursive
# Ingest raw text
vectorai ingest "Vector databases index embeddings for semantic retrieval" --collection ai_kb
# Execute semantic search
vectorai search "What was our Q3 EBITDA?" --collection finance --limit 3 --hybrid
# Check remaining quota and subscription balance
vectorai quota
# Check cluster SLA and uptime
vectorai health
⚠️ Error Handling
The SDK exposes clean, typed exceptions mapping to API status codes:
from vectorai import VectorClient
from vectorai.exceptions import (
AuthenticationError,
SubscriptionRequiredError,
QuotaExceededError,
RateLimitError,
VectorAIError
)
try:
client = VectorClient(api_key="sk-lvl1-...")
results = client.search("query", collection_name="docs")
except AuthenticationError:
print("Invalid or missing API key.")
except SubscriptionRequiredError:
print("Subscription is inactive or expired. Recharge at https://vector.acadmyai.com/console")
except QuotaExceededError:
print("Storage chunk quota exceeded.")
except RateLimitError as e:
print(f"Throttled. Retry after {e.retry_after} seconds.")
except VectorAIError as e:
print(f"VectorAI error: {e}")
📄 License
Apache 2.0 License. Powered by AcadmyAI.
Metadata
Release files for vectorai-sdk 1.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| vectorai_sdk-1.1.0.tar.gz | 22.9 kB | Without provenance | Details for vectorai_sdk-1.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| vectorai_sdk-1.1.0-py3-none-any.whl | Python 3 | none | any | Details for vectorai_sdk-1.1.0-py3-none-any.whl |
Total release size: 43.2 kB
Release files / vectorai_sdk-1.1.0.tar.gz
| Download URL | vectorai_sdk-1.1.0.tar.gz |
|---|---|
| Size | 22.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a15241673711dbd163757afc1e2511296b7d9bc17dccbe1cdf8083fc5ecf30af
|
|
BLAKE2b-256 checksum How to use checksums |
c4c7763cd5db0e5001b507af87146538e23de038c4779464f4c58814cb7a81fc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Release files / vectorai_sdk-1.1.0-py3-none-any.whl
| Download URL | vectorai_sdk-1.1.0-py3-none-any.whl |
|---|---|
| Size | 20.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
59bc9a41d3511ad3a12a60708908c44c202ae2bc0f60a62d4c3f39aff9b63761
|
|
BLAKE2b-256 checksum How to use checksums |
1be3fd9ab574fd667e1c8429daf333e176be99f4ed415c88a374feea39e36f3f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.6
|
Security for vectorai-sdk 1.1.0
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.