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)

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)

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: Optional[datetime] = None

to_uri()

Convert to URI format for spore communication

Return type:

str

classmethod from_uri(uri)

Create DataReference from URI

Return type:

DataReference

Parameters:

uri (str)

is_expired()

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)

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: Optional[int] = None

offset: Optional[int] = None

timeout: Optional[float] = 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>)

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: Optional[str] = None

execution_time: float = 0.0

metadata: Dict[str, Any]

data_reference: Optional[DataReference] = 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)

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_search: 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: Optional[str] = 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)

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)

Initialize the storage provider.

Parameters:

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

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

abstractmethod async connect()

Establish connection to the storage backend.

Return type:

bool

Returns:

True if connection successful, False otherwise

abstractmethod async disconnect()

Close connection to the storage backend.

abstractmethod async store(resource, data, **kwargs)

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)

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)

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)

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)

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)

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)

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()

Get provider schema/capabilities.

Return type:

Dict[str, Any]

async health_check()

Perform health check on the storage backend.

Return type:

Dict[str, Any]

praval.storage.base_provider.create_storage_provider(provider_class, name, config)

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