geochat-kernel 1.0.0__tar.gz

geochat_kernel-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Araz Shah
+
+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, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

geochat_kernel-1.0.0/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.4
+Name: geochat-kernel
+Version: 1.0.0
+Summary: Enterprise Orchestration Engine for GeoChat Spatial AI
+Author: Araz Shah
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/arazshah/geochat-platform
+Project-URL: Repository, https://github.com/arazshah/geochat-platform
+Project-URL: Issues, https://github.com/arazshah/geochat-platform/issues
+Keywords: geospatial,gis,orchestration,spatial-analysis,geoai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: uvicorn>=0.20.0
+Requires-Dist: networkx>=3.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: jinja2>=3.0.0
+Dynamic: license-file
+
+# geochat-kernel
+
+Orchestration engine of [geochat-platform](https://github.com/arazshah/geochat-platform): contracts, domain models, registries, the cascading router, the DAG plan executor and the plugin loader.
+
+Plugins are usually written with [`geochat-sdk`](../geochat-sdk). See the [main README](../README.md) for the query flow and a runnable example.

geochat_kernel-1.0.0/README.md

@@ -0,0 +1,5 @@
+# geochat-kernel
+
+Orchestration engine of [geochat-platform](https://github.com/arazshah/geochat-platform): contracts, domain models, registries, the cascading router, the DAG plan executor and the plugin loader.
+
+Plugins are usually written with [`geochat-sdk`](../geochat-sdk). See the [main README](../README.md) for the query flow and a runnable example.

geochat_kernel-1.0.0/geochat_kernel/__init__.py

@@ -0,0 +1,32 @@
+# geochat_kernel/__init__.py
+from __future__ import annotations
+
+# Must match [project].version in ../pyproject.toml - that file is the
+# source of truth for what PyPI publishes, and a mismatch here makes every
+# installation report the wrong runtime version to consumers.
+__version__ = "1.0.0"
+
+from geochat_kernel.bootstrap import (
+    PluginLoadFailure,
+    PluginLoader,
+    PluginLoadResult,
+    load_plugins_from_folder,
+)
+from geochat_kernel.runtime import (
+    ExecutionContext,
+    KernelAppContainer,
+    QueryPipeline,
+    UserLocation,
+)
+
+__all__ = [
+    "__version__",
+    "PluginLoadFailure",
+    "PluginLoader",
+    "PluginLoadResult",
+    "load_plugins_from_folder",
+    "ExecutionContext",
+    "KernelAppContainer",
+    "QueryPipeline",
+    "UserLocation",
+]

geochat_kernel-1.0.0/geochat_kernel/bootstrap/__init__.py

@@ -0,0 +1,16 @@
+# geochat_kernel/bootstrap/__init__.py
+from __future__ import annotations
+
+from geochat_kernel.bootstrap.plugin_loader import (
+    PluginLoadFailure,
+    PluginLoader,
+    PluginLoadResult,
+    load_plugins_from_folder,
+)
+
+__all__ = [
+    "PluginLoadFailure",
+    "PluginLoader",
+    "PluginLoadResult",
+    "load_plugins_from_folder",
+]

geochat_kernel-1.0.0/geochat_kernel/bootstrap/plugin_loader.py

@@ -0,0 +1,396 @@
+# geochat_kernel/bootstrap/plugin_loader.py
+from __future__ import annotations
+
+import hashlib
+import importlib.util
+import inspect
+import sys
+import types
+from pathlib import Path
+from types import ModuleType
+from typing import Any
+
+from pydantic import Field
+
+from geochat_kernel.contracts.plugin import BasePlugin
+from geochat_kernel.errors import KernelPluginError
+from geochat_kernel.models.base import KernelModel
+from geochat_kernel.runtime.app_container import KernelAppContainer
+
+
+_DYNAMIC_PLUGIN_PACKAGE = "_geochat_dynamic_plugins"
+
+
+class PluginLoadFailure(KernelModel):
+    """Information about a plugin/module that failed during discovery/import."""
+
+    source: str
+    stage: str
+    error_type: str
+    message: str
+    details: dict[str, Any] = Field(default_factory=dict)
+
+
+class PluginLoadResult(KernelModel):
+    """
+    Result of plugin auto-discovery.
+
+    This is returned even if some plugins fail to load, unless strict=True.
+    """
+
+    plugins_folder: str
+    discovered_sources: list[str] = Field(default_factory=list)
+    loaded_plugin_ids: list[str] = Field(default_factory=list)
+    failures: list[PluginLoadFailure] = Field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return len(self.failures) == 0
+
+    @property
+    def loaded_count(self) -> int:
+        return len(self.loaded_plugin_ids)
+
+    @property
+    def failure_count(self) -> int:
+        return len(self.failures)
+
+
+class PluginLoader:
+    """
+    Auto-discovers trusted Python plugins from a folder.
+
+    Supported plugin shapes inside `plugins/`:
+
+    1) Single-file plugin:
+       plugins/my_plugin.py
+
+    2) Package plugin:
+       plugins/my_plugin/__init__.py
+
+    A plugin module/package can expose plugins using any of these patterns:
+
+    A) PLUGIN = MyPlugin()
+    B) PLUGINS = [PluginA(), PluginB()]
+    C) def get_plugin() -> BasePlugin
+    D) def get_plugins() -> list[BasePlugin]
+    E) zero-argument subclasses of BasePlugin defined in the module
+
+    Notes:
+    - Plugins are trusted Python code in MVP.
+    - Heavy dependencies like shapely/rasterio/numpy can exist inside plugins.
+      The kernel itself does not import those dependencies directly.
+    - Dependency order is NOT handled at import-time; it is handled later by
+      KernelAppContainer.initialize_plugins() using PluginManifest.dependencies.
+    """
+
+    def __init__(
+        self,
+        container: KernelAppContainer,
+        *,
+        plugins_folder: str | Path = "plugins",
+        strict: bool = False,
+    ) -> None:
+        self.container = container
+        self.plugins_folder = Path(plugins_folder)
+        self.strict = strict
+        self._ensure_dynamic_package()
+
+    async def discover_register_initialize(self) -> PluginLoadResult:
+        """
+        Discover plugins, register them in the container, then initialize them.
+
+        This is the most convenient method for app startup.
+        """
+        result = self.discover_and_register()
+        if result.failures and self.strict:
+            raise KernelPluginError(
+                "Plugin discovery failed.",
+                details=result.to_dict(),
+            )
+
+        await self.container.initialize_plugins()
+        return result
+
+    def discover_and_register(self) -> PluginLoadResult:
+        """
+        Discover plugins and register plugin objects in KernelAppContainer.
+
+        Does not call initialize_plugins(); caller can do that manually.
+        """
+        result = PluginLoadResult(plugins_folder=str(self.plugins_folder))
+
+        if not self.plugins_folder.exists():
+            if self.strict:
+                raise KernelPluginError(
+                    f"Plugins folder does not exist: {self.plugins_folder}",
+                    details={"plugins_folder": str(self.plugins_folder)},
+                )
+            return result
+
+        if not self.plugins_folder.is_dir():
+            raise KernelPluginError(
+                f"Plugins path is not a directory: {self.plugins_folder}",
+                details={"plugins_folder": str(self.plugins_folder)},
+            )
+
+        for source in self._iter_plugin_sources(self.plugins_folder):
+            result.discovered_sources.append(str(source))
+
+            try:
+                module = self._import_source(source)
+                plugins = self._extract_plugins(module)
+
+                if not plugins:
+                    result.failures.append(
+                        PluginLoadFailure(
+                            source=str(source),
+                            stage="extract",
+                            error_type="NoPluginFound",
+                            message=(
+                                "No BasePlugin instance found. Expected PLUGIN, "
+                                "PLUGINS, get_plugin(), get_plugins(), or a "
+                                "zero-argument BasePlugin subclass."
+                            ),
+                        )
+                    )
+                    continue
+
+                for plugin in plugins:
+                    self.container.register_plugin(plugin)
+                    result.loaded_plugin_ids.append(plugin.id)
+
+            except Exception as exc:
+                failure = PluginLoadFailure(
+                    source=str(source),
+                    stage="discover_register",
+                    error_type=type(exc).__name__,
+                    message=str(exc),
+                )
+                result.failures.append(failure)
+
+                if self.strict:
+                    raise KernelPluginError(
+                        f"Failed to load plugin source: {source}",
+                        details=failure.to_dict(),
+                        cause=exc,
+                    ) from exc
+
+        return result
+
+    # ------------------------------------------------------------------ #
+    # Discovery                                                           #
+    # ------------------------------------------------------------------ #
+
+    @staticmethod
+    def _iter_plugin_sources(folder: Path) -> list[Path]:
+        """
+        Return direct plugin sources from a plugins folder.
+
+        Direct children only:
+        - *.py files except __init__.py and files starting with _
+        - directories containing __init__.py except directories starting with _
+        """
+        sources: list[Path] = []
+
+        for child in sorted(folder.iterdir(), key=lambda p: p.name):
+            if child.name.startswith("_"):
+                continue
+
+            if child.is_file():
+                if child.suffix == ".py" and child.name != "__init__.py":
+                    sources.append(child)
+                continue
+
+            if child.is_dir():
+                init_py = child / "__init__.py"
+                if init_py.exists() and init_py.is_file():
+                    sources.append(child)
+
+        return sources
+
+    # ------------------------------------------------------------------ #
+    # Import                                                              #
+    # ------------------------------------------------------------------ #
+
+    @staticmethod
+    def _ensure_dynamic_package() -> None:
+        """
+        Ensure the parent namespace package exists in sys.modules.
+
+        This allows loading plugin packages as:
+            _geochat_dynamic_plugins.<plugin_name_hash>
+        and makes relative imports inside plugin packages work.
+        """
+        if _DYNAMIC_PLUGIN_PACKAGE in sys.modules:
+            return
+
+        pkg = types.ModuleType(_DYNAMIC_PLUGIN_PACKAGE)
+        pkg.__path__ = []  # type: ignore[attr-defined]
+        sys.modules[_DYNAMIC_PLUGIN_PACKAGE] = pkg
+
+    def _import_source(self, source: Path) -> ModuleType:
+        if source.is_dir():
+            return self._import_package(source)
+        return self._import_file(source)
+
+    def _import_file(self, file_path: Path) -> ModuleType:
+        module_name = self._module_name_for_source(file_path)
+        spec = importlib.util.spec_from_file_location(module_name, file_path)
+
+        if spec is None or spec.loader is None:
+            raise KernelPluginError(
+                f"Could not create import spec for plugin file: {file_path}",
+                details={"file_path": str(file_path)},
+            )
+
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[module_name] = module
+        spec.loader.exec_module(module)
+        return module
+
+    def _import_package(self, package_dir: Path) -> ModuleType:
+        init_py = package_dir / "__init__.py"
+        module_name = self._module_name_for_source(package_dir)
+
+        spec = importlib.util.spec_from_file_location(
+            module_name,
+            init_py,
+            submodule_search_locations=[str(package_dir)],
+        )
+
+        if spec is None or spec.loader is None:
+            raise KernelPluginError(
+                f"Could not create import spec for plugin package: {package_dir}",
+                details={"package_dir": str(package_dir)},
+            )
+
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[module_name] = module
+        spec.loader.exec_module(module)
+        return module
+
+    @staticmethod
+    def _module_name_for_source(source: Path) -> str:
+        resolved = str(source.resolve())
+        digest = hashlib.sha1(resolved.encode("utf-8")).hexdigest()[:12]
+        safe_name = source.stem if source.is_file() else source.name
+        safe_name = "".join(ch if ch.isalnum() or ch == "_" else "_" for ch in safe_name)
+        return f"{_DYNAMIC_PLUGIN_PACKAGE}.{safe_name}_{digest}"
+
+    # ------------------------------------------------------------------ #
+    # Plugin extraction                                                   #
+    # ------------------------------------------------------------------ #
+
+    def _extract_plugins(self, module: ModuleType) -> list[BasePlugin]:
+        plugins: list[BasePlugin] = []
+
+        # A) PLUGIN = MyPlugin()
+        if hasattr(module, "PLUGIN"):
+            plugins.extend(self._coerce_plugin_value(getattr(module, "PLUGIN")))
+
+        # B) PLUGINS = [PluginA(), PluginB()]
+        if hasattr(module, "PLUGINS"):
+            plugins.extend(self._coerce_plugin_value(getattr(module, "PLUGINS")))
+
+        # C) get_plugin()
+        get_plugin = getattr(module, "get_plugin", None)
+        if callable(get_plugin):
+            plugins.extend(self._coerce_plugin_value(get_plugin()))
+
+        # D) get_plugins()
+        get_plugins = getattr(module, "get_plugins", None)
+        if callable(get_plugins):
+            plugins.extend(self._coerce_plugin_value(get_plugins()))
+
+        # E) zero-argument subclasses defined in this exact module
+        # Avoid duplicates by plugin id.
+        existing_ids = {p.id for p in plugins}
+
+        for _, obj in inspect.getmembers(module, inspect.isclass):
+            if obj is BasePlugin:
+                continue
+
+            if not issubclass(obj, BasePlugin):
+                continue
+
+            # only instantiate classes defined in this module, not imported ones
+            if obj.__module__ != module.__name__:
+                continue
+
+            try:
+                signature = inspect.signature(obj)
+                required_params = [
+                    p
+                    for p in signature.parameters.values()
+                    if p.default is inspect.Parameter.empty
+                    and p.kind
+                    in (
+                        inspect.Parameter.POSITIONAL_ONLY,
+                        inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                        inspect.Parameter.KEYWORD_ONLY,
+                    )
+                ]
+
+                if required_params:
+                    continue
+
+                instance = obj()
+                if instance.id not in existing_ids:
+                    plugins.append(instance)
+                    existing_ids.add(instance.id)
+
+            except TypeError:
+                continue
+
+        return plugins
+
+    @staticmethod
+    def _coerce_plugin_value(value: Any) -> list[BasePlugin]:
+        if value is None:
+            return []
+
+        if isinstance(value, BasePlugin):
+            return [value]
+
+        if isinstance(value, (list, tuple, set)):
+            plugins: list[BasePlugin] = []
+            for item in value:
+                if not isinstance(item, BasePlugin):
+                    raise KernelPluginError(
+                        "Plugin collection contains a non-BasePlugin item.",
+                        details={"item_type": type(item).__name__},
+                    )
+                plugins.append(item)
+            return plugins
+
+        raise KernelPluginError(
+            "Invalid plugin export value.",
+            details={"value_type": type(value).__name__},
+        )
+
+
+async def load_plugins_from_folder(
+    container: KernelAppContainer,
+    plugins_folder: str | Path = "plugins",
+    *,
+    strict: bool = False,
+    initialize: bool = True,
+) -> PluginLoadResult:
+    """
+    Convenience function for app startup.
+
+    Example:
+        container = KernelAppContainer()
+        result = await load_plugins_from_folder(container, "plugins")
+    """
+    loader = PluginLoader(
+        container,
+        plugins_folder=plugins_folder,
+        strict=strict,
+    )
+
+    if initialize:
+        return await loader.discover_register_initialize()
+
+    return loader.discover_and_register()

geochat_kernel-1.0.0/geochat_kernel/contracts/__init__.py

@@ -0,0 +1,50 @@
+# geochat_kernel/contracts/__init__.py
+from __future__ import annotations
+
+from geochat_kernel.contracts.artifact_builder import BaseArtifactBuilder
+from geochat_kernel.contracts.cache import BaseCache
+from geochat_kernel.contracts.geodata_provider import BaseGeodataProvider
+from geochat_kernel.contracts.hooks import HookContext
+from geochat_kernel.contracts.job_manager import BaseJobManager
+from geochat_kernel.contracts.router import (
+    BaseRouter,
+    RouterConfig,
+    RoutingRequest,
+)
+from geochat_kernel.contracts.llm_provider import BaseLLMProvider
+from geochat_kernel.contracts.parse_stage import BaseParseStage
+from geochat_kernel.contracts.plan_optimizer import BasePlanOptimizer
+from geochat_kernel.contracts.planner import BasePlanner
+from geochat_kernel.contracts.plugin import BasePlugin
+from geochat_kernel.contracts.query_parser import BaseQueryParser
+from geochat_kernel.contracts.ranker import BaseRanker
+from geochat_kernel.contracts.response_composer import BaseResponseComposer
+from geochat_kernel.contracts.result_fusion import BaseResultFusion
+from geochat_kernel.contracts.semantic_enricher import BaseSemanticEnricher
+from geochat_kernel.contracts.semantic_registry import BaseSemanticRegistry
+from geochat_kernel.contracts.step_handler import BaseStepHandler
+from geochat_kernel.contracts.tool import BaseTool
+
+__all__ = [
+    "BaseArtifactBuilder",
+    "BaseCache",
+    "BaseGeodataProvider",
+    "HookContext",
+    "BaseJobManager",
+    "BaseRouter",
+    "RouterConfig",
+    "RoutingRequest",
+    "BaseLLMProvider",
+    "BaseParseStage",
+    "BasePlanOptimizer",
+    "BasePlanner",
+    "BasePlugin",
+    "BaseQueryParser",
+    "BaseRanker",
+    "BaseResponseComposer",
+    "BaseResultFusion",
+    "BaseSemanticEnricher",
+    "BaseSemanticRegistry",
+    "BaseStepHandler",
+    "BaseTool",
+]

geochat_kernel-1.0.0/geochat_kernel/contracts/artifact_builder.py

@@ -0,0 +1,44 @@
+# geochat_kernel/contracts/artifact_builder.py
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+from geochat_kernel.models.geo_response import GeoResponse
+from geochat_kernel.models.query_ir import QueryIR
+
+if TYPE_CHECKING:
+    from geochat_kernel.runtime.execution_context import ExecutionContext
+
+
+class BaseArtifactBuilder(ABC):
+    """
+    Adds/derives user-facing artifacts from a GeoResponse.
+
+    Examples:
+    - create a MapLayer from features
+    - create a heatmap layer
+    - create a chart artifact from analytics
+    - attach a downloadable report artifact
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Unique artifact builder name."""
+
+    @property
+    def priority(self) -> int:
+        return 100
+
+    def can_build(self, response: GeoResponse, query_ir: QueryIR) -> bool:
+        return True
+
+    @abstractmethod
+    async def build(
+        self,
+        response: GeoResponse,
+        query_ir: QueryIR,
+        context: "ExecutionContext",
+    ) -> GeoResponse:
+        """Return response enriched with artifacts/layers."""

geochat_kernel-1.0.0/geochat_kernel/contracts/cache.py

@@ -0,0 +1,54 @@
+# geochat_kernel/contracts/cache.py
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class BaseCache(ABC):
+    """
+    Cache abstraction only.
+
+    The kernel defines the contract; implementations live outside the kernel:
+    memory, Redis, file cache, database, object storage, etc.
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Unique cache implementation name."""
+
+    async def initialize(self) -> None:
+        """Optional initialization."""
+
+    async def shutdown(self) -> None:
+        """Optional shutdown."""
+
+    @abstractmethod
+    async def get(self, key: str, *, namespace: str | None = None) -> Any | None:
+        """Return cached value or None."""
+
+    @abstractmethod
+    async def set(
+        self,
+        key: str,
+        value: Any,
+        *,
+        namespace: str | None = None,
+        ttl_s: float | None = None,
+    ) -> None:
+        """Store value."""
+
+    @abstractmethod
+    async def delete(self, key: str, *, namespace: str | None = None) -> None:
+        """Delete a cached value."""
+
+    async def exists(self, key: str, *, namespace: str | None = None) -> bool:
+        return await self.get(key, namespace=namespace) is not None
+
+    async def clear_namespace(self, namespace: str) -> None:
+        """
+        Optional bulk clear. Implementations may override.
+
+        Default is no-op because not all backends can efficiently support it.
+        """

geochat_kernel-1.0.0/geochat_kernel/contracts/geodata_provider.py

@@ -0,0 +1,35 @@
+# geochat_kernel/contracts/geodata_provider.py
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from geochat_kernel.models.datasource import DataSourceDescriptor
+
+
+class BaseGeodataProvider(ABC):
+    """
+    Data provider abstraction.
+
+    Providers expose data source metadata and optional lifecycle/health hooks.
+    Actual step execution is handled by StepHandlers, which may internally use
+    providers, tools, remote services, or anything else.
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Unique provider name."""
+
+    @abstractmethod
+    def get_descriptor(self) -> DataSourceDescriptor:
+        """Return source descriptor."""
+
+    async def initialize(self) -> None:
+        """Optional provider initialization."""
+
+    async def shutdown(self) -> None:
+        """Optional provider shutdown."""
+
+    async def healthcheck(self) -> bool:
+        """Optional healthcheck."""
+        return True