entity.resources package

Public resource interfaces and canonical wrappers.

class entity.resources.DatabaseResource(infrastructure)[source]

Bases: object

Layer 2 resource providing database access.

Parameters:: infrastructure (DatabaseInfrastructure | None)

__init__(infrastructure)[source]

Initialize with an injected database infrastructure.

Parameters:: infrastructure (DatabaseInfrastructure | None)
Return type:: None

execute(query, *params)[source]

Execute a SQL query and return the result cursor.

Parameters:

query (str)
params (object)

Return type:

object

async health_check()[source]

Return True if the underlying infrastructure is healthy.

Return type:: bool

health_check_sync()[source]

Synchronous wrapper for health_check for compatibility.

Return type:: bool

class entity.resources.VectorStoreResource(infrastructure)[source]

Bases: object

Layer 2 resource for storing and searching vectors.

Parameters:: infrastructure (VectorStoreInfrastructure | None)

__init__(infrastructure)[source]

Create the resource with a vector store backend.

Parameters:: infrastructure (VectorStoreInfrastructure | None)
Return type:: None

add_vector(table, vector)[source]

Insert a vector into the given table.

Parameters:

table (str)
vector (object)

Return type:

None

async health_check()[source]

Return True if the underlying infrastructure is healthy.

Return type:: bool

health_check_sync()[source]

Synchronous wrapper for health_check for compatibility.

Return type:: bool

query(query)[source]

Run a vector search query.

Parameters:: query (str)
Return type:: object

class entity.resources.LLMResource(infrastructure)[source]

Bases: object

Layer 2 resource that wraps an LLM infrastructure.

Parameters:: infrastructure (LLMInfrastructure | None)

__init__(infrastructure)[source]

Initialize with the infrastructure instance.

Parameters:: infrastructure (LLMInfrastructure | None)
Return type:: None

async generate(prompt)[source]

Return the model output for a given prompt.

Parameters:: prompt (str)
Return type:: str

health_check()[source]

Return True if the underlying infrastructure is healthy.

Return type:: bool

health_check_sync()[source]

Synchronous wrapper for health_check for compatibility.

Return type:: bool

class entity.resources.StorageResource(infrastructure)[source]

Bases: object

Layer 2 resource for S3-based file storage.

Parameters:: infrastructure (StorageInfrastructure | None)

__init__(infrastructure)[source]

Initialize the resource with a storage infrastructure instance.

Parameters:: infrastructure (StorageInfrastructure | None)
Return type:: None

async health_check()[source]

Return True if the underlying infrastructure is healthy.

Return type:: bool

health_check_sync()[source]

Synchronous wrapper for health_check for compatibility.

Return type:: bool

async upload_text(key, data)[source]

Upload plain text to the configured storage under the given key.

Parameters:

key (str)
data (str)

Return type:

None

class entity.resources.LocalStorageResource(infrastructure)[source]

Bases: object

Layer 2 resource for local file storage.

Parameters:: infrastructure (StorageInfrastructure | None)

__init__(infrastructure)[source]

Create the resource with a storage backend.

Parameters:: infrastructure (StorageInfrastructure | None)
Return type:: None

async health_check()[source]

Return True if the underlying infrastructure is healthy.

Return type:: bool

health_check_sync()[source]

Synchronous wrapper for health_check for compatibility.

Return type:: bool

async upload_text(key, data)[source]

Persist text to the local filesystem.

Parameters:

key (str)
data (str)

Return type:

None

exception entity.resources.ResourceInitializationError[source]

Bases: ResourceError

Raised when a canonical resource is missing required dependencies.

class entity.resources.Memory(database, vector_store)[source]

Bases: object

Layer 3 canonical resource providing persistent memory capabilities.

Memory is one of the four canonical resources guaranteed to be available to every workflow. It provides both structured (database) and semantic (vector) storage with automatic user isolation and cross-process synchronization.

This class follows the 4-layer architecture: - Layer 3: Canonical Agent Resources (Memory) - Depends on Layer 2: Resource Interfaces (DatabaseResource, VectorStoreResource)

