tos-vectors – OpenClaw Skill

---

name: tos-vectors description: Manage vector storage and similarity search using TOS Vectors service. Use when working with embeddings, semantic search, RAG systems, recommendation engines, or when the user mentions vector databases, similarity search, or TOS Vectors operations.

TOS Vectors Skill

Comprehensive skill for managing vector storage, indexing, and similarity search using the TOS Vectors service - a cloud-based vector database optimized for AI applications.

Quick Start

Initialize Client

import os
import tos

# Get credentials from environment
ak = os.getenv('TOS_ACCESS_KEY')
sk = os.getenv('TOS_SECRET_KEY')
account_id = os.getenv('TOS_ACCOUNT_ID')

# Configure endpoint and region
endpoint = 'https://tosvectors-cn-beijing.volces.com'
region = 'cn-beijing'

# Create client
client = tos.VectorClient(ak, sk, endpoint, region)

Basic Workflow

# 1. Create vector bucket (like a database)
client.create_vector_bucket('my-vectors')

# 2. Create vector index (like a table)
client.create_index(
    account_id=account_id,
    vector_bucket_name='my-vectors',
    index_name='embeddings-768d',
    data_type=tos.DataType.DataTypeFloat32,
    dimension=768,
    distance_metric=tos.DistanceMetricType.DistanceMetricCosine
)

# 3. Insert vectors
vectors = [
    tos.models2.Vector(
        key='doc-1',
        data=tos.models2.VectorData(float32=[0.1] * 768),
        metadata={'title': 'Document 1', 'category': 'tech'}
    )
]
client.put_vectors(
    vector_bucket_name='my-vectors',
    account_id=account_id,
    index_name='embeddings-768d',
    vectors=vectors
)

# 4. Search similar vectors
query_vector = tos.models2.VectorData(float32=[0.1] * 768)
results = client.query_vectors(
    vector_bucket_name='my-vectors',
    account_id=account_id,
    index_name='embeddings-768d',
    query_vector=query_vector,
    top_k=5,
    return_distance=True,
    return_metadata=True
)

Core Operations

Vector Bucket Management

Create Bucket

client.create_vector_bucket(bucket_name)

List Buckets

result = client.list_vector_buckets(max_results=100)
for bucket in result.vector_buckets:
    print(bucket.vector_bucket_name)

Delete Bucket (must be empty)

client.delete_vector_bucket(bucket_name, account_id)

Vector Index Management

Create Index

client.create_index(
    account_id=account_id,
    vector_bucket_name=bucket_name,
    index_name='my-index',
    data_type=tos.DataType.DataTypeFloat32,
    dimension=128,
    distance_metric=tos.DistanceMetricType.DistanceMetricCosine
)

List Indexes

result = client.list_indexes(bucket_name, account_id)
for index in result.indexes:
    print(f"{index.index_name}: {index.dimension}d")

Vector Data Operations

Insert Vectors (batch up to 500)

vectors = []
for i in range(100):
    vector = tos.models2.Vector(
        key=f'vec-{i}',
        data=tos.models2.VectorData(float32=[...]),
        metadata={'category': 'example'}
    )
    vectors.append(vector)

client.put_vectors(
    vector_bucket_name=bucket_name,
    account_id=account_id,
    index_name=index_name,
    vectors=vectors
)

Query Similar Vectors (KNN search)

results = client.query_vectors(
    vector_bucket_name=bucket_name,
    account_id=account_id,
    index_name=index_name,
    query_vector=query_vector,
    top_k=10,
    filter={"$and": [{"category": "tech"}]},  # Optional metadata filter
    return_distance=True,
    return_metadata=True
)

for vec in results.vectors:
    print(f"Key: {vec.key}, Distance: {vec.distance}")

Get Vectors by Keys

result = client.get_vectors(
    vector_bucket_name=bucket_name,
    account_id=account_id,
    index_name=index_name,
    keys=['vec-1', 'vec-2'],
    return_data=True,
    return_metadata=True
)

Delete Vectors

client.delete_vectors(
    vector_bucket_name=bucket_name,
    account_id=account_id,
    index_name=index_name,
    keys=['vec-1', 'vec-2']
)

Common Use Cases

1. Semantic Search

Build a semantic search system for documents:

# Index documents
for doc in documents:
    embedding = get_embedding(doc.text)  # Your embedding model
    vector = tos.models2.Vector(
        key=doc.id,
        data=tos.models2.VectorData(float32=embedding),
        metadata={'title': doc.title, 'content': doc.text[:500]}
    )
    vectors.append(vector)

client.put_vectors(
    vector_bucket_name=bucket_name,
    account_id=account_id,
    index_name=index_name,
    vectors=vectors
)

# Search
query_embedding = get_embedding(user_query)
results = client.query_vectors(
    vector_bucket_name=bucket_name,
    account_id=account_id,
    index_name=index_name,
    query_vector=tos.models2.VectorData(float32=query_embedding),
    top_k=5,
    return_metadata=True
)

