SVECTOR Python SDK

Official Python SDK for accessing SVECTOR APIs.

SVECTOR develops high-performance AI models and automation solutions, specializing in artificial intelligence, mathematical computing, and computational research. This Python SDK provides programmatic access to SVECTOR's API services, offering intuitive model completions, document processing, and seamless integration with SVECTOR's advanced AI systems (e.g., Spec-3, Spec-3-Turbo, Theta-35).

The library includes type hints for request parameters and response fields, and offers both synchronous and asynchronous clients powered by httpx and requests.

Quick Start

pip install svector-sdk

fromsvectorimportSVECTORclient=SVECTOR(api_key="your-api-key") # or set SVECTOR_API_KEY env var# Conversational API - just provide instructions and input!response=client.conversations.create(
model="spec-3-turbo",
instructions="You are a helpful AI assistant that explains complex topics clearly.",
input="What is artificial intelligence?",
)
print(response.output)

Table of Contents

• Installation
• Authentication
• Core Features
• Conversations API (Recommended)
• Chat Completions API (Advanced)
• Vision API
• Streaming Responses
• File Management & Document Processing
• Models
• Error Handling
• Async Support
• Advanced Configuration
• Complete Examples
• Best Practices
• Contributing

Installation

pip

pip install svector-sdk

Development Install

git clone https://github.com/svector-corporation/svector-python
cd svector-python
pip install -e ".[dev]"

Authentication

Get your API key from the SVECTOR Dashboard and set it as an environment variable:

export SVECTOR_API_KEY="your-api-key-here"

Or pass it directly to the client:

fromsvectorimportSVECTORclient=SVECTOR(api_key="your-api-key-here")

Core Features

• Conversations API - Simple instructions + input interface
• Advanced Chat Completions - Full control with role-based messages
• Vision API - Image analysis, OCR, object detection, and accessibility descriptions
• Real-time Streaming - Server-sent events for live responses
• File Processing - Upload and process documents (PDF, DOCX, TXT, etc.)
• Knowledge Collections - Organize files for enhanced RAG
• Type Safety - Full type hints and IntelliSense support
• Async Support - AsyncSVECTOR client for high-performance applications
• Robust Error Handling - Comprehensive error types and retry logic
• Multi-environment - Works everywhere Python runs

Conversations API (Recommended)

The Conversations API provides a, user-friendly interface. Just provide instructions and input - the SDK handles all the complex role management internally!

Basic Conversation

fromsvectorimportSVECTORclient=SVECTOR()
response=client.conversations.create(
model="spec-3-turbo",
instructions="You are a helpful assistant that explains things clearly.",
input="What is machine learning?",
temperature=0.7,
max_tokens=200,
)
print(response.output)
print(f"Request ID: {response.request_id}")
print(f"Token Usage: {response.usage}")

Conversation with Context

response=client.conversations.create(
model="spec-3-turbo",
instructions="You are a programming tutor that helps students learn coding.",
input="Can you show me an example?",
context=[
"How do I create a function in Python?",
"You can create a function using the def keyword followed by the function name and parameters..."
],
temperature=0.5,
)

Streaming Conversation

stream=client.conversations.create_stream(
model="spec-3-turbo",
instructions="You are a creative storyteller.",
input="Tell me a short story about robots and humans.",
stream=True,
)
print("Story: ", end="", flush=True)
foreventinstream:
ifnotevent.done:
print(event.content, end="", flush=True)
else:
print("\nStory completed!")

Document-based Conversation

# First upload a documentwithopen("research-paper.pdf", "rb") asf:
file_response=client.files.create(f, purpose="default")
# Then ask questions about itresponse=client.conversations.create(
model="spec-3-turbo",
instructions="You are a research assistant that analyzes documents.",
input="What are the key findings in this paper?",
files=[{"type": "file", "id": file_response.file_id}],
)

Chat Completions API (Advanced)

For full control over the conversation structure, use the Chat Completions API with role-based messages:

Basic Chat

response=client.chat.create(
model="spec-3-turbo",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello, how are you?"}
],
max_tokens=150,
temperature=0.7,
)
print(response["choices"][0]["message"]["content"])

