Python SDK Reference

Complete API documentation for avp-sdk

Installation

# Basic installation
pip install avp-sdk

# With OS keychain support
pip install avp-sdk[keychain]

# Development with all features
pip install avp-sdk[all]

Quick Example

from avp import AVPClient
from avp.backends import FileBackend, KeychainBackend

# File backend (encrypted storage)
backend = FileBackend("~/.avp/vault.enc", "password")

# Or use OS keychain (macOS/Linux/Windows)
# backend = KeychainBackend()

client = AVPClient(backend)
session = client.authenticate(workspace="my-agent")

# Store, retrieve, list, delete
client.store(session.session_id, "api_key", b"secret-value")
result = client.retrieve(session.session_id, "api_key")
print(result.value.decode())  # "secret-value"

AVPClient

Main client for interacting with AVP backends.

AVPClient(backend: BackendBase)

Create a new AVP client with the specified backend.

Methods

discover() → DiscoverResponse

Discover vault capabilities, backends, and limits.

info = client.discover()
print(f"Version: {info.version}")
print(f"Backends: {[b.id for b in info.backends]}")

authenticate(workspace: str, ttl_seconds: int = 3600) → Session

Authenticate and create a session for a workspace.

session = client.authenticate(workspace="production", ttl_seconds=7200)
print(f"Session ID: {session.session_id}")

store(session_id: str, name: str, value: bytes, labels: dict = None) → StoreResponse

Store a credential in the vault.

result = client.store(
    session.session_id,
    "openai_api_key",
    b"sk-...",
    labels={"env": "production", "service": "chat"}
)
print(f"Created: {result.created}, Version: {result.version}")

retrieve(session_id: str, name: str) → RetrieveResponse

Retrieve a credential from the vault.

result = client.retrieve(session.session_id, "openai_api_key")
api_key = result.value.decode()
print(f"Version: {result.version}")

delete(session_id: str, name: str) → DeleteResponse

Delete a credential from the vault.

result = client.delete(session.session_id, "old_api_key")
print(f"Deleted: {result.deleted}")

list_secrets(session_id: str, filter_labels: dict = None) → ListResponse

List all credentials in the workspace.

# List all
result = client.list_secrets(session.session_id)
for secret in result.secrets:
    print(f"  {secret.name}: v{secret.metadata.version}")

# Filter by labels
prod_secrets = client.list_secrets(
    session.session_id,
    filter_labels={"env": "production"}
)

rotate(session_id: str, name: str, new_value: bytes) → RotateResponse

Rotate a credential with version tracking.

result = client.rotate(session.session_id, "api_key", b"new-secret")
print(f"New version: {result.version}")

Backends

MemoryBackend

In-memory storage for testing. Testing Only

from avp.backends import MemoryBackend
backend = MemoryBackend()

FileBackend

Encrypted file storage using Fernet (AES-128-CBC + HMAC).

from avp.backends import FileBackend
backend = FileBackend(
    path="~/.avp/vault.enc",
    password="your-secure-password"
)

KeychainBackend

OS-native credential storage (requires pip install avp-sdk[keychain]).

from avp.backends import KeychainBackend
backend = KeychainBackend()  # Uses macOS Keychain, Windows Cred Manager, or SecretService

Error Handling

from avp.errors import SecretNotFoundError, SessionExpiredError

try:
    result = client.retrieve(session.session_id, "missing_key")
except SecretNotFoundError:
    print("Credential not found")
except SessionExpiredError:
    # Re-authenticate
    session = client.authenticate(workspace="my-agent")

Context Manager

# Automatic cleanup
with AVPClient(backend) as client:
    session = client.authenticate(workspace="temp")
    client.store(session.session_id, "key", b"value")
# Backend closed automatically