Metadata-Version: 2.4
Name: tablestore-agent-storage
Version: 1.0.1
Summary: A Python SDK for agent storage
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: oss2>=2.18.0
Requires-Dist: tablestore>=6.3.9
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"

# Aliyun Tablestore Agent Storage Python SDK

A Python SDK for agent storage with support for Aliyun OSS and OTS, featuring knowledge base and document management capabilities.

## Installation

```bash
pip install -e .
```

## Quick Start

```python
from tablestore_agent_storage import AgentStorageClient

# Initialize client with unified credentials
client = AgentStorageClient(
    access_key_id='your_access_key_id',
    access_key_secret='your_access_key_secret',
    oss_endpoint='https://oss-cn-hangzhou.aliyuncs.com',
    oss_bucket_name='your_bucket_name',
    ots_endpoint='https://your_instance.cn-hangzhou.ots.aliyuncs.com',
    ots_instance_name='your_instance_name'
)

# Create a knowledge base
response = client.create_knowledge_base({
    'name': 'my_knowledge_base',
    'description': 'My first knowledge base'
})

# Add a document with OSS key
client.add_documents({
    'knowledgeBaseName': 'my_knowledge_base',
    'documents': [{
        'ossKey': 'oss://your-bucket/path/to/file.pdf',
        'metadata': {'author': 'aliyun'}
    }]
})

# Or add a document by uploading a local file
client.upload_documents({
    'knowledgeBaseName': 'my_knowledge_base',
    'documents': [{
        'filePath': '/path/to/local/file.pdf',
        'metadata': {'author': 'aliyun'}
    }]
})

# Search/Retrieve
results = client.retrieve({
    'knowledgeBaseName': 'knowledgeBaseName',
    "retrievalQuery": {
        "text": "text to search",
        "type": "TEXT"
    }
})
```

## API Reference

### Knowledge Base Operations

- `create_knowledge_base(request)` - Create new knowledge base
- `list_knowledge_base(request)` - List all knowledge bases
- `describe_knowledge_base(request)` - Get knowledge base details
- `delete_knowledge_base(request)` - Delete knowledge base

### Document Operations

- `add_documents(request)` - Add a document to a knowledge base (requires OSS key)
- `upload_documents(request)` - Add a document by uploading a local file (automatically uploads to OSS)
- `list_documents(request)` - List documents in knowledge base
- `get_document(request)` - Get document details
- `delete_documents(request)` - Delete a document

### Retrieval Operations

- `retrieve(request)` - Perform vector search/retrieval

## Configuration

The SDK requires the following configuration parameters:

- `access_key_id`: Your Aliyun access key ID (shared by OSS and OTS)
- `access_key_secret`: Your Aliyun access key secret (shared by OSS and OTS)
- `oss_endpoint`: OSS service endpoint
- `oss_bucket_name`: OSS bucket name
- `ots_endpoint`: OTS service endpoint (optional)
- `ots_instance_name`: OTS instance name (optional)

## Examples

See the `examples/` directory for more detailed usage examples.

## Dependencies

- oss2 >= 2.18.0
- tablestore >=6.3.9

# Contact

- [阿里云 Tablestore 官方网站](http://www.aliyun.com/product/ots)
- [阿里云官网联系方式](https://help.aliyun.com/document_detail/61890.html)
- [阿里云 Tablestore 官方文档](https://help.aliyun.com/zh/tablestore/product-overview)
