praval.storage.base_provider

Base Storage Provider Framework

Defines the core interfaces and base classes for all Praval storage providers. This provides a standardized way to create, register, and use storage backends that agents can access uniformly.

Functions

create_storage_provider(provider_class, ...)

Create a storage provider instance.

Classes

BaseStorageProvider(name, config)

Abstract base class for all storage providers.

DataReference(provider, storage_type, ...[, ...])

Reference to data stored in a backend

StorageMetadata(name, description, storage_type)

Metadata describing a storage provider's capabilities

StorageQuery(operation, resource[, ...])

Query parameters for storage operations

StorageResult(success[, data, error, ...])

Result from storage operation

StorageType(*values)

Types of storage backends
class praval.storage.base_provider.StorageType(*values)[source]

Bases: Enum

Types of storage backends

RELATIONAL = 'relational'
DOCUMENT = 'document'
KEY_VALUE = 'key_value'
OBJECT = 'object'
VECTOR = 'vector'
SEARCH = 'search'
GRAPH = 'graph'
FILE_SYSTEM = 'file_system'
CACHE = 'cache'
QUEUE = 'queue'
class praval.storage.base_provider.DataReference(provider, storage_type, resource_id, metadata=<factory>, created_at=<factory>, expires_at=None)[source]

Bases: object

Reference to data stored in a backend

Parameters:

  • provider (str)

  • storage_type (StorageType)

  • resource_id (str)

  • metadata (Dict[str, Any])

  • created_at (datetime)

  • expires_at (datetime | None)

provider: str
storage_type: StorageType
resource_id: str
metadata: Dict[str, Any]
created_at: datetime
expires_at: datetime | None = None
to_uri()[source]

Convert to URI format for spore communication

Return type:

str

classmethod from_uri(uri)[source]

Create DataReference from URI

Return type:

DataReference

Parameters:

uri (str)

is_expired()[source]

Check if reference has expired

Return type:

bool

__init__(provider, storage_type, resource_id, metadata=<factory>, created_at=<factory>, expires_at=None)
Parameters:

  • provider (str)

  • storage_type (StorageType)

  • resource_id (str)

  • metadata (Dict[str, Any])

  • created_at (datetime)

  • expires_at (datetime | None)

Return type:

None

class praval.storage.base_provider.StorageQuery(operation, resource, parameters=<factory>, filters=<factory>, limit=None, offset=None, timeout=None)[source]

Bases: object

Query parameters for storage operations

Parameters:

  • operation (str)

  • resource (str)

  • parameters (Dict[str, Any])

  • filters (Dict[str, Any])

  • limit (int | None)

  • offset (int | None)

  • timeout (float | None)

operation: str
resource: str
parameters: Dict[str, Any]
filters: Dict[str, Any]
limit: int | None = None
offset: int | None = None
timeout: float | None = None
__init__(operation, resource, parameters=<factory>, filters=<factory>, limit=None, offset=None, timeout=None)
Parameters:

  • operation (str)

  • resource (str)

  • parameters (Dict[str, Any])

  • filters (Dict[str, Any])

  • limit (int | None)

  • offset (int | None)

  • timeout (float | None)

Return type:

None

class praval.storage.base_provider.StorageResult(success, data=None, error=None, execution_time=0.0, metadata=<factory>, data_reference=None, timestamp=<factory>)[source]

Bases: object

Result from storage operation

Parameters:

  • success (bool)

  • data (Any)

  • error (str | None)

  • execution_time (float)

  • metadata (Dict[str, Any])

  • data_reference (DataReference | None)

  • timestamp (datetime)

success: bool
data: Any = None
error: str | None = None
execution_time: float = 0.0
metadata: Dict[str, Any]
data_reference: DataReference | None = None
timestamp: datetime
__init__(success, data=None, error=None, execution_time=0.0, metadata=<factory>, data_reference=None, timestamp=<factory>)
Parameters:

  • success (bool)

  • data (Any)

  • error (str | None)

  • execution_time (float)

  • metadata (Dict[str, Any])

  • data_reference (DataReference | None)

  • timestamp (datetime)

Return type:

None

class praval.storage.base_provider.StorageMetadata(name, description, storage_type, version='1.0.0', supports_async=True, supports_transactions=False, supports_schemas=False, supports_indexing=False, supports_search=False, supports_streaming=False, max_connection_pool=10, default_timeout=30.0, required_config=<factory>, optional_config=<factory>, connection_string_template=None)[source]

Bases: object

Metadata describing a storage provider’s capabilities