Parameters:

database (DatabaseResource | None)
vector_store (VectorStoreResource | None)

database: The underlying database resource for structured data.

vector_store: The underlying vector store for semantic search.

Examples

>>> from entity.resources import Memory, DatabaseResource, VectorStoreResource
>>> from entity.infrastructure import DuckDBInfrastructure
>>>
>>> duckdb = DuckDBInfrastructure("./agent_memory.duckdb")
>>> db_resource = DatabaseResource(duckdb)
>>> vector_resource = VectorStoreResource(duckdb)
>>> memory = Memory(db_resource, vector_resource)

__init__(database, vector_store)[source]

Initialize Memory with database and vector store resources.

Parameters:

database (DatabaseResource | None) – Database resource for structured data storage.
vector_store (VectorStoreResource | None) – Vector store resource for semantic search.

Raises:

ResourceInitializationError – If database or vector_store is None.

Return type:

None

add_vector(table, vector)[source]

Add a vector to the vector store.

Parameters:

table (str) – Name of the table/collection to store the vector in.
vector (object) – Vector data to store (typically embeddings).

Return type:

None

Examples

>>> memory.add_vector("embeddings", [0.1, 0.2, 0.3, ...])

execute(query, *params)[source]

Execute a raw database query.

Parameters:

query (str) – SQL query string to execute.
*params (object) – Parameters to bind to the query.

Returns:

Query result from the database.

Return type:

object

Examples

>>> result = memory.execute("SELECT * FROM conversations WHERE user_id = ?", "user123")

health_check()[source]

Check if both database and vector store are healthy.

Returns:: True if both underlying resources are operational, False otherwise.
Return type:: bool

health_check_sync()[source]

Synchronous wrapper for health_check.

Returns:: True if both underlying resources are operational, False otherwise.
Return type:: bool

async load(key, default=None)[source]

Retrieve the stored value for key or default if missing.

Parameters:

key (str)
default (Any | None)

Return type:

Any

query(query)[source]

Execute a vector store query.

Parameters:: query (str)
Return type:: object

async store(key, value)[source]

Persist value for key asynchronously.

Parameters:

key (str)
value (Any)

Return type:

None

class entity.resources.LLM(resource)[source]

Bases: object

Layer 3 wrapper around an LLM resource.

Parameters:: resource (LLMResource | None)

__init__(resource)[source]

Wrap the provided LLMResource.

Parameters:: resource (LLMResource | None)
Return type:: None

async generate(prompt)[source]

Generate a completion using the underlying resource.

Parameters:: prompt (str)
Return type:: str

health_check()[source]

Return True if the underlying resource is healthy.

Return type:: bool

health_check_sync()[source]

Synchronous wrapper for health_check for compatibility.

Return type:: bool

class entity.resources.FileStorage(resource)[source]

Bases: object

Layer 3 wrapper around a storage resource.

Parameters:: resource (StorageResource | LocalStorageResource | None)

__init__(resource)[source]

Wrap a local or S3 storage resource.

Parameters:: resource (StorageResource | LocalStorageResource | None)
Return type:: None

health_check()[source]

Return True if the underlying resource is healthy.

Return type:: bool

health_check_sync()[source]

Synchronous wrapper for health_check for compatibility.

Return type:: bool

async upload_text(key, data)[source]

Proxy text upload to the underlying resource.

Parameters:

key (str)
data (str)

Return type:

None

class entity.resources.RichLoggingResource(level=LogLevel.INFO, *, json=False, log_file=None, max_bytes=0, backup_count=0, show_context=True)[source]

Bases: LoggingResource

Convenience wrapper choosing between console and JSON logging.

Parameters:

level (LogLevel)
json (bool)
log_file (str | None)
max_bytes (int)
backup_count (int)
show_context (bool)

__init__(level=LogLevel.INFO, *, json=False, log_file=None, max_bytes=0, backup_count=0, show_context=True)[source]

