entity.infrastructure package

class entity.infrastructure.AdaptiveLLMInfrastructure(preferred_models=None, benchmark_timeout=10.0, min_tokens_per_second=20.0, **kwargs)

Bases: BaseInfrastructure

Adaptive LLM infrastructure with automatic backend selection.

This infrastructure automatically detects GPU acceleration capabilities and selects the best available model backend for optimal performance.

Parameters:

• preferred_models (Optional[List[ModelConfig]])

• benchmark_timeout (float)

• min_tokens_per_second (float)

__init__(preferred_models=None, benchmark_timeout=10.0, min_tokens_per_second=20.0, **kwargs)

Initialize adaptive LLM infrastructure.

Parameters:

• preferred_models (List[ModelConfig] | None) – List of model configurations in order of preference

• benchmark_timeout (float) – Timeout for performance benchmarking in seconds

• min_tokens_per_second (float) – Minimum acceptable tokens/second performance

• **kwargs – Additional arguments passed to BaseInfrastructure

get_benchmark_results()

Get benchmark results for all tested models.

Return type:

Dict[str, Dict[str, Any]]

get_current_config()

Get current active configuration.

Return type:

Dict[str, Any]

async health_check()

Check if the active infrastructure is healthy.

Return type:

bool

async shutdown()

Shutdown the active infrastructure.

Return type:

None

async startup()

Initialize the adaptive infrastructure by detecting optimal backend.

Return type:

None

class entity.infrastructure.BaseInfrastructure(version=None)

Bases: ABC

Common functionality for infrastructure components.

Parameters:

version (str | None)

__init__(version=None)

Parameters:

version (str | None)

Return type:

None

abstractmethod async health_check()

Return True if the infrastructure is healthy.

Return type:

bool

health_check_sync()

Synchronous wrapper for health_check for compatibility.

Return type:

bool

async shutdown()

Perform asynchronous cleanup.

Return type:

None

async startup()

Perform asynchronous initialization.

Return type:

None

version = '0.1'

class entity.infrastructure.DuckDBInfrastructure(file_path, pool_size=5, version=None)

Bases: BaseInfrastructure

Layer 1 infrastructure for managing a DuckDB database file.

Parameters:

• file_path (str)

• pool_size (int)

• version (str | None)

__init__(file_path, pool_size=5, version=None)

Create the infrastructure with a simple connection pool.

Parameters:

• file_path (str)

• pool_size (int)

• version (str | None)

Return type:

None

connect()

Yield a database connection from the pool.

Return type:

Generator

async health_check()

Return True if the database can be opened.

Return type:

bool

async shutdown()

Perform asynchronous cleanup.

Return type:

None

async startup()

Perform asynchronous initialization.

Return type:

None

class entity.infrastructure.HarmonyOSSInfrastructure(model_path, reasoning_level='medium', temperature=0.7, max_tokens=2000)

Bases: BaseInfrastructure

Infrastructure adapter for GPT-OSS models using harmony format.

This adapter: - Formats prompts using the harmony multi-role structure - Parses multi-channel responses (analysis, commentary, final) - Maintains role hierarchy for proper context - Integrates with Entity’s LLM infrastructure protocol

Parameters:

• model_path (str)

• reasoning_level (str)

• temperature (float)

• max_tokens (int)

__init__(model_path, reasoning_level='medium', temperature=0.7, max_tokens=2000)

Initialize the Harmony OSS Infrastructure.

Parameters:

• model_path (str) – Path or identifier for the GPT-OSS model

• reasoning_level (str) – Reasoning effort level (low, medium, high)

• temperature (float) – Sampling temperature for generation

• max_tokens (int) – Maximum tokens to generate

Return type:

None

async generate(prompt, system_prompt=None)

Generate a response using harmony format.

Parameters:

• prompt (str) – User input prompt

• system_prompt (str | None) – Optional system-level instructions

Returns:

Generated text response (final channel by default)

Return type:

str

async generate_with_channels(prompt)

Generate response and return all channels.

Returns:

Dictionary with analysis, commentary, and final channels

Parameters:

prompt (str)

Return type:

Dict[str, str]

async health_check()

Check if the GPT-OSS model is accessible and responsive.

Return type:

bool

set_reasoning_effort(level)

Dynamically adjust reasoning effort level.

Parameters:

level (str)

Return type:

None

async shutdown()

Clean up resources.

Return type:

None

async startup()

Initialize the harmony infrastructure.

Return type:

None

class entity.infrastructure.LocalStorageInfrastructure(base_path, version=None)

Bases: BaseInfrastructure

Layer 1 infrastructure for storing files on the local filesystem.

Parameters:

• base_path (str)

• version (str | None)

__init__(base_path, version=None)

Create the infrastructure rooted at base_path.

Parameters:

• base_path (str)

• version (str | None)

Return type:

None

async health_check()

Return True if the base path is writable.

Return type:

bool

resolve_path(key)

Return the absolute path for the given storage key.

Parameters:

key (str)

Return type:

Path

async shutdown()

Perform asynchronous cleanup.

Return type:

None

async startup()

Perform asynchronous initialization.

Return type:

None

class entity.infrastructure.OllamaInfrastructure(base_url, model, version=None)

Bases: BaseInfrastructure

Layer 1 infrastructure for communicating with an Ollama server.

Parameters:

• base_url (str)

• model (str)

• version (str | None)

__init__(base_url, model, version=None)

Configure the client base URL, model, and installer settings.

Parameters:

• base_url (str)

• model (str)

• version (str | None)

Return type:

None

async generate(prompt)

Send a prompt to Ollama and return the generated text.

Parameters:

prompt (str)

Return type:

str

async health_check()

Return True if the Ollama server responds.

Return type:

bool

async shutdown()

Perform asynchronous cleanup.

Return type:

None

async startup()

Perform asynchronous initialization.

Return type:

None

class entity.infrastructure.S3Infrastructure(bucket, version=None)

Bases: BaseInfrastructure

Layer 1 infrastructure for interacting with an S3 bucket.

Parameters:

• bucket (str)

• version (str | None)

__init__(bucket, version=None)

Configure the target bucket.

Parameters:

• bucket (str)

• version (str | None)

Return type:

None

async client()

Create an S3 client from the session.

async health_check()

Return True if the bucket is reachable.

Return type:

bool

session()

Return an aioboto3 session, creating one if needed.

Return type:

aioboto3.Session

async shutdown()

Perform asynchronous cleanup.

Return type:

None

async startup()

Perform asynchronous initialization.

Return type:

None

class entity.infrastructure.DatabaseInfrastructure(*args, **kwargs)

Bases: Protocol

Protocol for database infrastructure implementations.

__init__(*args, **kwargs)

connect()

Return a database connection context manager.

Return type:

Any

async health_check()

Return True if the infrastructure is healthy.

Return type:

bool

async shutdown()

Perform asynchronous cleanup.

Return type:

None

async startup()

Perform asynchronous initialization.

Return type:

None

class entity.infrastructure.VectorStoreInfrastructure(*args, **kwargs)

Bases: Protocol

Protocol for vector store infrastructure implementations.

__init__(*args, **kwargs)

connect()

Return a vector store connection context manager.

Return type:

Any

async health_check()

Return True if the infrastructure is healthy.

Return type:

bool

async shutdown()

Perform asynchronous cleanup.

Return type:

None

async startup()

Perform asynchronous initialization.

Return type:

None

class entity.infrastructure.StorageInfrastructure(*args, **kwargs)

Bases: Protocol

Protocol for storage infrastructure implementations.

__init__(*args, **kwargs)

async delete(path)

Delete a file.

Parameters:

path (str)

Return type:

None

async exists(path)

Check if a file exists.