Multi-turn Conversation

conversation= [
{"role": "system", "content": "You are a helpful programming assistant."},
{"role": "user", "content": "How do I reverse a string in Python?"},
{"role": "assistant", "content": "You can reverse a string using slicing: string[::-1]"},
{"role": "user", "content": "Can you show me other methods?"}
]
response=client.chat.create(
model="spec-3-turbo",
messages=conversation,
temperature=0.5,
)

Developer Role (System-level Instructions)

response=client.chat.create(
model="spec-3-turbo",
messages=[
{"role": "developer", "content": "You are an expert code reviewer. Provide detailed feedback."},
{"role": "user", "content": "Please review this Python code: def add(a, b): return a + b"}
],
)

Vision API

SVECTOR's Vision API provides powerful image analysis capabilities including object detection, text extraction (OCR), accessibility descriptions, and more.

Basic Image Analysis

Analyze image from URL

fromsvectorimportSVECTORclient=SVECTOR()
# Using the responses API (recommended for simple use cases)response=client.responses.create(
model="spec-3-turbo",
input=[{
"role": "user",
"content": [
{"type": "input_text", "text": "what's in this image?"},
{
"type": "input_image",
"image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg",
},
],
}],
)
print(response.output_text)

Analyze image from base64 data

importbase64fromsvectorimportSVECTORclient=SVECTOR()
# Function to encode the imagedefencode_image(image_path):
withopen(image_path, "rb") asimage_file:
returnbase64.b64encode(image_file.read()).decode("utf-8")
# Path to your imageimage_path="path_to_your_image.jpg"# Getting the Base64 stringbase64_image=encode_image(image_path)
response=client.responses.create(
model="spec-3-turbo",
input=[
{
"role": "user",
"content": [
{ "type": "input_text", "text": "what's in this image?" },
{
"type": "input_image",
"image_url": f"data:image/jpeg;base64,{base64_image}",
},
],
}
],
)
print(response.output_text)

Analyze image from file upload

fromsvectorimportSVECTORclient=SVECTOR()
# Function to create a file with the Files APIdefcreate_file(file_path):
withopen(file_path, "rb") asfile_content:
result=client.files.create(
file=file_content,
purpose="vision",
)
returnresult.id# Getting the file IDfile_id=create_file("path_to_your_image.jpg")
response=client.responses.create(
model="spec-3-turbo",
input=[{
"role": "user",
"content": [
{"type": "input_text", "text": "what's in this image?"},
{
"type": "input_image",
"file_id": file_id,
},
],
}],
)
print(response.output_text)

Advanced Vision Capabilities

Using the Vision API directly

# Detailed image analysisresponse=client.vision.analyze_from_url(
image_url="https://example.com/image.jpg",
prompt="Describe this image in detail, including colors, objects, and composition.",
detail="high"
)
print(response.analysis)
# Extract text from image (OCR)response=client.vision.extract_text(
image_url="https://example.com/document.jpg"
)
print(response.analysis)
# Generate accessibility descriptionresponse=client.vision.describe_for_accessibility(
image_url="https://example.com/chart.jpg"
)
print(response.analysis)
# Detect specific objectsresponse=client.vision.detect_objects(
image_url="https://example.com/scene.jpg",
object_types=["people", "cars", "buildings"]
)
print(response.analysis)
# Generate social media captionsresponse=client.vision.generate_caption(
image_url="https://example.com/photo.jpg",
style="casual"# Options: professional, casual, funny, technical
)
print(response.analysis)

Compare multiple images

images= [
{"url": "https://example.com/image1.jpg"},
{"url": "https://example.com/image2.jpg"},
{"base64": "base64_data_here"}
]
response=client.vision.compare_images(
images=images,
prompt="Compare these images and describe their similarities and differences."
)
print(response.analysis)

Vision Response Object

All vision methods return a VisionResponse object with the following properties:

response=client.vision.analyze_from_url("https://example.com/image.jpg")
print(response.analysis) # The analysis textprint(response.output_text) # Alias for analysis (compatibility)print(response.usage) # Token usage informationprint(response.request_id) # Request ID for debugging

