praval.storage.providers

Built-in storage providers for Praval framework

This module contains ready-to-use storage provider implementations for common backends like PostgreSQL, Redis, S3, and file systems.

class praval.storage.providers.PostgreSQLProvider(name, config)

Bases: BaseStorageProvider

PostgreSQL storage provider with async connection pooling.

Features: - Async connection pooling - SQL query execution - Transaction support - Schema management - JSON column support - Full-text search capabilities

Parameters:

• name (str)

• config (Dict[str, Any])

async connect()

Establish connection pool to PostgreSQL.

Return type:

bool

async delete(resource, **kwargs)

Delete data from PostgreSQL table.

Parameters:

• resource (str) – Table name

• **kwargs – Delete parameters (where clause required)

Return type:

StorageResult

Returns:

StorageResult with operation outcome

async disconnect()

Close connection pool.

async list_resources(prefix='', **kwargs)

List tables in the database.

Return type:

StorageResult

Parameters:

prefix (str)

async query(resource, query, **kwargs)

Execute SQL query against PostgreSQL.

Parameters:

• resource (str) – Table name (ignored for raw SQL)

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

• **kwargs – Query parameters

Return type:

StorageResult

Returns:

StorageResult with query results

async retrieve(resource, **kwargs)

Retrieve data from PostgreSQL table.

Parameters:

• resource (str) – Table name

• **kwargs – Query parameters (where, limit, offset, order_by, etc.)

Return type:

StorageResult

Returns:

StorageResult with retrieved data

async store(resource, data, **kwargs)

Store data in PostgreSQL table.

Parameters:

• resource (str) – Table name

• data (Any) – Data to store (dict or list of dicts)

• **kwargs – Additional parameters (upsert, returning, etc.)

Return type:

StorageResult

Returns:

StorageResult with operation outcome

class praval.storage.providers.RedisProvider(name, config)

Bases: BaseStorageProvider

Redis key-value storage provider with async support.

Features: - Key-value operations (GET, SET, DEL) - Hash operations (HGET, HSET, HGETALL) - List operations (LPUSH, RPUSH, LRANGE) - Set operations (SADD, SMEMBERS) - Expiration and TTL management - Pub/Sub messaging - Lua script execution

Parameters:

• name (str)

• config (Dict[str, Any])

async connect()

Establish connection to Redis.

Return type:

bool

async delete(resource, **kwargs)

Delete keys from Redis.

Parameters:

• resource (str) – Key or pattern to delete

• **kwargs – Delete parameters

Return type:

StorageResult

Returns:

StorageResult with operation outcome

async disconnect()

Close Redis connection.

async list_resources(prefix='', **kwargs)

List keys in Redis.

Return type:

StorageResult

Parameters:

prefix (str)

async query(resource, query, **kwargs)

Execute Redis operations or search queries.

Parameters:

• resource (str) – Pattern or specific key

• query (Union[str, Dict]) – Query type or Redis command

• **kwargs – Query parameters

Return type:

StorageResult

Returns:

StorageResult with query results

async retrieve(resource, **kwargs)

Retrieve data from Redis.

Parameters:

• resource (str) – Redis key

• **kwargs – Additional parameters (decode_json, etc.)

Return type:

StorageResult

Returns:

StorageResult with retrieved data

async store(resource, data, **kwargs)

Store data in Redis.

Parameters:

• resource (str) – Redis key

• data (Any) – Data to store (will be JSON serialized if not string)

• **kwargs – Redis parameters (ex, px, nx, xx, etc.)

Return type:

StorageResult

Returns:

StorageResult with operation outcome

class praval.storage.providers.S3Provider(name, config)

Bases: BaseStorageProvider

S3-compatible object storage provider.

Features: - Object upload, download, and deletion - Bucket management - Presigned URLs for secure access - Metadata and tagging support - Multipart uploads for large files - Lifecycle management - Cross-region replication support

Parameters:

• name (str)

• config (Dict[str, Any])

async connect()

Establish connection to S3.

Return type:

bool

async delete(resource, **kwargs)

Delete object(s) from S3.

Parameters:

• resource (str) – Object key or prefix

• **kwargs – Delete parameters (recursive, etc.)

Return type:

StorageResult

Returns:

StorageResult with operation outcome

async disconnect()

Close S3 connection.

async list_resources(prefix='', **kwargs)

List objects in S3 bucket.

Return type:

StorageResult

Parameters:

prefix (str)

async query(resource, query, **kwargs)

Execute S3 operations or list objects.

Parameters:

• resource (str) – Prefix or specific key

• query (Union[str, Dict]) – Query type (“list”, “search”, “metadata”, etc.)