Parameters:

path (str)

Return type:

bool

async health_check()

Return True if the infrastructure is healthy.

Return type:

bool

async list_files(prefix='')

List files with optional prefix.

Parameters:

prefix (str)

Return type:

list[str]

async read(path)

Read file contents.

Parameters:

path (str)

Return type:

bytes

resolve(path)

Resolve a path relative to the storage root.

Parameters:

path (str)

Return type:

str

async shutdown()

Perform asynchronous cleanup.

Return type:

None

async startup()

Perform asynchronous initialization.

Return type:

None

async write(path, data)

Write file contents.

Parameters:

• path (str)

• data (bytes)

Return type:

None

Submodules

• entity.infrastructure.base module
  • BaseInfrastructure
    • BaseInfrastructure.__init__()
    • BaseInfrastructure.version
    • BaseInfrastructure.startup()
    • BaseInfrastructure.shutdown()
    • BaseInfrastructure.health_check()
    • BaseInfrastructure.health_check_sync()
• entity.infrastructure.config_models module
  • DuckDBConfig
    • DuckDBConfig.file_path
    • DuckDBConfig.pool_size
    • DuckDBConfig.version
    • DuckDBConfig.validate_file_path()
    • DuckDBConfig.model_config
  • OllamaConfig
    • OllamaConfig.base_url
    • OllamaConfig.model
    • OllamaConfig.version
    • OllamaConfig.validate_base_url()
    • OllamaConfig.model_config
  • LocalStorageConfig
    • LocalStorageConfig.base_path
    • LocalStorageConfig.permissions
    • LocalStorageConfig.version
    • LocalStorageConfig.validate_permissions()
    • LocalStorageConfig.model_config
  • S3Config
    • S3Config.bucket
    • S3Config.region
    • S3Config.endpoint_url
    • S3Config.version
    • S3Config.validate_bucket_name()
    • S3Config.model_config
• entity.infrastructure.local_storage_infra module
  • LocalStorageInfrastructure
    • LocalStorageInfrastructure.__init__()
    • LocalStorageInfrastructure.resolve_path()
    • LocalStorageInfrastructure.health_check()
    • LocalStorageInfrastructure.startup()
    • LocalStorageInfrastructure.shutdown()
• entity.infrastructure.ollama_infra module
  • OllamaInfrastructure
    • OllamaInfrastructure.__init__()
    • OllamaInfrastructure.generate()
    • OllamaInfrastructure.startup()
    • OllamaInfrastructure.shutdown()
    • OllamaInfrastructure.health_check()
• entity.infrastructure.protocols module
  • DatabaseInfrastructure
    • DatabaseInfrastructure.startup()
    • DatabaseInfrastructure.shutdown()
    • DatabaseInfrastructure.health_check()
    • DatabaseInfrastructure.connect()
    • DatabaseInfrastructure.__init__()
  • VectorStoreInfrastructure
    • VectorStoreInfrastructure.startup()
    • VectorStoreInfrastructure.shutdown()
    • VectorStoreInfrastructure.health_check()
    • VectorStoreInfrastructure.connect()
    • VectorStoreInfrastructure.__init__()
  • StorageInfrastructure
    • StorageInfrastructure.startup()
    • StorageInfrastructure.shutdown()
    • StorageInfrastructure.health_check()
    • StorageInfrastructure.resolve()
    • StorageInfrastructure.read()
    • StorageInfrastructure.write()
    • StorageInfrastructure.delete()
    • StorageInfrastructure.exists()
    • StorageInfrastructure.list_files()
    • StorageInfrastructure.__init__()
• entity.infrastructure.s3_infrastructure module
  • S3Infrastructure
    • S3Infrastructure.__init__()
    • S3Infrastructure.session()
    • S3Infrastructure.client()
    • S3Infrastructure.startup()
    • S3Infrastructure.shutdown()
    • S3Infrastructure.health_check()