Vision Error Handling

fromsvectorimportSVECTOR, APIConnectionTimeoutError, RateLimitErrorclient=SVECTOR()
try:
response=client.vision.analyze_from_url(
image_url="https://example.com/large-image.jpg",
timeout=30, # Custom timeout in secondsdetail="low"# Use low detail for faster processing
)
print(response.analysis)
exceptAPIConnectionTimeoutErrorase:
print(f"Request timed out: {e}")
print("Try using a smaller image or setting detail='low'")
exceptRateLimitErrorase:
print(f"Rate limit exceeded: {e}")
exceptExceptionase:
print(f"Vision analysis failed: {e}")

Complete Vision API Reference

Advanced Vision Features

# Confidence scoring - get confidence level with analysisresult=client.vision.analyze_with_confidence(
image_url="https://example.com/image.jpg",
prompt="Analyze this image"
)
print(f"Analysis: {result['analysis']}")
print(f"Confidence: {result['confidence']}%")
# Batch processing - analyze multiple imagesimages= [
{"image_url": "https://example.com/image1.jpg", "prompt": "Describe this"},
{"image_url": "https://example.com/image2.jpg", "prompt": "What's in this image?"}
]
results=client.vision.batch_analyze(images, delay=1.0)
fori, resultinenumerate(results):
print(f"Image {i+1}: {result['analysis']}")
# Image comparison - compare multiple imagesimages= [
{"url": "https://example.com/before.jpg"},
{"url": "https://example.com/after.jpg"}
]
response=client.vision.compare_images(
images=images,
prompt="Compare these images and describe the differences"
)
print(response.analysis)
# Caption generation for social mediastyles= ["casual", "professional", "funny", "technical"]
forstyleinstyles:
response=client.vision.generate_caption(
image_url="https://example.com/photo.jpg",
style=style
)
print(f"{style.title()}: {response.analysis}")

Utility Functions

fromsvectorimportencode_image, create_data_url# Encode local image to base64base64_string=encode_image("path/to/your/image.jpg")
# Create data URL from base64data_url=create_data_url(base64_string, "image/jpeg")
# Use with vision APIresponse=client.vision.analyze_from_base64(
base64_data=base64_string,
prompt="Analyze this local image"
)

Supported Image Formats

• PNG (.png)
• JPEG (.jpeg, .jpg)
• WEBP (.webp)
• GIF (.gif) - Non-animated only

Best Practices for Vision

1. Choose the right detail level: Use "high" for complex images requiring detailed analysis
2. Optimize image size: Smaller images process faster while maintaining quality
3. Use specific prompts: Better prompts lead to more relevant analysis
4. Handle rate limits: Add delays between batch requests
5. Validate images: Ensure images meet format and content requirements
6. Use timeouts: Set appropriate timeouts for large images
7. Error handling: Always wrap vision calls in try-catch blocks

Complete Vision Example

importosimportbase64fromsvectorimportSVECTOR, encode_imageclassVisionAnalyzer:
def__init__(self, api_key: str):
self.client=SVECTOR(api_key=api_key, timeout=60)
defanalyze_image(self, image_path: str, prompt: str=None) ->str:
"""Analyze a local image file"""try:
# Method 1: Upload file and analyze by IDwithopen(image_path, 'rb') asf:
file_response=self.client.files.create(
file=f,
purpose="vision",
filename=os.path.basename(image_path)
)
result=self.client.vision.analyze_from_file_id(
file_id=file_response["file_id"],
prompt=promptor"Provide a comprehensive analysis of this image.",
model="spec-3-turbo",
max_tokens=800,
detail="high"
)
returnresult.analysisexceptExceptionase:
returnf"Analysis failed: {e}"defanalyze_url(self, image_url: str, prompt: str=None) ->str:
"""Analyze an image from URL"""try:
result=self.client.vision.analyze_from_url(
image_url=image_url,
prompt=promptor"Analyze this image in detail.",
model="spec-3-turbo",
detail="high"
)
returnresult.analysisexceptExceptionase:
returnf"Analysis failed: {e}"defextract_text(self, image_path: str) ->str:
"""Extract text from image (OCR)"""try:
base64_image=encode_image(image_path)
result=self.client.vision.extract_text(
image_base64=base64_image,
model="spec-3-turbo"
)
returnresult.analysisexceptExceptionase:
returnf"OCR failed: {e}"# Usageanalyzer=VisionAnalyzer(api_key="your-api-key")
# Analyze local imageanalysis=analyzer.analyze_image(
"path/to/image.jpg", "Describe the objects and colors in this image"
)
print(analysis)
# Analyze web imageanalysis=analyzer.analyze_url(
"https://example.com/image.jpg",
"What emotions does this image convey?"
)
print(analysis)
# Extract texttext=analyzer.extract_text("path/to/document.jpg")
print(f"Extracted text: {text}")

