forge-core-di 0.2.0__py3-none-any.whl

forge_core_di-0.2.0.dist-info/METADATA

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: forge-core-di
+Version: 0.2.0
+Summary: Lightweight Dependency Injection and Application Runtime Core for Python.
+Project-URL: Homepage, https://github.com/akmallmline/forgecore
+Project-URL: Repository, https://github.com/akmallmline/forgecore
+Author-email: Akmal Maulana <akmallmline@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: application-kernel,autowiring,dependency-injection,di-container,framework,lifecycle,plugin,python
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# ForgeCore
+
+Lightweight Dependency Injection and Application Runtime Core for Python.
+
+ForgeCore is a framework engine — not just a DI container. It provides the
+foundation for building web frameworks, CLI tools, bots, trading systems,
+and AI agents in Python.
+
+---
+
+## Features
+
+- Explicit DI container — no magic auto-registration
+- Constructor autowiring via type hints
+- Singleton, Transient, and Scoped lifecycles
+- Thread-safe scoped instances via `threading.local()`
+- Circular dependency detection with clear error messages
+- Optional injection (`Cache | None = None`)
+- Service binding — abstraction to implementation mapping
+- Custom factory support
+- Application kernel with boot pipeline
+- Service provider system for modular registration
+- Lifecycle hooks (`on_start`, `on_stop`)
+- Event system with subscribe, emit, and unsubscribe
+- Plugin system for runtime extension
+
+---
+
+## Requirements
+
+- Python 3.12+
+
+---
+
+## Installation
+
+```bash
+pip install forgecore

forge_core_di-0.2.0.dist-info/RECORD

@@ -0,0 +1,49 @@
+forgecore/__init__.py,sha256=RFUPWZq6cx9eKEbAhwYbi6dh4bz7AHeGvjNwjm10BfA,1844
+forgecore/version.py,sha256=Zn1KFblwuFHiDRdRAiRnDBRkbPttWh44jKa5zG2ov0E,22
+forgecore/application/__init__.py,sha256=CybBmP2gBeXOT7HFENFlpqc3Qaz1iCgeh4Tm6Fcgszo,126
+forgecore/application/app.py,sha256=6XukXSCyX2nJ0UThoUNfWVxxMxtiTmIYVtCyQzGd6Ak,2576
+forgecore/application/metadata.py,sha256=-_W7NUZypbu0R31flRwabQPkQLLoo9ZAWmQyPCRQ7Is,213
+forgecore/config/__init__.py,sha256=0RaUZX5uZjJ6Xw8ShA63aflFq9se3QCq0rZ_jRUlePE,56
+forgecore/config/config.py,sha256=I8oZYsHnt6ulntZ7e3mqlOodKGdP2NW7s34MlGG2ZVw,586
+forgecore/context/__init__.py,sha256=yG8qxX4kXW8FMVHF2ThA90c8JpyRh-bFAgsmtcy7X6s,81
+forgecore/context/context.py,sha256=XiR9MAB4FFwiQ6TjLyrQWKRTAjXOsYOIvp7b6JMRZf4,693
+forgecore/core/__init__.py,sha256=q0W5AJvgMXy55WwaMuVAZeLfSZW0tGcqNEqqSJmNZFo,622
+forgecore/core/constants.py,sha256=oprb761hTUWhWtzCKqXLwaT4ZxhHGx58DVxAW37-yac,94
+forgecore/core/exceptions.py,sha256=GRLE7HhH_1Fxjqya98Yb--niRrYfcxC9j-IBMnKn18A,258
+forgecore/core/types.py,sha256=7cGY2289h8ITPA_DUdpHd0p1c8G2UCwwA_16efV9lJY,101
+forgecore/core/version.py,sha256=zpHIM4v-sIMttitw4o_oPc-eiqXwmlmmcSwU6b3-XYw,63
+forgecore/lifecycle/__init__.py,sha256=Qzb7y4-1r3Gi0Rl9rYoK3_LCyTeatozUtGMj1JORwws,133
+forgecore/lifecycle/manager.py,sha256=K7dDScD90iwpm8ee_3bxj4sIngjP8JtW1oDsGf4nV88,1019
+forgecore/lifecycle/state.py,sha256=__lsC57gjdvand2xfVr4CNdqT412PPf8_fZd4RPH80w,225
+forgecore/logging/__init__.py,sha256=7O9U4WeO02q8Wdo5t57SwkfcWdFlj_pONt_yS77fqKM,64
+forgecore/logging/logger.py,sha256=TKKIn5pDKSjBSZEMB6YCrU_SGnPLKljxhEYHD3LiSDA,473
+forgecore/plugins/__init__.py,sha256=So8druVzdZh_0oMVAthd9g7F7gFBgXKgyQaYLK2QXXg,112
+forgecore/plugins/manager.py,sha256=H4VbYM2i2kp69d6ePWPq6JFo8d8WZpgdoUFPdZGQCh8,881
+forgecore/plugins/plugin.py,sha256=6PSA7ji51MuFgtFDpwujHTRVmvLt4ruIzwSJRyoPxZs,442
+forgecore/providers/__init__.py,sha256=KH3PLIy3j2poxlkVuAGYDp-LWfcRpZfnVUtnkXOCJJc,76
+forgecore/providers/provider.py,sha256=z60qg3V6aGoYZoIE9DAlboOI_ZPiJ9kQi00_6Q-BaHY,375
+forgecore/registry/__init__.py,sha256=Idcw3PMSfRgbhoYNTdQYwRS39FQuAVKuYS36i3X1xhQ,127
+forgecore/registry/exceptions.py,sha256=y2a-WMmN7g5ke8c4xxhXDQtCiQaZ3_nh-0mNjALfWvw,88
+forgecore/registry/registry.py,sha256=8F_qtK-1BEtZ_UdIgbLDyXZN_eF-k2AMcuHOazcgQGY,760
+forgecore/runtime/__init__.py,sha256=WG-BKQVmHfEw2hzoIygv103RErx9QAEph8QZLFPMeMY,148
+forgecore/runtime/bus.py,sha256=3G53_WqvbCmU3nrMuFFQZoL-LlP3RFATNOQOoQvlNe8,1378
+forgecore/runtime/event.py,sha256=XuOSsiMkSXUiwL8cu5yBIqcOjOhBJIwjGfcLZwqmE_c,223
+forgecore/runtime/exceptions.py,sha256=CO6XUqOWxYZdaKpp8CyTnuo5xt5yC0RSVVY9UGiWrJU,38
+forgecore/services/__init__.py,sha256=1tNor8SQGwpqHd6pnpKN3MAA5xMeJXDHDHqAs_yHYY8,585
+forgecore/services/autowire.py,sha256=ZRR-Bq2q4ucWuWFW3bzB1kZSuNVAsYKsz0s736GhbTU,678
+forgecore/services/container.py,sha256=UzFwBeiPfBHb7SR5svI6i_jR0vTfkA6atv-VAqqAukU,2985
+forgecore/services/descriptor.py,sha256=CfBcSiSEtszMMLnYbnKcfqS0PAVvXpf7S17uTApNlIo,393
+forgecore/services/exceptions.py,sha256=_mOMlzWb7lRJaBMjtOqr5J0DGVx96t4Ir253yyayuHE,103
+forgecore/services/factory.py,sha256=IC3dxbaIbnTZFArjP9Ya0FDvuAcv1oK_aM0HiPHJ7Mo,420
+forgecore/services/resolver.py,sha256=y30CB41bdX3AFXrYENYOIwmcFqC1mwkxfYzQS65Y7rY,5494
+forgecore/services/scope.py,sha256=9Rzl8I80OtDiatYGqAwXa4HRFxXwKtp6C9zoCMjOzeQ,133
+forgecore/services/scope_context.py,sha256=cUill6RM9nfPaOUohBTPqHYmBPknba4E8a1rKT2rNEU,847
+forgecore/utils/__init__.py,sha256=DKLqJfaX_VE7q0vey86hC54Y06d8i6UyY5xciXNbupw,198
+forgecore/utils/inspect.py,sha256=RDrELdiOSVPT5p8YHmmZCY3_T3JfATTbZfCu84g835A,147
+forgecore/utils/system.py,sha256=JHcahq-Fi2PtoG3yfRmrKhyNroFgMXmSdnZGAgHxGmE,236
+forgecore/validation/__init__.py,sha256=Ho1O6qPjirsYP0hmy7usPJ_ILY4Fv1p36PuPSQbH6IU,225
+forgecore/validation/validators.py,sha256=B2_8NZ8eK8J5Z9U5y16-9-8q-aJqkNq9qF9D0gtrcrA,443
+forge_core_di-0.2.0.dist-info/METADATA,sha256=Wsz3b35js6JAhQ3uk8K_ND7JsWiLGyGpXEc60uixKkE,1878
+forge_core_di-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+forge_core_di-0.2.0.dist-info/licenses/LICENSE,sha256=lLcy2cvfVluby9-jyzLHJGt2v2m3NkTAhEnVSDSJC0c,377
+forge_core_di-0.2.0.dist-info/RECORD,,

forge_core_di-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

forge_core_di-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Akmal Maulana
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software.

forgecore/__init__.py

@@ -0,0 +1,88 @@
+from .application import ApplicationMetadata, ForgeApp
+from .config import Config
+from .core import (
+    DEFAULT_ENCODING,
+    DEFAULT_TIMEOUT,
+    JSON,
+    MAX_RETRIES,
+    PACKAGE_NAME,
+    VERSION,
+    ConfigurationError,
+    ForgeCoreError,
+    InitializationError,
+    JSONList,
+    UnsupportedPlatformError,
+    ValidationError,
+    __version__,
+)
+from .lifecycle import LifecycleManager, LifecycleState
+from .logging import get_logger
+from .plugins import Plugin, PluginManager
+from .providers import ServiceProvider
+from .registry import Registry
+from .runtime import Event, EventBus, EventError
+from .services import (
+    CircularDependencyError,
+    ScopeContext,
+    ServiceContainer,
+    ServiceDescriptor,
+    ServiceNotFoundError,
+    ServiceScope,
+)
+from .utils import (
+    machine,
+    operating_system,
+    package_version,
+    python_version,
+)
+from .validation import (
+    is_boolean,
+    is_float,
+    is_integer,
+    is_non_empty_string,
+    is_string,
+)
+
+__all__ = [
+    "__version__",
+    "VERSION",
+    "PACKAGE_NAME",
+    "DEFAULT_ENCODING",
+    "DEFAULT_TIMEOUT",
+    "MAX_RETRIES",
+    "ForgeCoreError",
+    "ConfigurationError",
+    "ValidationError",
+    "InitializationError",
+    "UnsupportedPlatformError",
+    "JSON",
+    "JSONList",
+    "ForgeApp",
+    "ApplicationMetadata",
+    "ServiceContainer",
+    "ServiceProvider",
+    "ServiceScope",
+    "ServiceDescriptor",
+    "ServiceNotFoundError",
+    "CircularDependencyError",
+    "ScopeContext",
+    "Event",
+    "EventBus",
+    "EventError",
+    "LifecycleManager",
+    "LifecycleState",
+    "Registry",
+    "Plugin",
+    "PluginManager",
+    "Config",
+    "get_logger",
+    "package_version",
+    "python_version",
+    "operating_system",
+    "machine",
+    "is_string",
+    "is_integer",
+    "is_float",
+    "is_boolean",
+    "is_non_empty_string",
+]

forgecore/application/__init__.py

@@ -0,0 +1,7 @@
+from .app import ForgeApp
+from .metadata import ApplicationMetadata
+
+__all__ = [
+    "ForgeApp",
+    "ApplicationMetadata",
+]

forgecore/application/app.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from forgecore.context import ApplicationContext
+from forgecore.lifecycle import LifecycleState
+from forgecore.providers import ServiceProvider
+from forgecore.runtime import Event
+
+from .metadata import ApplicationMetadata
+
+
+class ForgeApp:
+
+    def __init__(
+        self,
+        metadata: ApplicationMetadata | None = None,
+    ) -> None:
+        if metadata is None:
+            metadata = ApplicationMetadata(
+                name="Forge Application",
+                version="0.0.0",
+            )
+
+        self.context = ApplicationContext(metadata)
+        self._providers: list[ServiceProvider] = []
+        self._booted: bool = False
+
+    @property
+    def metadata(self) -> ApplicationMetadata:
+        return self.context.metadata
+
+    @property
+    def services(self):
+        return self.context.services
+
+    @property
+    def registry(self):
+        return self.context.registry
+
+    @property
+    def events(self):
+        return self.context.events
+
+    @property
+    def lifecycle(self):
+        return self.context.lifecycle
+
+    def register_provider(self, provider: ServiceProvider) -> None:
+        if self._booted:
+            raise RuntimeError(
+                "Cannot register provider after application has booted."
+            )
+        self._providers.append(provider)
+
+    def boot(self) -> None:
+        if self._booted:
+            return
+
+        for provider in self._providers:
+            provider.register(self.context.services)
+
+        for provider in self._providers:
+            provider.boot(self.context.services)
+
+        self._booted = True
+        self.context.events.emit(Event(name="app.booted"))
+
+    def run(self) -> None:
+        if self.lifecycle.state is not LifecycleState.INITIALIZED:
+            raise RuntimeError(
+                "Application is already running or has been stopped."
+            )
+
+        self.boot()
+
+        self.lifecycle.on_start(
+            lambda: self.context.events.emit(Event(name="app.starting"))
+        )
+        self.lifecycle.on_stop(
+            lambda: self.context.events.emit(Event(name="app.stopping"))
+        )
+
+        self.lifecycle.start()
+        self.lifecycle.run()
+        self.context.events.emit(Event(name="app.running"))
+
+    def stop(self) -> None:
+        if self.lifecycle.state is not LifecycleState.RUNNING:
+            raise RuntimeError(
+                "Application is not running."
+            )
+
+        self.lifecycle.stop()
+        self.lifecycle.shutdown()
+        self.context.events.emit(Event(name="app.stopped"))

forgecore/application/metadata.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class ApplicationMetadata:
+    name: str
+    version: str
+    description: str = ""
+    author: str = ""

forgecore/config/__init__.py

@@ -0,0 +1,5 @@
+from .config import Config
+
+__all__ = [
+    "Config",
+]

forgecore/config/config.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+class Config:
+    def __init__(self) -> None:
+        self._data: dict[str, Any] = {}
+
+    def load_json(self, path: str | Path) -> None:
+        with open(path, encoding="utf-8") as file:
+            self._data = json.load(file)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self._data.get(key, default)
+
+    def set(self, key: str, value: Any) -> None:
+        self._data[key] = value
+
+    def to_dict(self) -> dict[str, Any]:
+        return dict(self._data)

forgecore/context/__init__.py

@@ -0,0 +1,5 @@
+from .context import ApplicationContext
+
+__all__ = [
+    "ApplicationContext",
+]

forgecore/context/context.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from forgecore.application.metadata import ApplicationMetadata
+from forgecore.lifecycle import LifecycleManager
+from forgecore.registry import Registry
+from forgecore.runtime import EventBus
+from forgecore.services import ServiceContainer
+
+
+class ApplicationContext:
+    def __init__(
+        self,
+        metadata: ApplicationMetadata | None = None,
+    ) -> None:
+        self.metadata = metadata or ApplicationMetadata(
+            name="Forge Application",
+            version="0.0.0",
+        )
+
+        self.services = ServiceContainer()
+        self.registry = Registry()
+        self.events = EventBus()
+        self.lifecycle = LifecycleManager()

forgecore/core/__init__.py

@@ -0,0 +1,31 @@
+from .constants import (
+    DEFAULT_ENCODING,
+    DEFAULT_TIMEOUT,
+    MAX_RETRIES,
+    PACKAGE_NAME,
+)
+from .exceptions import (
+    ConfigurationError,
+    ForgeCoreError,
+    InitializationError,
+    UnsupportedPlatformError,
+    ValidationError,
+)
+from .types import JSON, JSONList
+from .version import VERSION, __version__
+
+__all__ = [
+    "PACKAGE_NAME",
+    "DEFAULT_ENCODING",
+    "DEFAULT_TIMEOUT",
+    "MAX_RETRIES",
+    "ForgeCoreError",
+    "ConfigurationError",
+    "ValidationError",
+    "InitializationError",
+    "UnsupportedPlatformError",
+    "VERSION",
+    "__version__",
+    "JSON",
+    "JSONList",
+]

forgecore/core/constants.py

@@ -0,0 +1,7 @@
+PACKAGE_NAME = "forgecore"
+
+DEFAULT_ENCODING = "utf-8"
+
+DEFAULT_TIMEOUT = 30
+
+MAX_RETRIES = 3

forgecore/core/exceptions.py

@@ -0,0 +1,18 @@
+class ForgeCoreError(Exception):
+    pass
+
+
+class ConfigurationError(ForgeCoreError):
+    pass
+
+
+class ValidationError(ForgeCoreError):
+    pass
+
+
+class InitializationError(ForgeCoreError):
+    pass
+
+
+class UnsupportedPlatformError(ForgeCoreError):
+    pass

forgecore/core/types.py

@@ -0,0 +1,4 @@
+from typing import Any, TypeAlias
+
+JSON: TypeAlias = dict[str, Any]
+JSONList: TypeAlias = list[JSON]

forgecore/core/version.py

@@ -0,0 +1,3 @@
+VERSION = (0, 2, 0)
+
+__version__ = ".".join(map(str, VERSION))

forgecore/lifecycle/__init__.py

@@ -0,0 +1,7 @@
+from .manager import LifecycleManager
+from .state import LifecycleState
+
+__all__ = [
+    "LifecycleManager",
+    "LifecycleState",
+]

forgecore/lifecycle/manager.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from .state import LifecycleState
+
+Hook = Callable[[], None]
+
+
+class LifecycleManager:
+    def __init__(self) -> None:
+        self._state = LifecycleState.INITIALIZED
+        self._on_start_hooks: list[Hook] = []
+        self._on_stop_hooks: list[Hook] = []
+
+    @property
+    def state(self) -> LifecycleState:
+        return self._state
+
+    def on_start(self, hook: Hook) -> None:
+        self._on_start_hooks.append(hook)
+
+    def on_stop(self, hook: Hook) -> None:
+        self._on_stop_hooks.append(hook)
+
+    def start(self) -> None:
+        self._state = LifecycleState.STARTING
+        for hook in self._on_start_hooks:
+            hook()
+
+    def run(self) -> None:
+        self._state = LifecycleState.RUNNING
+
+    def stop(self) -> None:
+        self._state = LifecycleState.STOPPING
+        for hook in reversed(self._on_stop_hooks):
+            hook()
+
+    def shutdown(self) -> None:
+        self._state = LifecycleState.STOPPED

forgecore/lifecycle/state.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from enum import Enum
+
+
+class LifecycleState(str, Enum):
+    INITIALIZED = "initialized"
+    STARTING = "starting"
+    RUNNING = "running"
+    STOPPING = "stopping"
+    STOPPED = "stopped"

forgecore/logging/__init__.py

@@ -0,0 +1,5 @@
+from .logger import get_logger
+
+__all__ = [
+    "get_logger",
+]

forgecore/logging/logger.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import logging
+import sys
+
+_FORMAT = "[%(asctime)s] %(levelname)s %(name)s: %(message)s"
+
+
+def get_logger(name: str) -> logging.Logger:
+    logger = logging.getLogger(name)
+
+    if logger.handlers:
+        return logger
+
+    logger.setLevel(logging.INFO)
+
+    handler = logging.StreamHandler(sys.stdout)
+    handler.setFormatter(logging.Formatter(_FORMAT))
+
+    logger.addHandler(handler)
+    logger.propagate = False
+
+    return logger

forgecore/plugins/__init__.py

@@ -0,0 +1,7 @@
+from .manager import PluginManager
+from .plugin import Plugin
+
+__all__ = [
+    "Plugin",
+    "PluginManager",
+]

forgecore/plugins/manager.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from forgecore.context import ApplicationContext
+
+from .plugin import Plugin
+
+
+class PluginManager:
+    def __init__(self, context: ApplicationContext) -> None:
+        self._context = context
+        self._plugins: dict[str, Plugin] = {}
+
+    def register(self, plugin: Plugin) -> None:
+        self._plugins[plugin.name] = plugin
+
+    def unregister(self, name: str) -> None:
+        self._plugins.pop(name, None)
+
+    def get(self, name: str) -> Plugin | None:
+        return self._plugins.get(name)
+
+    def all(self) -> tuple[Plugin, ...]:
+        return tuple(self._plugins.values())
+
+    def start_all(self) -> None:
+        for plugin in self._plugins.values():
+            plugin.start(self._context)
+
+    def stop_all(self) -> None:
+        for plugin in reversed(tuple(self._plugins.values())):
+            plugin.stop(self._context)

forgecore/plugins/plugin.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from forgecore.context import ApplicationContext
+
+
+class Plugin(ABC):
+    @property
+    @abstractmethod
+    def name(self) -> str: ...
+
+    @property
+    @abstractmethod
+    def version(self) -> str: ...
+
+    @abstractmethod
+    def start(self, context: ApplicationContext) -> None: ...
+
+    @abstractmethod
+    def stop(self, context: ApplicationContext) -> None: ...

forgecore/providers/__init__.py

@@ -0,0 +1,5 @@
+from .provider import ServiceProvider
+
+__all__ = [
+    "ServiceProvider",
+]

forgecore/providers/provider.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from forgecore.services import ServiceContainer
+
+
+class ServiceProvider(ABC):
+    @abstractmethod
+    def register(self, container: ServiceContainer) -> None:
+        """Register services into the container."""
+
+    def boot(self, container: ServiceContainer) -> None:
+        """Boot the provider."""

forgecore/registry/__init__.py

@@ -0,0 +1,7 @@
+from .exceptions import RegistryKeyError
+from .registry import Registry
+
+__all__ = [
+    "Registry",
+    "RegistryKeyError",
+]

forgecore/registry/exceptions.py

@@ -0,0 +1,2 @@
+class RegistryKeyError(KeyError):
+    """Raised when a registry key cannot be found."""

forgecore/registry/registry.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .exceptions import RegistryKeyError
+
+
+class Registry:
+    def __init__(self) -> None:
+        self._items: dict[str, Any] = {}
+
+    def register(self, key: str, value: Any) -> None:
+        self._items[key] = value
+
+    def get(self, key: str) -> Any:
+        try:
+            return self._items[key]
+        except KeyError as exc:
+            raise RegistryKeyError(f"Registry key '{key}' is not registered.") from exc
+
+    def contains(self, key: str) -> bool:
+        return key in self._items
+
+    def remove(self, key: str) -> None:
+        self._items.pop(key, None)
+
+    def clear(self) -> None:
+        self._items.clear()
+
+    def __len__(self) -> int:
+        return len(self._items)

forgecore/runtime/__init__.py

@@ -0,0 +1,9 @@
+from .bus import EventBus
+from .event import Event
+from .exceptions import EventError
+
+__all__ = [
+    "Event",
+    "EventBus",
+    "EventError",
+]

forgecore/runtime/bus.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Callable
+
+from .event import Event
+from .exceptions import EventError
+
+Listener = Callable[[Event], None]
+
+
+class EventBus:
+
+    def __init__(self) -> None:
+        self._listeners: dict[str, list[Listener]] = defaultdict(list)
+
+    def subscribe(
+        self,
+        event_name: str,
+        listener: Listener,
+    ) -> None:
+        self._listeners[event_name].append(listener)
+
+    def unsubscribe(
+        self,
+        event_name: str,
+        listener: Listener,
+    ) -> None:
+        if event_name in self._listeners:
+            self._listeners[event_name] = [
+                l for l in self._listeners[event_name] if l is not listener
+            ]
+
+    def emit(self, event: Event) -> None:
+        for listener in list(self._listeners[event.name]):
+            try:
+                listener(event)
+            except Exception as exc:
+                raise EventError(
+                    f"Listener failed for event '{event.name}': {exc}"
+                ) from exc
+
+    def has_listeners(self, event_name: str) -> bool:
+        return bool(self._listeners.get(event_name))
+
+    def clear(self, event_name: str | None = None) -> None:
+        if event_name is not None:
+            self._listeners.pop(event_name, None)
+        else:
+            self._listeners.clear()

forgecore/runtime/event.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True, frozen=True)
+class Event:
+    name: str
+    payload: dict[str, Any] = field(default_factory=dict)

forgecore/runtime/exceptions.py

@@ -0,0 +1,2 @@
+class EventError(Exception):
+    pass

forgecore/services/__init__.py

@@ -0,0 +1,20 @@
+from .autowire import constructor_dependencies
+from .container import ServiceContainer
+from .descriptor import ServiceDescriptor
+from .exceptions import CircularDependencyError, ServiceNotFoundError
+from .factory import ServiceFactory
+from .resolver import ServiceResolver
+from .scope import ServiceScope
+from .scope_context import ScopeContext
+
+__all__ = [
+    "ServiceContainer",
+    "ServiceNotFoundError",
+    "CircularDependencyError",
+    "ServiceScope",
+    "ServiceDescriptor",
+    "constructor_dependencies",
+    "ServiceResolver",
+    "ServiceFactory",
+    "ScopeContext",
+]

forgecore/services/autowire.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from inspect import signature
+from typing import Any
+
+
+def constructor_dependencies(cls: type[Any]) -> list[type[Any]]:
+    """
+    Return constructor dependencies from type annotations.
+    """
+
+    parameters = signature(cls.__init__).parameters.values()
+
+    dependencies: list[type[Any]] = []
+
+    for parameter in parameters:
+        if parameter.name == "self":
+            continue
+
+        if parameter.annotation is parameter.empty:
+            raise TypeError(
+                f"{cls.__name__}.{parameter.name} is missing a type annotation."
+            )
+
+        dependencies.append(parameter.annotation)
+
+    return dependencies

forgecore/services/container.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .descriptor import ServiceDescriptor
+from .exceptions import ServiceNotFoundError
+from .factory import ServiceFactory
+from .resolver import ServiceResolver
+from .scope import ServiceScope
+from .scope_context import ScopeContext
+
+
+class ServiceContainer:
+
+    def __init__(self) -> None:
+        self._services: dict[type[Any], ServiceDescriptor] = {}
+        self._bindings: dict[type[Any], type[Any]] = {}
+        self._resolver = ServiceResolver(self)
+
+    def register(
+        self,
+        service: Any,
+        *,
+        scope: ServiceScope = ServiceScope.SINGLETON,
+    ) -> None:
+        service_type = type(service)
+        self._services[service_type] = ServiceDescriptor(
+            service_type=service_type,
+            implementation=service_type,
+            scope=scope,
+            instance=service,
+        )
+
+    def bind(
+        self,
+        abstraction: type[Any],
+        implementation: type[Any],
+    ) -> None:
+        self._bindings[abstraction] = implementation
+
+    def singleton(
+        self,
+        service_type: type[Any],
+        factory: callable | None = None,
+    ) -> None:
+        descriptor = ServiceDescriptor(
+            service_type=service_type,
+            implementation=service_type,
+            scope=ServiceScope.SINGLETON,
+        )
+        if factory is not None:
+            descriptor.factory = ServiceFactory(factory)
+        self._services[service_type] = descriptor
+
+    def transient(
+        self,
+        service_type: type[Any],
+        factory: callable | None = None,
+    ) -> None:
+        descriptor = ServiceDescriptor(
+            service_type=service_type,
+            implementation=service_type,
+            scope=ServiceScope.TRANSIENT,
+        )
+        if factory is not None:
+            descriptor.factory = ServiceFactory(factory)
+        self._services[service_type] = descriptor
+
+    def scoped(
+        self,
+        service_type: type[Any],
+        factory: callable | None = None,
+    ) -> None:
+        descriptor = ServiceDescriptor(
+            service_type=service_type,
+            implementation=service_type,
+            scope=ServiceScope.SCOPED,
+        )
+        if factory is not None:
+            descriptor.factory = ServiceFactory(factory)
+        self._services[service_type] = descriptor
+
+    def begin_scope(self) -> ScopeContext:
+        return self._resolver.begin_scope()
+
+    def end_scope(self) -> None:
+        self._resolver.end_scope()
+
+    def get(self, service_type: type[Any]) -> Any:
+        return self._resolver.resolve(service_type)
+
+    def resolve(self, service_type: type[Any]) -> Any:
+        return self._resolver.resolve(service_type)
+
+    def contains(self, service_type: type[Any]) -> bool:
+        return service_type in self._services
+
+    def clear(self) -> None:
+        self._services.clear()
+        self._bindings.clear()
+
+    def __len__(self) -> int:
+        return len(self._services)

forgecore/services/descriptor.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from .factory import ServiceFactory
+from .scope import ServiceScope
+
+
+@dataclass(slots=True)
+class ServiceDescriptor:
+    service_type: type[Any]
+    implementation: type[Any]
+    scope: ServiceScope = ServiceScope.SINGLETON
+    instance: Any | None = None
+    factory: ServiceFactory | None = None

forgecore/services/exceptions.py

@@ -0,0 +1,6 @@
+class ServiceNotFoundError(LookupError):
+    pass
+
+
+class CircularDependencyError(Exception):
+    pass

forgecore/services/factory.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+
+class ServiceFactory:
+    """
+    Wraps a callable used to create a service instance.
+    """
+
+    def __init__(
+        self,
+        factory: Callable[[Any], Any],
+    ) -> None:
+        self._factory = factory
+
+    def create(
+        self,
+        container: Any,
+    ) -> Any:
+        return self._factory(container)

forgecore/services/resolver.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import inspect
+import sys
+import threading
+import types
+import typing
+from typing import Any, get_type_hints
+
+from .exceptions import CircularDependencyError, ServiceNotFoundError
+from .scope import ServiceScope
+from .scope_context import ScopeContext
+
+
+def _is_optional(hint: Any) -> tuple[bool, Any]:
+    origin = typing.get_origin(hint)
+
+    if origin is typing.Union:
+        args = typing.get_args(hint)
+        non_none = [a for a in args if a is not type(None)]
+        if len(args) - len(non_none) > 0 and len(non_none) == 1:
+            return True, non_none[0]
+
+    if origin is types.UnionType:
+        args = typing.get_args(hint)
+        non_none = [a for a in args if a is not type(None)]
+        if len(args) - len(non_none) > 0 and len(non_none) == 1:
+            return True, non_none[0]
+
+    return False, hint
+
+
+class ServiceResolver:
+
+    def __init__(self, container: Any) -> None:
+        self._container = container
+        self._local = threading.local()
+
+    def _get_resolving(self) -> set[type[Any]]:
+        if not hasattr(self._local, "resolving"):
+            self._local.resolving = set()
+        return self._local.resolving
+
+    def _get_scope_context(self) -> ScopeContext | None:
+        return getattr(self._local, "scope_context", None)
+
+    def _set_scope_context(self, ctx: ScopeContext | None) -> None:
+        self._local.scope_context = ctx
+
+    def begin_scope(self) -> ScopeContext:
+        ctx = ScopeContext(on_exit=self.end_scope)
+        self._set_scope_context(ctx)
+        return ctx
+
+    def end_scope(self) -> None:
+        ctx = self._get_scope_context()
+        if ctx is not None:
+            ctx.clear()
+            self._set_scope_context(None)
+
+    def resolve(self, service_type: type[Any]) -> Any:
+
+        if service_type in self._container._bindings:
+            service_type = self._container._bindings[service_type]
+
+        resolving = self._get_resolving()
+
+        if service_type in resolving:
+            chain = " -> ".join(t.__name__ for t in resolving)
+            raise CircularDependencyError(
+                f"Circular dependency detected: {chain} -> {service_type.__name__}"
+            )
+
+        descriptor = self._container._services.get(service_type)
+
+        if descriptor is None:
+            raise ServiceNotFoundError(
+                f"Service '{service_type.__name__}' is not registered. "
+                f"Register it first using container.singleton(), "
+                f"container.transient(), or container.register()."
+            )
+
+        if (
+            descriptor.scope is ServiceScope.SINGLETON
+            and descriptor.instance is not None
+        ):
+            return descriptor.instance
+
+        scope_context = self._get_scope_context()
+
+        if descriptor.scope is ServiceScope.SCOPED:
+            if scope_context is None:
+                raise RuntimeError(
+                    f"Service '{service_type.__name__}' is SCOPED "
+                    f"but no active scope context. "
+                    f"Use container.begin_scope() first."
+                )
+            if scope_context.has(service_type):
+                return scope_context.get(service_type)
+
+        if descriptor.factory is not None:
+            instance = descriptor.factory.create(self._container)
+            if descriptor.scope is ServiceScope.SINGLETON:
+                descriptor.instance = instance
+            elif descriptor.scope is ServiceScope.SCOPED and scope_context:
+                scope_context.set(service_type, instance)
+            return instance
+
+        resolving.add(service_type)
+
+        try:
+            module = sys.modules.get(descriptor.implementation.__module__, None)
+            globalns = getattr(module, "__dict__", {})
+
+            try:
+                hints = get_type_hints(
+                    descriptor.implementation.__init__,
+                    globalns=globalns,
+                )
+            except Exception:
+                hints = {}
+
+            sig = inspect.signature(descriptor.implementation.__init__)
+            kwargs: dict[str, Any] = {}
+
+            for name, parameter in sig.parameters.items():
+                if name == "self":
+                    continue
+
+                if parameter.kind in (
+                    inspect.Parameter.VAR_POSITIONAL,
+                    inspect.Parameter.VAR_KEYWORD,
+                ):
+                    continue
+
+                dep_type = hints.get(name)
+
+                if dep_type is None:
+                    raise TypeError(
+                        f"Parameter '{name}' pada "
+                        f"'{descriptor.implementation.__name__}' "
+                        f"tidak memiliki type annotation."
+                    )
+
+                is_optional, inner_type = _is_optional(dep_type)
+
+                if is_optional:
+                    if self._container.contains(inner_type):
+                        kwargs[name] = self.resolve(inner_type)
+                    else:
+                        kwargs[name] = None
+                else:
+                    kwargs[name] = self.resolve(dep_type)
+
+            instance = descriptor.implementation(**kwargs)
+
+        finally:
+            resolving.discard(service_type)
+
+        if descriptor.scope is ServiceScope.SINGLETON:
+            descriptor.instance = instance
+        elif descriptor.scope is ServiceScope.SCOPED and scope_context:
+            scope_context.set(service_type, instance)
+
+        return instance

forgecore/services/scope.py

@@ -0,0 +1,7 @@
+from enum import Enum
+
+
+class ServiceScope(str, Enum):
+    SINGLETON = "singleton"
+    TRANSIENT = "transient"
+    SCOPED = "scoped"

forgecore/services/scope_context.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+
+class ScopeContext:
+
+    def __init__(self, on_exit: Callable[[], None] | None = None) -> None:
+        self._instances: dict[type[Any], Any] = {}
+        self._on_exit = on_exit
+
+    def has(self, service_type: type[Any]) -> bool:
+        return service_type in self._instances
+
+    def get(self, service_type: type[Any]) -> Any:
+        return self._instances[service_type]
+
+    def set(self, service_type: type[Any], instance: Any) -> None:
+        self._instances[service_type] = instance
+
+    def clear(self) -> None:
+        self._instances.clear()
+
+    def __enter__(self) -> ScopeContext:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.clear()
+        if self._on_exit is not None:
+            self._on_exit()

forgecore/utils/__init__.py

@@ -0,0 +1,9 @@
+from .inspect import package_version
+from .system import machine, operating_system, python_version
+
+__all__ = [
+    "package_version",
+    "python_version",
+    "operating_system",
+    "machine",
+]

forgecore/utils/inspect.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from importlib.metadata import version
+
+
+def package_version(package: str) -> str:
+    return version(package)

forgecore/utils/system.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+import platform
+
+
+def python_version() -> str:
+    return platform.python_version()
+
+
+def operating_system() -> str:
+    return platform.system()
+
+
+def machine() -> str:
+    return platform.machine()

forgecore/validation/__init__.py

@@ -0,0 +1,15 @@
+from .validators import (
+    is_boolean,
+    is_float,
+    is_integer,
+    is_non_empty_string,
+    is_string,
+)
+
+__all__ = [
+    "is_string",
+    "is_integer",
+    "is_float",
+    "is_boolean",
+    "is_non_empty_string",
+]

forgecore/validation/validators.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+
+def is_string(value: object) -> bool:
+    return isinstance(value, str)
+
+
+def is_integer(value: object) -> bool:
+    return isinstance(value, int)
+
+
+def is_float(value: object) -> bool:
+    return isinstance(value, float)
+
+
+def is_boolean(value: object) -> bool:
+    return isinstance(value, bool)
+
+
+def is_non_empty_string(value: object) -> bool:
+    return isinstance(value, str) and bool(value.strip())

forgecore/version.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"