• **kwargs – Query parameters

Return type:

StorageResult

Returns:

StorageResult with query results

async retrieve(resource, **kwargs)

Retrieve object from S3.

Parameters:

• resource (str) – S3 object key

• **kwargs – Retrieval parameters (range, decode_json, etc.)

Return type:

StorageResult

Returns:

StorageResult with retrieved data

async store(resource, data, **kwargs)

Store object in S3.

Parameters:

• resource (str) – S3 object key

• data (Any) – Data to store (bytes, string, file-like object, or dict/list for JSON)

• **kwargs – S3 parameters (content_type, metadata, acl, etc.)

Return type:

StorageResult

Returns:

StorageResult with operation outcome

class praval.storage.providers.FileSystemProvider(name, config)

Bases: BaseStorageProvider

Local file system storage provider.

Features: - File and directory operations - Path management and validation - File metadata and permissions - Recursive operations - Pattern-based file listing - Atomic file operations

Parameters:

• name (str)

• config (Dict[str, Any])

async connect()

Verify file system access.

Return type:

bool

async delete(resource, **kwargs)

Delete file or directory from file system.

Parameters:

• resource (str) – Path to delete

• **kwargs – Delete parameters (recursive, etc.)

Return type:

StorageResult

Returns:

StorageResult with operation outcome

async disconnect()

No explicit disconnection needed for file system.

async list_resources(prefix='', **kwargs)

List files and directories.

Return type:

StorageResult

Parameters:

prefix (str)

async query(resource, query, **kwargs)

Execute file system operations.

Parameters:

• resource (str) – Path or pattern

• query (Union[str, Dict]) – Query type (“list”, “find”, “metadata”, etc.)

• **kwargs – Query parameters

Return type:

StorageResult

Returns:

StorageResult with query results

async retrieve(resource, **kwargs)

Retrieve data from file system.

Parameters:

• resource (str) – File path relative to base_path

• **kwargs – Read parameters (encoding, decode_json, etc.)

Return type:

StorageResult

Returns:

StorageResult with retrieved data

async store(resource, data, **kwargs)

Store data to file system.

Parameters:

• resource (str) – File path relative to base_path

• data (Any) – Data to store (string, bytes, dict/list for JSON, or file-like object)

• **kwargs – File parameters (encoding, mode, etc.)

Return type:

StorageResult

Returns:

StorageResult with operation outcome

class praval.storage.providers.QdrantProvider(name, config)

Bases: BaseStorageProvider

Qdrant vector database storage provider.

Features: - Vector similarity search - Collection management - Point insertion and retrieval - Filtering and metadata search - Batch operations - Integration with Praval memory system

Parameters:

• name (str)

• config (Dict[str, Any])

async connect()

Establish connection to Qdrant.

Return type:

bool

async delete(resource, **kwargs)

Delete points from Qdrant.

Parameters:

• resource (str) – Collection name or “collection:point_id”

• **kwargs – Delete parameters (point_ids, filter)

Return type:

StorageResult

Returns:

StorageResult with operation outcome

async disconnect()

Close Qdrant connection.

async list_resources(prefix='', **kwargs)

List collections in Qdrant.

Return type:

StorageResult

Parameters:

prefix (str)

async query(resource, query, **kwargs)

Execute vector search or other operations.

Parameters:

• resource (str) – Collection name

• query (Union[str, Dict]) – Query type or search vector

• **kwargs – Query parameters

Return type:

StorageResult

Returns:

StorageResult with query results

async retrieve(resource, **kwargs)

Retrieve vectors from Qdrant.

Parameters:

• resource (str) – Collection name or “collection:point_id”

• **kwargs – Retrieval parameters (point_ids, with_vectors, with_payload)

Return type:

StorageResult

Returns:

StorageResult with retrieved data

async store(resource, data, **kwargs)

Store vector data in Qdrant.

Parameters:

• resource (str) – Collection name (optional, uses default if not specified)

• data (Any) – Data to store - can be: - Single point: {“id”: “…”, “vector”: […], “payload”: {…}} - Multiple points: [{“id”: “…”, “vector”: […], “payload”: {…}}, …] - Just vector: [0.1, 0.2, …] (will generate ID)

• **kwargs – Additional parameters

Return type:

StorageResult

Returns:

StorageResult with operation outcome

Modules

filesystem	File system storage provider for Praval framework
postgresql	PostgreSQL storage provider for Praval framework
qdrant_provider	Qdrant vector storage provider for Praval framework
redis_provider	Redis storage provider for Praval framework
s3_provider	S3 object storage provider for Praval framework