Streaming Responses

Both Conversations and Chat APIs support real-time streaming:

Conversations Streaming

stream=client.conversations.create_stream(
model="spec-3-turbo",
instructions="You are a creative writer.",
input="Write a poem about technology.",
stream=True,
)
foreventinstream:
ifnotevent.done:
print(event.content, end="", flush=True)
else:
print("\nStream completed")

Chat Streaming

stream=client.chat.create_stream(
model="spec-3-turbo",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Explain quantum computing"}
],
stream=True,
)
foreventinstream:
if"choices"ineventandlen(event["choices"]) >0:
delta=event["choices"][0].get("delta", {})
content=delta.get("content", "")
ifcontent:
print(content, end="", flush=True)

File Management & Document Processing

Upload and process various file formats for enhanced AI capabilities:

Upload from File

frompathlibimportPath# PDF documentwithopen("document.pdf", "rb") asf:
pdf_file=client.files.create(f, purpose="default")
# Text file from pathfile_response=client.files.create(
Path("notes.txt"), purpose="default"
)
print(f"File uploaded: {file_response.file_id}")

Upload from Bytes

withopen("document.pdf", "rb") asf:
data=f.read()
file_response=client.files.create(
data, purpose="default", filename="document.pdf"
)

Upload from String Content

content="""# Research NotesThis document contains important findings..."""file_response=client.files.create(
content.encode(), purpose="default", filename="notes.md"
)

Document Q&A

# Upload documentswithopen("manual.pdf", "rb") asf:
doc1=client.files.create(f, purpose="default")
withopen("faq.docx", "rb") asf:
doc2=client.files.create(f, purpose="default")
# Ask questions about the documentsanswer=client.conversations.create(
model="spec-3-turbo",
instructions="You are a helpful assistant that answers questions based on the provided documents.",
input="What are the key features mentioned in the manual?",
files=[
{"type": "file", "id": doc1.file_id},
{"type": "file", "id": doc2.file_id}
],
)

Knowledge Collections

Organize multiple files into collections for better performance and context management:

# Add files to a knowledge collectionresult1=client.knowledge.add_file("collection-123", "file-456")
result2=client.knowledge.add_file("collection-123", "file-789")
# Use the entire collection in conversationsresponse=client.conversations.create(
model="spec-3-turbo",
instructions="You are a research assistant with access to our knowledge base.",
input="Summarize all the information about our products.",
files=[{"type": "collection", "id": "collection-123"}],
)

Models

SVECTOR provides several cutting-edge foundational AI models:

Available Models

# List all available modelsmodels=client.models.list()
print(models["models"])

SVECTOR's Foundational Models:

• spec-3-turbo - Fast, efficient model for most use cases
• spec-3 - Standard model with balanced performance
• theta-35-mini - Lightweight model for simple tasks
• theta-35 - Advanced model for complex reasoning

Model Selection Guide

# For quick responses and general tasksquick_response=client.conversations.create(
model="spec-3-turbo",
instructions="You are a helpful assistant.",
input="What time is it?",
)
# For complex reasoning and analysiscomplex_analysis=client.conversations.create(
model="theta-35",
instructions="You are an expert data analyst.",
input="Analyze the trends in this quarterly report.",
files=[{"type": "file", "id": "report-file-id"}],
)
# For lightweight taskssimple_task=client.conversations.create(
model="theta-35-mini",
instructions="You help with simple questions.",
input="What is 2 + 2?",
)