Parameters:

level (LogLevel)
json (bool)
log_file (str | None)
max_bytes (int)
backup_count (int)
show_context (bool)

Return type:

None

health_check()[source]

Return type:: bool

async log(level, category, message, context=None, **extra_fields)[source]

Log structured entry with automatic context injection.

Parameters:

level (LogLevel)
category (LogCategory)
message (str)
context (LogContext | None)
extra_fields (Any)

Return type:

None

class entity.resources.RichConsoleLoggingResource(level=LogLevel.INFO, show_context=True)[source]

Bases: LoggingResource

Colored, formatted console logging using Rich.

Parameters:

level (LogLevel)
show_context (bool)

__init__(level=LogLevel.INFO, show_context=True)[source]

Parameters:

level (LogLevel)
show_context (bool)

Return type:

None

async log(level, category, message, context=None, **extra_fields)[source]

Log structured entry with automatic context injection.

Parameters:

level (LogLevel)
category (LogCategory)
message (str)
context (LogContext | None)
extra_fields (Any)

Return type:

None

class entity.resources.RichJSONLoggingResource(level=LogLevel.INFO, output_file=None, max_bytes=0, backup_count=0)[source]

Bases: LoggingResource

Structured JSON logging with optional Rich console output.

Parameters:

level (LogLevel)
output_file (str | None)
max_bytes (int)
backup_count (int)

__init__(level=LogLevel.INFO, output_file=None, max_bytes=0, backup_count=0)[source]

Parameters:

level (LogLevel)
output_file (str | None)
max_bytes (int)
backup_count (int)

Return type:

None

async log(level, category, message, context=None, **extra_fields)[source]

Log structured entry with automatic context injection.

Parameters:

level (LogLevel)
category (LogCategory)
message (str)
context (LogContext | None)
extra_fields (Any)

Return type:

None

class entity.resources.LogLevel(value)[source]

Bases: Enum

DEBUG = 'debug'

INFO = 'info'

WARNING = 'warning'

ERROR = 'error'

class entity.resources.MetricsCollectorResource(sample_rate=1.0)[source]

Bases: object

Collect and aggregate plugin execution metrics.

Parameters:: sample_rate (float)

__init__(sample_rate=1.0)[source]

Parameters:: sample_rate (float)
Return type:: None

health_check()[source]

Return True as metrics collection has no external deps.

Return type:: bool

async record_plugin_execution(plugin_name, stage, duration_ms, success)[source]

Record execution metrics for a plugin call.

Parameters:

plugin_name (str)
stage (str)
duration_ms (float)
success (bool)

Return type:

None

class entity.resources.ArgumentParsingResource(logger=None)[source]

Bases: ABC

Entity resource for structured CLI argument parsing.

This resource follows Entity’s patterns: - Uses structured logging via LoggingResource - Provides async validation and parsing - Maintains records for debugging - Integrates with Entity’s resource acquisition pattern

Parameters:: logger (LoggingResource | None)

__init__(logger=None)[source]

Parameters:: logger (LoggingResource | None)

abstractmethod async generate_help(command=None)[source]

Generate help text for commands.

Parameters:: command (str | None)
Return type:: str

health_check()[source]

Resource health check.

Return type:: bool

async log(level, category, message, **kwargs)[source]

Log through Entity’s logging system if available.

Parameters:

level (LogLevel)
category (LogCategory)
message (str)

abstractmethod async parse(args=None)[source]

Parse command-line arguments.

Parameters:: args (List[str] | None)
Return type:: ParsedArguments

register_argument(command_name, name, type, category, help, **kwargs)[source]

Register an argument for a specific command.

Parameters:

command_name (str)
name (str)
type (ArgumentType)
category (ArgumentCategory)
help (str)

Return type:

None

register_command(command)[source]

Register a command with the parser.

Parameters:: command (CommandDefinition)
Return type:: None

class entity.resources.EntityArgumentParsingResource(logger=None, app_name='entity-cli', app_description='Entity Framework CLI')[source]