Parameters:

  • name (str)

  • description (str)

  • storage_type (StorageType)

  • version (str)

  • supports_async (bool)

  • supports_transactions (bool)

  • supports_schemas (bool)

  • supports_indexing (bool)

  • supports_search (bool)

  • supports_streaming (bool)

  • max_connection_pool (int)

  • default_timeout (float)

  • required_config (List[str])

  • optional_config (List[str])

  • connection_string_template (str | None)

name: str
description: str
storage_type: StorageType
version: str = '1.0.0'
supports_async: bool = True
supports_transactions: bool = False
supports_schemas: bool = False
supports_indexing: bool = False
supports_streaming: bool = False
max_connection_pool: int = 10
default_timeout: float = 30.0
required_config: List[str]
optional_config: List[str]
connection_string_template: str | None = None
__init__(name, description, storage_type, version='1.0.0', supports_async=True, supports_transactions=False, supports_schemas=False, supports_indexing=False, supports_search=False, supports_streaming=False, max_connection_pool=10, default_timeout=30.0, required_config=<factory>, optional_config=<factory>, connection_string_template=None)
Parameters:

  • name (str)

  • description (str)

  • storage_type (StorageType)

  • version (str)

  • supports_async (bool)

  • supports_transactions (bool)

  • supports_schemas (bool)

  • supports_indexing (bool)

  • supports_search (bool)

  • supports_streaming (bool)

  • max_connection_pool (int)

  • default_timeout (float)

  • required_config (List[str])

  • optional_config (List[str])

  • connection_string_template (str | None)

Return type:

None

class praval.storage.base_provider.BaseStorageProvider(name, config)[source]

Bases: ABC

Abstract base class for all storage providers.

All storage backends must inherit from this class and implement the required methods. This ensures a consistent interface across all storage types while allowing for provider-specific optimizations.

Parameters:

  • name (str)

  • config (Dict[str, Any])

__init__(name, config)[source]

Initialize the storage provider.

Parameters:

  • name (str) – Unique name for this provider instance

  • config (Dict[str, Any]) – Provider-specific configuration

abstractmethod async connect()[source]

Establish connection to the storage backend.

Return type:

bool

Returns:

True if connection successful, False otherwise

abstractmethod async disconnect()[source]

Close connection to the storage backend.

abstractmethod async store(resource, data, **kwargs)[source]

Store data in the backend.

Parameters:

  • resource (str) – Resource identifier (table, bucket, key, etc.)

  • data (Any) – Data to store

  • **kwargs – Provider-specific parameters

Return type:

StorageResult

Returns:

StorageResult with operation outcome

abstractmethod async retrieve(resource, **kwargs)[source]

Retrieve data from the backend.

Parameters:

  • resource (str) – Resource identifier

  • **kwargs – Provider-specific parameters

Return type:

StorageResult

Returns:

StorageResult with retrieved data

abstractmethod async query(resource, query, **kwargs)[source]

Execute a query against the backend.

Parameters:

  • resource (str) – Resource to query

  • query (Union[str, Dict]) – Query string or structured query

  • **kwargs – Provider-specific parameters

Return type:

StorageResult

Returns:

StorageResult with query results

abstractmethod async delete(resource, **kwargs)[source]

Delete data from the backend.

Parameters:

  • resource (str) – Resource to delete

  • **kwargs – Provider-specific parameters

Return type:

StorageResult

Returns:

StorageResult with operation outcome

async exists(resource, **kwargs)[source]

Check if a resource exists.

Parameters:

  • resource (str) – Resource to check

  • **kwargs – Provider-specific parameters

Return type:

bool

Returns:

True if resource exists, False otherwise

async list_resources(prefix='', **kwargs)[source]

List available resources.

Parameters:

  • prefix (str) – Resource prefix to filter by

  • **kwargs – Provider-specific parameters

Return type:

StorageResult

Returns:

StorageResult with list of resources

async safe_execute(operation, *args, **kwargs)[source]

Execute operation with error handling and timing.

Parameters:

  • operation (str) – Operation name

  • args – Operation parameters

  • kwargs – Operation parameters

Return type:

StorageResult

Returns:

StorageResult with operation outcome

get_schema()[source]

Get provider schema/capabilities.

Return type:

Dict[str, Any]

async health_check()[source]

Perform health check on the storage backend.

Return type:

Dict[str, Any]

praval.storage.base_provider.create_storage_provider(provider_class, name, config)[source]

Create a storage provider instance.

Parameters:

  • provider_class (Type[BaseStorageProvider]) – Provider class to instantiate

  • name (str) – Provider instance name

  • config (Dict[str, Any]) – Provider configuration

Return type:

BaseStorageProvider

Returns:

Configured provider instance