feat: port batch of modules from Bridge

.github/workflows/_package-publish.yml

@@ -73,4 +73,4 @@ jobs:
         with:
           method: chat.postMessage
           token: ${{ secrets.SLACK_RELEASE_BOT_TOKEN }}
-          payload: '{"channel":"#announce-foundry","text":"🚀 Foundry Python Core ${{ github.ref_name }} released","blocks":[{"type":"section","text":{"type":"mrkdwn","text":"🚀 *Foundry Python Core* <${{ github.server_url }}/${{ github.repository }}/releases/tag/${{ github.ref_name }}|${{ github.ref_name }}> released"}},{"type":"section","text":{"type":"mrkdwn","text":"${{ env.RELEASE_NOTES_CONTENT }}"}}]}'
+          payload: '{"channel":"#announce-foundry","text":"🚀 aignostics-foundry-core ${{ github.ref_name }} released","blocks":[{"type":"section","text":{"type":"mrkdwn","text":"🚀 *aignostics-foundry-core* <${{ github.server_url }}/${{ github.repository }}/releases/tag/${{ github.ref_name }}|${{ github.ref_name }}> released"}},{"type":"section","text":{"type":"mrkdwn","text":"${{ env.RELEASE_NOTES_CONTENT }}"}}]}'

.pre-commit-config.yaml

@@ -84,7 +84,7 @@ repos:
         pass_filenames: false
         always_run: true
         verbose: true
-        stages: [pre-push]
+        stages: [pre-commit]
       - id: test-unit
         name: Test (unit)
         entry: bash -c 'mise run test_unit'

ATTRIBUTIONS.md

@@ -286,6 +286,40 @@ SOFTWARE.
 
 ```
 
+## annotated-doc (0.0.4) - UNKNOWN
+
+Document parameters, class attributes, return types, and variables inline, with Annotated.
+
+* URL: https://github.com/fastapi/annotated-doc
+* Author(s): =?utf-8?q?Sebasti=C3=A1n_Ram=C3=ADrez?= <tiangolo@gmail.com>
+
+### License Text
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2025 Sebastián Ramírez
+
+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.
+
+```
+
 ## annotated-types (0.7.0) - MIT License
 
 Reusable constraint types to use with typing.Annotated
@@ -320,6 +354,39 @@ SOFTWARE.
 
 ```
 
+## anyio (4.13.0) - UNKNOWN
+
+High-level concurrency and networking framework on top of asyncio or Trio
+
+* URL: https://anyio.readthedocs.io/en/stable/versionhistory.html
+* Author(s): Alex Grönholm <alex.gronholm@nextday.fi>
+
+### License Text
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2018 Alex Grönholm
+
+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.
+
+```
+
 ## argcomplete (3.6.3) - Apache Software License
 
 Bash tab completion for argparse
@@ -2989,6 +3056,40 @@ execnet: rapid multi-Python deployment
 
 ```
 
+## fastapi (0.135.2) - UNKNOWN
+
+FastAPI framework, high performance, easy to learn, fast to code, ready for production
+
+* URL: https://github.com/fastapi/fastapi
+* Author(s): =?utf-8?q?Sebasti=C3=A1n_Ram=C3=ADrez?= <tiangolo@gmail.com>
+
+### License Text
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2018 Sebastián Ramírez
+
+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.
+
+```
+
 ## filelock (3.25.2) - MIT License
 
 A platform independent file lock.
@@ -3763,6 +3864,13 @@ license-expression is a comprehensive utility library to parse, compare, simplif
 
 ```
 
+## loguru (0.7.3) - MIT License
+
+Python logging made (stupidly) simple
+
+* URL: https://github.com/Delgan/loguru
+* Author(s): Delgan <delgan.py@gmail.com>
+
 ## lxml (6.0.2) - BSD-3-Clause
 
 Powerful and Pythonic XML processing library combining libxml2/libxslt with the ElementTree API.
@@ -4913,9 +5021,9 @@ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 ```
 
-## psutil (7.2.2) - BSD-3-Clause
+## psutil (6.1.1) - BSD License
 
-Cross-platform lib for process and system monitoring.
+Cross-platform lib for process and system monitoring in Python.
 
 * URL: https://github.com/giampaolo/psutil
 * Author(s): Giampaolo Rodola
