Metadata-Version: 2.4
Name: vectorai-sdk
Version: 1.0.0
Summary: Official Python SDK for VectorAI — Multi-Modal Vector Storage, Document Chunking & Hybrid Semantic Search Engine by AcadmyAI
Author-email: AcadmyAI <acadmyaiorg@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://vector.acadmyai.com
Project-URL: Documentation, https://vector.acadmyai.com/docs
Project-URL: Repository, https://github.com/nickmudit/trading_level1_backend
Project-URL: Bug Tracker, https://github.com/nickmudit/trading_level1_backend/issues
Keywords: vector-database,vector-search,semantic-search,rag,embeddings,chunking,multi-modal,hybrid-search,ai-infrastructure
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.1.0; extra == "langchain"
Provides-Extra: llamaindex
Requires-Dist: llama-index-core>=0.10.0; extra == "llamaindex"
Provides-Extra: all
Requires-Dist: langchain-core>=0.1.0; extra == "all"
Requires-Dist: llama-index-core>=0.10.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.20.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Dynamic: license-file

# VectorAI Python SDK (`vectorai-sdk`)

[![PyPI version](https://img.shields.io/badge/pypi-v1.0.0-blue.svg)](https://pypi.org/project/vectorai-sdk/)
[![Python versions](https://img.shields.io/badge/python-3.8%20%7C%203.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue)](https://pypi.org/project/vectorai-sdk/)
[![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](LICENSE)
[![Documentation](https://img.shields.io/badge/docs-vector.acadmyai.com-cyan)](https://vector.acadmyai.com/docs)

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

```bash
# 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](https://vector.acadmyai.com/console).

```python
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)

```python
# 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

```python
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

```python
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):

```python
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

```python
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:

```bash
# 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:

```python
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](https://acadmyai.com).
