Core Components#

class isek.isek_center.CommonResponse(data: Any | None, code: int, message: str)[source]#

Bases: object

A helper class to standardize JSON API responses.

classmethod fail(message: str, code: int = 400, data: Any | None = None) → Tuple[Dict[str, Any], int][source]#

Creates a standardized failure/error response.

Commonly used for client errors (e.g., bad request, not found).

Parameters:

message (str) -- The failure message.
code (int) -- The error code. Defaults to 400 (Bad Request).
data (Optional[Any]) -- Optional data payload accompanying the failure.

Returns:

A tuple containing the response dictionary and the HTTP status code.

Return type:

Tuple[Dict[str, Any], int]

classmethod success(data: Any | None = None, code: int = 200, message: str = 'success') → Tuple[Dict[str, Any], int][source]#

Creates a standardized success response.

Parameters:

data (Optional[Any]) -- Optional data payload for the success response.
code (int) -- The success code. Defaults to 200.
message (str) -- The success message. Defaults to 'success'.

Returns:

A tuple containing the response dictionary and the HTTP status code.

Return type:

Tuple[Dict[str, Any], int]

to_dict() → Dict[str, Any][source]#

Converts the CommonResponse instance to a dictionary.

Returns:: A dictionary representation of the response.
Return type:: Dict[str, Any]

isek.isek_center.cleanup_expired_nodes() → None[source]#

Periodically removes expired nodes from the nodes dictionary.

This function runs in a separate daemon thread. It checks every 5 seconds for nodes whose lease (expires_at) has passed.

isek.isek_center.deregister_node_route() → Tuple[Dict[str, Any], int][source]#

Deregisters a node from the service.

Expects a JSON payload with node_id.

Request JSON Body:

{
    "node_id": "unique_node_identifier"
}

Responses:

200 OK: Node deregistered successfully.
400 Bad Request: Missing or invalid node_id.
404 Not Found: If node_id does not exist (alternative to 400 for invalid).

Returns:: A Flask JSON response.
Return type:: FlaskResponse

isek.isek_center.get_available_nodes_route() → Tuple[Dict[str, Any], int][source]#

Retrieves a list of all currently active (non-expired) registered nodes.

Responses:

200 OK: Returns a list of available nodes. The response data will be structured as follows:

{
    "available_nodes": {
        "node_id_1": {
            "node_id": "node_id_1",
            "host": "host1.example.com",
            "port": 8080,
            "metadata": {"key1": "value1"},
            "expires_at": 1678886400.0
        },
        "node_id_2": {
            "node_id": "node_id_2",
            "host": "host2.example.com",
            "port": 8081,
            "metadata": {},
            "expires_at": 1678886500.0
        }
    }
}

Returns:: A Flask JSON response containing the available nodes.
Return type:: FlaskResponse

isek.isek_center.main() → None[source]#

Sets up and runs the Flask application for the Isek Center.

Initializes a background thread for cleaning up expired node registrations and starts the Flask development server.

isek.isek_center.register_node_route() → Tuple[Dict[str, Any], int][source]#

Registers a new node or updates an existing node's registration.

Expects a JSON payload with node_id, host, port, and optional metadata. Assigns an expiration time to the node's registration (lease).

Request JSON Body:

{
    "node_id": "unique_node_identifier",
    "host": "node_hostname_or_ip",
    "port": 8080,
    "metadata": {"key": "value"}
}

Responses:

200 OK: Node registered successfully.
400 Bad Request: Missing required fields (node_id, host, port).

Returns:: A Flask JSON response.
Return type:: FlaskResponse

isek.isek_center.renew_lease_route() → Tuple[Dict[str, Any], int][source]#

Renews the lease for an existing registered node.

Expects a JSON payload with node_id. Updates the node's expires_at timestamp.

Request JSON Body:

{
    "node_id": "unique_node_identifier"
}

Responses:

200 OK: Lease renewed successfully.
400 Bad Request: Missing or invalid node_id.
404 Not Found: If node_id does not exist.

Returns:: A Flask JSON response.
Return type:: FlaskResponse

class isek.isek_config.IsekConfig(yaml_path: str)[source]#

Bases: object

Manages application configuration loaded from a YAML file.