2. RAG (Retrieval Augmented Generation)

Retrieve relevant context for LLM prompts:

# Retrieve relevant documents
question_embedding = get_embedding(user_question)
search_results = client.query_vectors(
    vector_bucket_name=bucket_name,
    account_id=account_id,
    index_name='knowledge-base',
    query_vector=tos.models2.VectorData(float32=question_embedding),
    top_k=3,
    return_metadata=True
)

# Build context
context = "\n\n".join([
    v.metadata.get('content', '') for v in search_results.vectors
])

# Generate answer with LLM
prompt = f"Context:\n{context}\n\nQuestion: {user_question}"

3. Recommendation System

Find similar items based on user preferences:

# Query with metadata filtering
results = client.query_vectors(
    vector_bucket_name=bucket_name,
    account_id=account_id,
    index_name='products',
    query_vector=user_preference_vector,
    top_k=10,
    filter={"$and": [{"category": "electronics"}, {"price_range": "mid"}]},
    return_metadata=True
)

Best Practices

Naming Conventions

• Bucket names: 3-32 chars, lowercase letters, numbers, hyphens only
• Index names: 3-63 chars
• Vector keys: 1-1024 chars, use meaningful identifiers

Batch Operations

• Insert up to 500 vectors per call
• Delete up to 100 vectors per call
• Use pagination for listing operations

Error Handling

try:
    result = client.create_vector_bucket(bucket_name)
except tos.exceptions.TosClientError as e:
    print(f'Client error: {e.message}')
except tos.exceptions.TosServerError as e:
    print(f'Server error: {e.code}, Request ID: {e.request_id}')

Performance Tips

• Choose appropriate vector dimensions (balance accuracy vs performance)
• Use metadata filtering to reduce search space
• Use cosine similarity for normalized vectors
• Use Euclidean distance for absolute distances

Important Limits

• Vector buckets: Max 100 per account
• Vector dimensions: 1-4096
• Batch insert: 1-500 vectors per call
• Batch get/delete: 1-100 vectors per call
• Query TopK: 1-30 results

Additional Resources

For detailed API reference, see REFERENCE.md For complete workflows, see WORKFLOWS.md For example scripts, see the scripts/ directory

TOS Vectors Agent Skill

A comprehensive Claude Agent Skill for managing vector storage and similarity search using TOS Vectors service.

Overview

This skill enables Claude to work with TOS Vectors - a cloud-based vector database optimized for AI applications including semantic search, RAG systems, and recommendation engines.

Skill Structure

tos-vectors-skill/
├── SKILL.md              # Main skill file with quick start and core operations
├── REFERENCE.md          # Complete API reference
├── WORKFLOWS.md          # Common workflow patterns
├── scripts/              # Utility scripts
│   ├── init_vectors.py   # Initialize bucket and index
│   ├── insert_vectors.py # Insert sample vectors
│   └── search_vectors.py # Search vectors
└── examples/             # Additional examples

Quick Start

1. Set Environment Variables

export TOS_ACCESS_KEY="your-access-key"
export TOS_SECRET_KEY="your-secret-key"
export TOS_ACCOUNT_ID="your-account-id"

2. Initialize Environment

python scripts/init_vectors.py

3. Insert Sample Data

python scripts/insert_vectors.py

4. Search Vectors

python scripts/search_vectors.py "machine learning"

Core Capabilities

• Vector Bucket Management: Create, list, delete vector buckets
• Vector Index Management: Create indexes with custom dimensions and metrics
• Vector Operations: Insert, query, get, delete, and list vectors
• Similarity Search: KNN search with metadata filtering
• Batch Operations: Efficient batch insert/delete (up to 500/100 vectors)
• Policy Management: IAM policy configuration

Common Use Cases

1. Semantic Search: Build document search systems
2. RAG Systems: Retrieval augmented generation for LLMs
3. Recommendations: Product/content recommendation engines
4. Image Search: Visual similarity search

Documentation

• SKILL.md: Quick reference and common operations
• REFERENCE.md: Complete API documentation
• WORKFLOWS.md: Step-by-step workflow examples

Requirements

• Python 3.7+
• tos Python SDK
• TOS Vectors account credentials

Installation

pip install tos

• important: TOS vectors in Beta, please install tos=2.8.8b1

Configuration

Endpoints

• Internal: https://tosvectors-cn-beijing.ivolces.com
• External: https://tosvectors-cn-beijing.volces.com

Regions

• cn-beijing (Beijing)
• cn-shanghai (Shanghai)
• cn-guangzhou (Guangzhou)

Limits

• Max vector buckets: 100 per account
• Vector dimensions: 1-4096
• Batch insert: 1-500 vectors
• Batch get/delete: 1-100 vectors
• Query TopK: 1-30 results

Support

For issues or questions, refer to the TOS Vectors documentation or contact support.