Error Handling

The SDK provides comprehensive error handling with specific error types:

fromsvectorimport (
SVECTOR, AuthenticationError, RateLimitError, NotFoundError,
APIError
)
client=SVECTOR()
try:
response=client.conversations.create(
model="spec-3-turbo",
instructions="You are a helpful assistant.",
input="Hello world",
)
print(response.output)
exceptAuthenticationErrorase:
print(f"Invalid API key: {e}")
print("Get your API key from https://www.svector.co.in")
exceptRateLimitErrorase:
print(f"Rate limit exceeded: {e}")
print("Please wait before making another request")
exceptNotFoundErrorase:
print(f"Resource not found: {e}")
exceptAPIErrorase:
print(f"API error: {e} (Status: {e.status_code})")
print(f"Request ID: {getattr(e, 'request_id', 'N/A')}")
exceptExceptionase:
print(f"Unexpected error: {e}")

Available Error Types

• AuthenticationError - Invalid API key or authentication issues
• PermissionDeniedError - Insufficient permissions for the resource
• NotFoundError - Requested resource not found
• RateLimitError - API rate limit exceeded
• UnprocessableEntityError - Invalid request data or parameters
• InternalServerError - Server-side errors
• APIConnectionError - Network connection issues
• APIConnectionTimeoutError - Request timeout

Async Support

The SDK provides full async support with AsyncSVECTOR:

Async Basic Usage

importasynciofromsvectorimportAsyncSVECTORasyncdefmain():
asyncwithAsyncSVECTOR() asclient:
response=awaitclient.conversations.create(
model="spec-3-turbo",
instructions="You are a helpful assistant.",
input="Explain quantum computing in simple terms.",
)
print(response.output)
asyncio.run(main())

Async Streaming

asyncdefstreaming_example():
asyncwithAsyncSVECTOR() asclient:
stream=awaitclient.conversations.create_stream(
model="spec-3-turbo",
instructions="You are a creative storyteller.",
input="Write a poem about technology.",
stream=True,
)
asyncforeventinstream:
ifnotevent.done:
print(event.content, end="", flush=True)
print()
asyncio.run(streaming_example())

Async Concurrent Requests

asyncdefconcurrent_example():
asyncwithAsyncSVECTOR() asclient:
# Multiple async conversationstasks= [
client.conversations.create(
model="spec-3-turbo",
instructions="You are a helpful assistant.",
input=f"What is {topic}?"
)
fortopicin ["artificial intelligence", "quantum computing", "blockchain"]
]
responses=awaitasyncio.gather(*tasks, return_exceptions=True)
topics= ["artificial intelligence", "quantum computing", "blockchain"]
fortopic, responseinzip(topics, responses):
ifisinstance(response, Exception):
print(f"{topic}: Error - {response}")
else:
print(f"{topic}: {response.output[:100]}...")
asyncio.run(concurrent_example())

Advanced Configuration

Client Configuration

fromsvectorimportSVECTORclient=SVECTOR(
api_key="your-api-key",
base_url="https://api.svector.co.in", # Custom API endpointtimeout=30, # Request timeout in secondsmax_retries=3, # Retry failed requestsverify_ssl=True, # SSL verificationhttp_client=None, # Custom HTTP client
)

Async Configuration

fromsvectorimportAsyncSVECTORclient=AsyncSVECTOR(
api_key="your-api-key",
timeout=30,
max_retries=3,
)

Per-request Options

response=client.conversations.create(
model="spec-3-turbo",
instructions="You are a helpful assistant.",
input="Hello",
timeout=60, # Override timeout for this requestheaders={ # Additional headers"X-Custom-Header": "value",
"X-Request-Source": "my-app"
}
)

Raw Response Access

# Get both response data and raw HTTP responseresponse, raw=client.conversations.create_with_response(
model="spec-3-turbo",
instructions="You are a helpful assistant.",
input="Hello",
)
print(f"Status: {raw.status_code}")
print(f"Headers: {raw.headers}")
print(f"Response: {response.output}")
print(f"Request ID: {response.request_id}")