This class provides a structured way to access configuration values and to instantiate various components of the Isek system, such as agents, registries, language models (LLMs), and embedding models, based on the loaded configuration.

get(*keys: str, default: Any | None = None) → Any | None[source]#

Retrieves a configuration value using a sequence of keys (path).

Traverses the nested configuration dictionary. If any key in the path is not found, or if the path leads to a None value explicitly, it returns the default value.

Example: config.get("agent", "persona", "name", default="Unknown")

Parameters:

keys (str) -- A sequence of string keys representing the path to the desired value.
default (Optional[Any]) -- The value to return if the path is not found or the value is None. Defaults to None.

Returns:

The configuration value if found, otherwise the default value.

Return type:

Optional[Any]

get_sub_config(key: str) → Dict[str, Any] | None[source]#

Retrieves a sub-dictionary from the configuration.

Parameters:: key (str) -- The top-level key for the desired sub-configuration dictionary.
Returns:: The sub-configuration dictionary if the key exists and its value is a dictionary, otherwise None.
Return type:: Optional[Dict[str, Any]]

load_agent() → SingleAgent | DistributedAgent[source]#

Loads and returns an agent instance (SingleAgent or DistributedAgent) based on the configuration.

Configures the agent with its persona, language model, and, if distributed, its network settings (host, port, registry) and embedding model. Also initializes the logger based on the 'debug' setting.

Returns:: An instance of SingleAgent or DistributedAgent.
Return type:: Union[isek.agent.single_agent.SingleAgent, isek.agent.distributed_agent.DistributedAgent]
Raises:: ValueError -- If essential configuration for the agent is missing or invalid.

load_embedding() → AbstractEmbedding | None[source]#

Loads and returns an embedding model instance based on the configuration.

Uses an 'embeddings' dispatcher (assumed to be a dictionary or module mapping mode names to embedding classes) to instantiate the correct type.

Returns:: An instance of an AbstractEmbedding implementation, or None if no embedding model is configured or if the mode is "None".
Return type:: Optional[isek.embedding.abstract_embedding.AbstractEmbedding]
Raises:: ValueError -- If the configured embedding mode is not supported or its specific configuration is missing/invalid.

load_etcd_registry(etcd_specific_config: Dict[str, Any]) → EtcdRegistry[source]#

Loads an EtcdRegistry instance using etcd-specific configuration.

Parameters:: etcd_specific_config (Dict[str, Any]) -- A dictionary containing parameters for etcd3.Etcd3Client (e.g., host, port) and EtcdRegistry (e.g., ttl, parent_node_id).
Returns:: An instance of EtcdRegistry.
Return type:: isek.node.etcd_registry.EtcdRegistry
Raises:: ValueError -- If essential etcd configuration is missing or etcd3.client fails.

load_isek_center_registry(isek_center_specific_config: Dict[str, Any]) → IsekCenterRegistry[source]#

Loads an IsekCenterRegistry instance using its specific configuration.

Parameters:: isek_center_specific_config (Dict[str, Any]) -- A dictionary containing parameters for IsekCenterRegistry (e.g., host, port).
Returns:: An instance of IsekCenterRegistry.
Return type:: isek.node.isek_center_registry.IsekCenterRegistry

load_llm() → AbstractModel | None[source]#

Loads and returns a language model (LLM) instance based on the configuration.

Uses an 'llms' dispatcher (assumed to be a dictionary or module mapping mode names to LLM classes) to instantiate the correct LLM type.

Returns:: An instance of an AbstractModel implementation, or None if no LLM is configured or if the mode is "None".
Return type:: Optional[isek.llm.abstract_model.AbstractModel]
Raises:: ValueError -- If the configured LLM mode is not supported or its specific configuration is missing/invalid.

load_registry() → Registry[source]#

Loads and returns a service registry instance based on the configuration.

Supports "etcd" or "isek_center" (defaulting to "isek_center" if 'registry.mode' is missing).

Returns:: An instance of a Registry implementation.
Return type:: isek.node.registry.Registry
Raises:: ValueError -- If the registry configuration is missing or invalid.

isek.cli.get_available_examples(ctx, args, incomplete)[source]#: Get available example scripts

isek.cli.load_module(script_path: Path)[source]#: Dynamically load module