@@ -7171,6 +7279,47 @@ limitations under the License.
 
 ```
 
+## starlette (1.0.0) - UNKNOWN
+
+The little ASGI library that shines.
+
+* URL: https://github.com/Kludex/starlette
+* Author(s): Tom Christie <tom@tomchristie.com>
+* Maintainer(s): Marcelo Trylesinski <marcelotryle@gmail.com>
+
+### License Text
+
+```
+Copyright © 2018, [Encode OSS Ltd](https://www.encode.io/).
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+```
+
 ## tabledata (1.3.4) - MIT License
 
 tabledata is a Python library to represent tabular data. Used for pytablewriter/pytablereader/SimpleSQLite/etc.

README.md

@@ -1,6 +1,6 @@
 # 🏭 Foundry Python Core
 
-[![License](https://img.shields.io/badge/license-Proprietary-A41831?labelColor=414042)](https://github.com/aignostics/foundry-python-core/blob/main/LICENSE)
+[![License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/aignostics/foundry-python-core/blob/main/LICENSE)
 [![CI](https://github.com/aignostics/foundry-python-core/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/aignostics/foundry-python-core/actions/workflows/ci-cd.yml)
 [![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=aignostics_foundry-python-core&metric=alert_status&token=a2fcb508f6d22af0c9d0a38728a7f5ee22d5b2ab)](https://sonarcloud.io/summary/new_code?id=aignostics_foundry-python-core)
 [![Security](https://sonarcloud.io/api/project_badges/measure?project=aignostics_foundry-python-core&metric=security_rating&token=a2fcb508f6d22af0c9d0a38728a7f5ee22d5b2ab)](https://sonarcloud.io/summary/new_code?id=aignostics_foundry-python-core)

pyproject.toml

@@ -49,6 +49,10 @@ classifiers = [
 requires-python = ">=3.11, <3.15"
 
 dependencies = [
+    "fastapi>=0.110,<1",
+    "loguru>=0.7,<1",
+    "platformdirs>=4,<5",
+    "psutil>=6",
     "pydantic>=2,<3",
     "pydantic-settings>=2,<3",
     "rich>=14,<15",

src/aignostics_foundry_core/AGENTS.md

@@ -8,6 +8,10 @@ This file provides an overview of all modules in `aignostics_foundry_core`, thei
 
 | Module | Purpose | Description |
 |--------|---------|-------------|
+| **models** | Shared output format enum | `OutputFormat` StrEnum with `YAML` and `JSON` values for use in CLI and API responses |
+| **process** | Current process introspection | `ProcessInfo`, `ParentProcessInfo` Pydantic models and `get_process_info()` for runtime process metadata; `SUBPROCESS_CREATION_FLAGS` for subprocess creation |
+| **api.exceptions** | API exception hierarchy and FastAPI handlers | `ApiException` (500), `NotFoundException` (404), `AccessDeniedException` (401); `api_exception_handler`, `unhandled_exception_handler`, `validation_exception_handler` for FastAPI registration |
+| **log** | Configurable loguru logging initialisation | `logging_initialize(project_name, version, env_file, filter_func)`, `LogSettings` (env-prefix configurable), `InterceptHandler` for stdlib-to-loguru bridging |
 | **console** | Themed terminal output | Module-level `console` object (Rich `Console`) with colour theme and `_get_console()` factory |
 | **di** | Dependency injection | `locate_subclasses`, `locate_implementations`, `load_modules`, `discover_plugin_packages`, `clear_caches`, `PLUGIN_ENTRY_POINT_GROUP` for plugin and subclass discovery |
 | **health** | Service health checks | `Health` model and `HealthStatus` enum for tree-structured health status |
@@ -17,6 +21,58 @@ This file provides an overview of all modules in `aignostics_foundry_core`, thei
 
 <!-- For each module, document its purpose, features, dependencies, and usage. -->
 
+### api.exceptions
+
+**API exception hierarchy and FastAPI exception handlers**
+
+- **Purpose**: Provides standardised HTTP exceptions and matching FastAPI exception handlers so all API errors return a consistent `{"success": false, "error": {"code": …, "message": …}}` envelope
+- **Key Features**:
+  - `ApiException(Exception)` — base API error; class-level `status_code = 500`, `message = "Unhandled API exception"`; both overridable via constructor kwargs
+  - `NotFoundException(ApiException)` — `status_code = 404`
+  - `AccessDeniedException(ApiException)` — `status_code = 401`
+  - `api_exception_handler(request, exc)` — maps `ApiException` to `JSONResponse` with `success: False` and structured error body
+  - `unhandled_exception_handler(request, exc)` — catches any `Exception`, logs at CRITICAL via loguru, returns 500
+  - `validation_exception_handler(request, exc)` — handles Pydantic `ValidationError` / FastAPI `RequestValidationError`; calls `.errors()` if available, returns 422
+- **Location**: `aignostics_foundry_core/api/exceptions.py`
+- **Dependencies**: `fastapi>=0.110,<1` (mandatory); `loguru` (used lazily inside `unhandled_exception_handler`)
+- **Import**: `from aignostics_foundry_core.api.exceptions import ApiException, NotFoundException, AccessDeniedException, api_exception_handler, unhandled_exception_handler, validation_exception_handler`
+
+### log
+
+**Configurable loguru logging initialisation**
+
+- **Purpose**: Bootstraps loguru as the primary logging framework, optionally redirecting stdlib `logging` via `InterceptHandler`. All project-specific constants are passed as parameters rather than hard-coded.
+- **Key Features**:
+  - `InterceptHandler(logging.Handler)` — redirects stdlib log records to loguru, preserving original module/function/line metadata
+  - `LogSettings(BaseSettings)` — reads from `FOUNDRY_LOG_*` env vars by default; override prefix and env file via constructor kwargs (e.g. `LogSettings(_env_prefix="BRIDGE_LOG_", _env_file=".env")`). Fields: `level`, `stderr_enabled`, `file_enabled`, `file_name`, `redirect_logging`
+  - `logging_initialize(project_name, version, env_file, filter_func)` — removes all existing loguru handlers, then adds stderr/file handlers per settings; embeds `project_name` and `version` in loguru `extra`; installs `InterceptHandler` for stdlib redirect; suppresses psycopg pool noise
+- **Location**: `aignostics_foundry_core/log.py`
+- **Dependencies**: `loguru>=0.7,<1`, `platformdirs>=4,<5` (mandatory)
+- **Import**: `from aignostics_foundry_core.log import logging_initialize, LogSettings, InterceptHandler`
+
+### models
+
+**Shared output format enum for CLI and API responses**
+
+- **Purpose**: Provides a single source of truth for supported output formats across all Foundry components
+- **Key Features**:
+  - `OutputFormat(StrEnum)` — `YAML = "yaml"`, `JSON = "json"`; each member is a plain `str` subtype, usable wherever a string format identifier is expected
+- **Location**: `aignostics_foundry_core/models.py`
+- **Dependencies**: Python stdlib only (`enum.StrEnum`, Python ≥ 3.11)
+
+### process
+
+**Current process introspection**
+
+- **Purpose**: Provides runtime process metadata for observability, diagnostics, and user-agent generation
+- **Key Features**:
+  - `ParentProcessInfo(BaseModel)` — `name` and `pid` of the parent process
+  - `ProcessInfo(BaseModel)` — `project_root`, `pid`, `parent`, and `cmdline` of the current process
+  - `get_process_info()` — returns a `ProcessInfo` for the running process (uses `psutil` lazily)
+  - `SUBPROCESS_CREATION_FLAGS` — platform-safe creation flags for `subprocess` calls (suppresses console window on Windows)
+- **Location**: `aignostics_foundry_core/process.py`
+- **Dependencies**: `psutil>=6` (mandatory)
+
 ### console
 
 **Themed Rich console for structured terminal output**

src/aignostics_foundry_core/api/__init__.py

@@ -0,0 +1,23 @@
+"""API sub-package for aignostics_foundry_core.
+
+Sub-modules:
+- exceptions: ApiException hierarchy and FastAPI exception handlers
+"""
+
+from .exceptions import (
+    AccessDeniedException,
+    ApiException,
+    NotFoundException,
+    api_exception_handler,
+    unhandled_exception_handler,
+    validation_exception_handler,
+)
+
+__all__ = [
+    "AccessDeniedException",
+    "ApiException",
+    "NotFoundException",
+    "api_exception_handler",
+    "unhandled_exception_handler",
+    "validation_exception_handler",
+]