semantica/docs/reference/core.md

Core

Framework infrastructure, lifecycle management, and plugin system.

---

🎯 Overview

• :material-cogs:{ .lg .middle } Orchestrator

  ---

  Central coordinator for all framework components and workflows

• :material-lifecycle:{ .lg .middle } Lifecycle Management

  ---

  Manage initialization, startup, shutdown, and state transitions

• :material-tune:{ .lg .middle } Configuration

  ---

  Unified configuration management via YAML and Environment variables

• :material-puzzle:{ .lg .middle } Plugin System

  ---

  Extensible plugin registry for adding custom modules and capabilities

• :material-console:{ .lg .middle } Logging & Telemetry

  ---

  Centralized logging and metrics collection

!!! tip "When to Use" - Application Startup: Initializing the Semantica framework in your app - Configuration: Tuning global settings - Extension: Developing custom plugins or modules - Orchestration: Coordinating complex workflows across multiple modules

---

⚙️ Algorithms Used

Lifecycle Management

• State Machine: CREATED -> INITIALIZED -> RUNNING -> STOPPED
• Dependency Injection: Resolving and injecting dependencies between modules.
• Graceful Shutdown: Ensuring all resources (DB connections, thread pools) are closed properly.

Configuration

• Layered Loading: Defaults -> Config File -> Environment Variables -> CLI Arguments (Priority order).
• Schema Validation: Validating config structure against defined schemas.

Plugin System

• Discovery: Auto-discovery of plugins via entry points or directory scanning.
• Registration: Dynamic registration of classes and functions.
• Hook Execution: Running plugin hooks at specific lifecycle events.

---

Main Classes

Orchestrator

The brain of the framework.

Methods:

Method	Description
start()	Initialize and start all components
stop()	Graceful shutdown
get_component(name)	Access initialized module

Example:

from semantica.core import Orchestrator

app = Orchestrator()
app.start()

# Access modules
kg = app.get_component("knowledge_graph")
ingest = app.get_component("ingest")

ConfigManager

Manages global configuration.

Methods:

Method	Description
load(path)	Load config from file
get(key, default)	Get config value

PluginRegistry

Manages extensions.

Methods:

Method	Description
register(plugin)	Register new plugin
get_plugin(name)	Retrieve plugin

---

Configuration

Environment Variables

export SEMANTICA_ENV=production
export SEMANTICA_LOG_LEVEL=INFO
export SEMANTICA_CONFIG_PATH=./config.yaml

YAML Configuration

core:
  environment: production
  log_level: INFO
  plugins:
    enabled: true
    directory: ./plugins

---

Integration Examples

Custom Application

from semantica.core import Orchestrator, ConfigManager

# 1. Load Config
config = ConfigManager()
config.load("config.yaml")

# 2. Initialize Orchestrator
app = Orchestrator(config=config)

# 3. Register Custom Plugin
class MyPlugin:
    name = "my_plugin"
    def initialize(self):
        print("My Plugin Started")

app.plugin_registry.register(MyPlugin())

# 4. Start
app.start()

# 5. Run Workload
try:
    app.run_pipeline("my_pipeline")
finally:
    app.stop()

---

Best Practices

1. Use Orchestrator: Avoid manually instantiating every module; let the Orchestrator handle dependencies.
2. Graceful Shutdown: Always ensure app.stop() is called (e.g., in a finally block) to prevent resource leaks.
3. Config Layers: Use config.yaml for defaults and Environment Variables for secrets/overrides.

---

See Also

• Pipeline Module - Executed by the Orchestrator
• Utils Module - Shared utilities used by Core