Bases: ArgumentParsingResource

Entity-native argument parsing implementation.

Provides clean, structured argument parsing without external dependencies, following Entity framework patterns and integrating with Entity resources.

Parameters:

logger (LoggingResource | None)
app_name (str)
app_description (str)

__init__(logger=None, app_name='entity-cli', app_description='Entity Framework CLI')[source]

Parameters:

logger (LoggingResource | None)
app_name (str)
app_description (str)

async generate_help(command=None)[source]

Generate help text using Entity’s structured approach.

Parameters:: command (str | None)
Return type:: str

async parse(args=None)[source]

Parse arguments using Entity-native parsing logic.

Parameters:: args (List[str] | None)
Return type:: ParsedArguments

class entity.resources.ArgumentDefinition(name, type, category, help, required=False, default=None, choices=None, aliases=<factory>, validator=None)[source]

Bases: object

Definition of a command-line argument.

Parameters:

name (str)
type (ArgumentType)
category (ArgumentCategory)
help (str)
required (bool)
default (Any)
choices (List[str] | None)
aliases (List[str])
validator (Callable[[Any], bool] | None)

__init__(name, type, category, help, required=False, default=None, choices=None, aliases=<factory>, validator=None)

Parameters:

name (str)
type (ArgumentType)
category (ArgumentCategory)
help (str)
required (bool)
default (Any)
choices (List[str] | None)
aliases (List[str])
validator (Callable[[Any], bool] | None)

Return type:

None

choices: List[str] | None = None

default: Any = None

required: bool = False

validator: Callable[[Any], bool] | None = None

name: str

type: ArgumentType

category: ArgumentCategory

help: str

aliases: List[str]

class entity.resources.CommandDefinition(name, help, arguments=<factory>, handler=None)[source]

Bases: object

Definition of a CLI command with its arguments.

Parameters:

name (str)
help (str)
arguments (List[ArgumentDefinition])
handler (Callable | None)

__init__(name, help, arguments=<factory>, handler=None)

Parameters:

name (str)
help (str)
arguments (List[ArgumentDefinition])
handler (Callable | None)

Return type:

None

handler: Callable | None = None

name: str

help: str

arguments: List[ArgumentDefinition]

class entity.resources.ArgumentType(value)[source]

Bases: Enum

Supported argument types for Entity CLI parsing.

STRING = 'string'

INTEGER = 'integer'

BOOLEAN = 'boolean'

CHOICE = 'choice'

PATH = 'path'

class entity.resources.ArgumentCategory(value)[source]

Bases: Enum

Categories for organizing CLI arguments.

WORKFLOW = 'workflow'

RESOURCE = 'resource'

OUTPUT = 'output'

SYSTEM = 'system'

entity.resources.create_argument_parsing_resource(logger=None, app_name='entity-cli', app_description='Entity Framework CLI')[source]

Factory function to create ArgumentParsingResource following Entity patterns.

Parameters:

logger (LoggingResource | None)
app_name (str)
app_description (str)

Return type:

EntityArgumentParsingResource

exception entity.resources.InfrastructureError[source]

Bases: ResourceError

Raised when infrastructure operations fail.

entity.resources.create_memory(database, vector_store, table_name='entity_memory')[source]

Create a basic memory instance.

This is the replacement for the old Memory class.

Parameters:

database (DatabaseResource) – Database resource for structured storage
vector_store (VectorStoreResource) – Vector store resource for semantic search
table_name (str) – Name of the database table to use

Returns:

Basic memory instance implementing IMemory protocol

Return type:

IMemory

entity.resources.create_async_memory(database, vector_store, table_name='entity_memory', max_workers=10)[source]

Create an async-capable memory instance.

This is the replacement for the old AsyncMemory class.

Parameters:

database (DatabaseResource) – Database resource for structured storage
vector_store (VectorStoreResource) – Vector store resource for semantic search
table_name (str) – Name of the database table to use
max_workers (int) – Maximum number of worker threads for async operations