Complete Examples

Intelligent Chat Application

fromsvectorimportSVECTORclassIntelligentChat:
def__init__(self, api_key: str):
self.client=SVECTOR(api_key=api_key)
self.conversation_history= []
defchat(self, user_message: str, system_instructions: str=None) ->str:
# Add user message to historyself.conversation_history.append(user_message)
response=self.client.conversations.create(
model="spec-3-turbo",
instructions=system_instructionsor"You are a helpful and friendly AI assistant.",
input=user_message,
context=self.conversation_history[-10:], # Keep last 10 messagestemperature=0.7,
)
# Add AI response to historyself.conversation_history.append(response.output)
returnresponse.outputdefstream_chat(self, user_message: str):
print("Assistant: ", end="", flush=True)
stream=self.client.conversations.create_stream(
model="spec-3-turbo",
instructions="You are a helpful AI assistant. Be conversational and engaging.",
input=user_message,
context=self.conversation_history[-6:],
stream=True,
)
full_response=""foreventinstream:
ifnotevent.done:
print(event.content, end="", flush=True)
full_response+=event.contentprint()
self.conversation_history.append(user_message)
self.conversation_history.append(full_response)
defclear_history(self):
self.conversation_history= []
# Usageimportoschat=IntelligentChat(os.environ.get("SVECTOR_API_KEY"))
# Regular chatprint(chat.chat("Hello! How are you today?"))
# Streaming chatchat.stream_chat("Tell me an interesting fact about space.")
# Specialized chatprint(chat.chat(
"Explain quantum computing", "You are a physics professor who explains complex topics in simple terms."
))

Document Analysis System

fromsvectorimportSVECTORfrompathlibimportPathclassDocumentAnalyzer:
def__init__(self):
self.client=SVECTOR()
self.uploaded_files= []
defadd_document(self, file_path: str) ->str:
try:
withopen(file_path, "rb") asf:
file_response=self.client.files.create(
f, purpose="default",
filename=Path(file_path).name
)
self.uploaded_files.append(file_response.file_id)
print(f"Uploaded: {file_path} (ID: {file_response.file_id})")
returnfile_response.file_idexceptExceptionaserror:
print(f"Failed to upload {file_path}: {error}")
raiseerrordefadd_document_from_text(self, content: str, filename: str) ->str:
file_response=self.client.files.create(
content.encode(), purpose="default", filename=filename
)
self.uploaded_files.append(file_response.file_id)
returnfile_response.file_iddefanalyze(self, query: str, analysis_type: str="insights") ->str:
instructions= {
"summary": "You are an expert document summarizer. Provide clear, concise summaries.",
"questions": "You are an expert analyst. Answer questions based on the provided documents with citations.",
"insights": "You are a research analyst. Extract key insights, patterns, and important findings."
}
response=self.client.conversations.create(
model="spec-3-turbo",
instructions=instructions[analysis_type],
input=query,
files=[{"type": "file", "id": file_id} forfile_idinself.uploaded_files],
temperature=0.3, # Lower temperature for more factual responses
)
returnresponse.outputdefcompare_documents(self, query: str) ->str:
iflen(self.uploaded_files) <2:
raiseValueError("Need at least 2 documents to compare")
returnself.analyze(
f"Compare and contrast the documents regarding: {query}",
"insights"
)
defget_uploaded_file_ids(self):
returnself.uploaded_files.copy()
# Usageanalyzer=DocumentAnalyzer()
# Add multiple documentsanalyzer.add_document("./reports/quarterly-report.pdf")
analyzer.add_document("./reports/annual-summary.docx")
analyzer.add_document_from_text("""# Meeting NotesKey decisions:1. Increase R&D budget by 15%2. Launch new product line in Q33. Expand team by 5 engineers""", "meeting-notes.md")
# Analyze documentssummary=analyzer.analyze(
"Provide a comprehensive summary of all documents",
"summary"
)
print("Summary:", summary)
insights=analyzer.analyze(
"What are the key business decisions and their potential impact?",
"insights"
)
print("Insights:", insights)
# Compare documentscomparison=analyzer.compare_documents(
"financial performance and future projections"
)
print("Comparison:", comparison)

