Aliyun Tablestore Agent Storage Python SDK
A Python SDK for agent storage with support for Aliyun OSS and OTS, featuring:
- knowledge base management
- document management
- chunk-level listing and update
- retrieval with metadata filters
Installation
pip install tablestore-agent-storage
or install from source:
pip install -e .
Quick Start
from tablestore_agent_storage import (
AgentStorageClient,
UpdateKnowledgeBaseRequest,
UpdateDocumentRequest,
ListChunksRequest,
UpdateChunkItem,
UpdateChunksRequest,
)
# 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({
'knowledgeBaseName': 'my_knowledge_base',
'description': 'My first knowledge base'
})
# Update knowledge base
client.update_knowledge_base(
UpdateKnowledgeBaseRequest(
knowledge_base_name="my_knowledge_base",
description="Updated description",
tags=["production", "v2"]
)
)
# 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'}
}]
})
# Update document metadata
client.update_document(
UpdateDocumentRequest(
knowledge_base_name="my_knowledge_base",
doc_id="doc_123",
metadata={"author": "new_author"}
)
)
# List chunks
chunk_list = client.list_chunks(
ListChunksRequest(
knowledge_base_name="my_knowledge_base",
doc_id="doc_123",
max_results=10
)
)
# Update chunks
client.update_chunks(
UpdateChunksRequest(
knowledge_base_name="my_knowledge_base",
chunks=[
UpdateChunkItem(chunk_id=1, doc_id="doc_123", title="new title"),
UpdateChunkItem(chunk_id=2, doc_id="doc_123", content="new content"),
],
)
)
# 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 baselist_knowledge_base(request)- List all knowledge basesdescribe_knowledge_base(request)- Get knowledge base detailsupdate_knowledge_base(request)- Update knowledge base description/tags/retrieval configdelete_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)update_document(request)- Update document metadata bydocIdorossKeylist_documents(request)- List documents in knowledge baseget_document(request)- Get document detailsdelete_documents(request)- Delete documents
Chunk Operations
list_chunks(request)- List chunks bydocId/ossKeywith pagination supportupdate_chunks(request)- Batch update chunk title/content/status
Retrieval Operations
retrieve(request)- Perform vector search/retrieval
Item Operations (file-memory stores)
Memory stores in filemem mode (and the read-only file+ots projection)
expose file items through the item APIs. Every request carries
"type": "memoryfile"; the SDK fills it automatically when omitted
(constant ITEM_TYPE_MEMORY_FILE).
add_item(request)- Create an item (path,content, optionalsessionId)list_items(request)- List items without content (pathPrefix,nextToken,limit)get_item(request)- Get one item; passincludeContent=Falsefor metadata only (defaults to true)update_item(request)- Rewrite content or rename; set exactly one ofcontent/newPath(overwrite,expectedSha256,sessionIdoptional)delete_item(request)- Delete an item (path, optionalexpectedSha256,sessionId)list_item_versions(request)- List immutable versions (itemId, optionaloperationfilter)get_item_version(request)- Get one version with content (itemId,versionId,versionSeq)redact_item_version(request)- Irreversibly clear a version's content/sha/size/path; idempotent
Update Request Semantics
UpdateKnowledgeBaseRequest, UpdateDocumentRequest, and UpdateChunkItem use an internal UNSET sentinel:
- field not provided: keep current value unchanged
- field explicitly set to
None: clear this field on server side
This makes partial update behavior explicit and predictable.
Configuration
The SDK supports API Key authentication or signed AK/STS requests. All Agent Storage requests are implemented inside this package and do not depend on the general Tablestore Python SDK exposing matching methods.
Core 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)sts_token: Optional STS security tokenapi_key: API Key for OTS requests; requires an HTTPS endpointoss_endpoint: OSS service endpointoss_bucket_name: OSS bucket nameots_endpoint: OTS service endpointots_instance_name: OTS instance name
Additional keyword options remain available:
credentials_provider: Refreshing provider with aget_credentials()methodregion: Enables SignV4 for the specified region; SignV2 is the defaultsign_version: Explicitly selectv2orv4socket_timeout: Per-request timeout in secondsmax_connection: HTTP connection-pool sizessl_version: Minimum TLS versionextra_headers: Headers attached to every OTS requestretry_policy: Object implementingshould_retry()andget_retry_delay()
Examples
See the examples/ directory for more detailed usage examples.
Dependencies
- Python >= 3.8
- oss2 >= 2.18.0
- urllib3 >= 1.26, < 3
Contact
Metadata
Release files for tablestore-agent-storage 1.0.10
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tablestore_agent_storage-1.0.10.tar.gz | 35.8 kB | Without provenance | Details for tablestore_agent_storage-1.0.10.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tablestore_agent_storage-1.0.10-py3-none-any.whl | Python 3 | none | any | Details for tablestore_agent_storage-1.0.10-py3-none-any.whl |
Total release size: 65.1 kB
Release files / tablestore_agent_storage-1.0.10.tar.gz
| Download URL | tablestore_agent_storage-1.0.10.tar.gz |
|---|---|
| Size | 35.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8b62b228684e6df6b01b62d1a9f5a232c38e84905fc980593e8dcecbecd75a64
|
|
BLAKE2b-256 checksum How to use checksums |
94a4ca5e809d54d5fb22a4f9c48827ecaf9a47c0e72f98388ec156086a5d5a4a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.2.1 CPython/3.9.19 Linux/5.10.134-010.ali5000.al8.x86_64
|
Release files / tablestore_agent_storage-1.0.10-py3-none-any.whl
| Download URL | tablestore_agent_storage-1.0.10-py3-none-any.whl |
|---|---|
| Size | 29.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
caab63c42a63e90dd4bbb34310cdb3d7596771989536ba00c24cc60de43663e5
|
|
BLAKE2b-256 checksum How to use checksums |
0915ba30a0624c758c518bab4abbef37eb613dc04a755fa2d5995b6d06bbf48b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.2.1 CPython/3.9.19 Linux/5.10.134-010.ali5000.al8.x86_64
|
Security for tablestore-agent-storage 1.0.10
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.