Returns:

Memory instance with async capabilities

Return type:

IMemory

entity.resources.create_managed_memory(database, vector_store, table_name='entity_memory', default_ttl=3600, max_entries=1000, evict_count=100, cleanup_interval=60)[source]

Create a managed memory instance with TTL and LRU features.

This is the replacement for the old ManagedMemory class.

Parameters:

database (DatabaseResource) – Database resource for structured storage
vector_store (VectorStoreResource) – Vector store resource for semantic search
table_name (str) – Name of the database table to use
default_ttl (int | None) – Default time-to-live in seconds (None = no expiry)
max_entries (int) – Maximum number of entries before LRU eviction
evict_count (int) – Number of entries to evict when max is reached
cleanup_interval (int) – Interval in seconds between TTL cleanup runs

Returns:

Memory instance with TTL and LRU management

Return type:

IMemory

entity.resources.create_robust_memory(database, vector_store, table_name='entity_memory', lock_dir='/tmp/entity_locks', timeout=10.0, enable_monitoring=True)[source]

Create a robust memory instance with locking and monitoring.

This is the replacement for the old RobustMemory class.

Parameters:

database (DatabaseResource) – Database resource for structured storage
vector_store (VectorStoreResource) – Vector store resource for semantic search
table_name (str) – Name of the database table to use
lock_dir (str) – Directory for lock files
timeout (float) – Lock acquisition timeout in seconds
enable_monitoring (bool) – Whether to enable metrics collection

Returns:

Memory instance with process-safe locking and monitoring

Return type:

IMemory

entity.resources.create_full_featured_memory(database, vector_store, table_name='entity_memory', default_ttl=None, max_entries=10000, evict_count=100, cleanup_interval=60, lock_dir='/tmp/entity_locks', lock_timeout=10.0, enable_monitoring=True, async_workers=10)[source]

Create a fully-featured memory instance with all decorators.

This combines all available features for maximum functionality.

Parameters:

database (DatabaseResource) – Database resource for structured storage
vector_store (VectorStoreResource) – Vector store resource for semantic search
table_name (str) – Name of the database table to use
default_ttl (int | None) – Default time-to-live in seconds (None = no expiry)
max_entries (int) – Maximum number of entries before LRU eviction
evict_count (int) – Number of entries to evict when max is reached
cleanup_interval (int) – Interval in seconds between TTL cleanup runs
lock_dir (str) – Directory for lock files
lock_timeout (float) – Lock acquisition timeout in seconds
enable_monitoring (bool) – Whether to enable metrics collection
async_workers (int) – Maximum number of worker threads for async operations

Returns:

Memory instance with all available features

Return type:

IMemory

class entity.resources.AsyncMemory(database, vector_store, table_name='entity_memory', max_workers=10)[source]

Bases: object

Deprecated: Use create_async_memory() factory function instead.

This class is maintained for backward compatibility only.

Parameters:

database (DatabaseResource)
vector_store (VectorStoreResource)
table_name (str)
max_workers (int)

class entity.resources.ManagedMemory(database, vector_store, table_name='entity_memory', default_ttl=3600, max_entries=1000, evict_count=100, cleanup_interval=60)[source]

Bases: object

Deprecated: Use create_managed_memory() factory function instead.

This class is maintained for backward compatibility only.

Parameters:

database (DatabaseResource)
vector_store (VectorStoreResource)
table_name (str)
default_ttl (Optional[int])
max_entries (int)
evict_count (int)
cleanup_interval (int)

class entity.resources.RobustMemory(database, vector_store, table_name='entity_memory', lock_dir='/tmp/entity_locks', timeout=10.0, enable_monitoring=True)[source]

Bases: object

Deprecated: Use create_robust_memory() factory function instead.

This class is maintained for backward compatibility only.

Parameters:

database (DatabaseResource)
vector_store (VectorStoreResource)
table_name (str)
lock_dir (str)
timeout (float)
enable_monitoring (bool)

entity.resources package

Submodules