Multi-Model Comparison

fromsvectorimportSVECTORimporttimeclassModelComparison:
def__init__(self):
self.client=SVECTOR()
defcompare_models(self, prompt: str):
models= ["spec-3-turbo", "spec-3", "theta-35", "theta-35-mini"]
print(f"Comparing models for prompt: \"{prompt}\"\n")
results= []
formodelinmodels:
try:
start_time=time.time()
response=self.client.conversations.create(
model=model,
instructions="You are a helpful assistant. Be concise but informative.",
input=prompt,
max_tokens=150,
)
duration=time.time() -start_timeresults.append({
"model": model,
"response": response.output,
"duration": duration,
"usage": response.usage,
"success": True
})
exceptExceptionase:
results.append({
"model": model,
"error": str(e),
"success": False
})
# Display resultsforresultinresults:
ifresult["success"]:
print(f"Model: {result['model']}")
print(f"Duration: {result['duration']:.2f}s")
print(f"Tokens: {result['usage'].get('total_tokens', 'N/A')}")
print(f"Response: {result['response'][:200]}...")
print("─"*80)
else:
print(f"{result['model']} failed: {result['error']}")
# Usagecomparison=ModelComparison()
comparison.compare_models("Explain the concept of artificial general intelligence")

Best Practices

1. Use Conversations API for Simplicity

# Recommended: Clean and simpleresponse=client.conversations.create(
model="spec-3-turbo",
instructions="You are a helpful assistant.",
input=user_message,
)
# More complex: Manual role managementresponse=client.chat.create(
model="spec-3-turbo",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": user_message}
],
)

2. Handle Errors Gracefully

importtimedefchat_with_retry(client, prompt, max_retries=3):
forattemptinrange(max_retries):
try:
returnclient.conversations.create(
model="spec-3-turbo",
instructions="You are helpful.",
input=prompt
)
exceptRateLimitError:
ifattempt<max_retries-1:
wait_time=2**attempt# Exponential backofftime.sleep(wait_time)
else:
raise

3. Use Appropriate Models

# For quick responsesmodel="spec-3-turbo"# For complex reasoningmodel="theta-35"# For simple tasksmodel="theta-35-mini"

4. Optimize File Usage

# Upload once, use multiple timeswithopen("document.pdf", "rb") asf:
file_response=client.files.create(f, purpose="default")
file_id=file_response.file_id# Use in multiple conversationsforquestioninquestions:
response=client.conversations.create(
model="spec-3-turbo",
instructions="You are a document analyst.",
input=question,
files=[{"type": "file", "id": file_id}],
)

5. Environment Variables

importosfromsvectorimportSVECTOR# Use environment variablesclient=SVECTOR(api_key=os.environ.get("SVECTOR_API_KEY"))
# Don't hardcode API keysclient=SVECTOR(api_key="sk-hardcoded-key-here") # Never do this!

6. Use Context Managers for Async

# Recommended: Use context managerasyncwithAsyncSVECTOR() asclient:
response=awaitclient.conversations.create(...)
# Manual cleanup requiredclient=AsyncSVECTOR()
try:
response=awaitclient.conversations.create(...)
finally:
awaitclient.close()

Testing

Run tests with pytest:

# Install test dependencies
pip install -e ".[test]"# Run tests
pytest
# Run with coverage
pytest --cov=svector

Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create a feature branch
3. Install development dependencies: pip install -e ".[dev]"
4. Make your changes
5. Add tests and documentation
6. Run tests and linting
7. Submit a pull request

License

Apache License - see LICENSE file for details.

Links & Support

• Website: https://www.svector.co.in
• Documentation: https://platform.svector.co.in
• Issues: GitHub Issues
• Support: support@svector.co.in
• PyPI Package: svector-sdk

---

Built with ❤️ by SVECTOR Corporation - Pushing the boundaries of AI, Mathematics, and Computational research