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, and semantic chunking 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 VectorClient and asynchronous AsyncVectorClient for 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.