feat: add health module

Author: olivermeyer

ATTRIBUTIONS.md

@@ -273,6 +273,40 @@ without prior written permission from Aignostics GmbH.
 
 ```
 
+## annotated-types (0.7.0) - MIT License
+
+Reusable constraint types to use with typing.Annotated
+
+* URL: https://github.com/annotated-types/annotated-types
+* Author(s): Adrian Garcia Badaracco <1755071+adriangb@users.noreply.github.com>, Samuel Colvin <s@muelcolvin.com>, Zac Hatfield-Dodds <zac@zhd.dev>
+
+### License Text
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2022 the contributors
+
+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
@@ -5123,6 +5157,74 @@ Library for serializing and deserializing Python Objects to and from JSON and XM
 
 ```
 
+## pydantic (2.12.5) - UNKNOWN
+
+Data validation using Python type hints
+
+* URL: https://github.com/pydantic/pydantic
+* Author(s): Samuel Colvin <s@muelcolvin.com>, Eric Jolibois <em.jolibois@gmail.com>, Hasan Ramezani <hasan.r67@gmail.com>, Adrian Garcia Badaracco <1755071+adriangb@users.noreply.github.com>, Terrence Dorsey <terry@pydantic.dev>, David Montague <david@pydantic.dev>, Serge Matveenko <lig@countzero.co>, Marcelo Trylesinski <marcelotryle@gmail.com>, Sydney Runkle <sydneymarierunkle@gmail.com>, David Hewitt <mail@davidhewitt.io>, Alex Hall <alex.mojaki@gmail.com>, Victorien Plot <contact@vctrn.dev>, Douwe Maan <hi@douwe.me>
+
+### License Text
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2017 to present Pydantic Services Inc. and individual contributors.
+
+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.
+
+```
+
+## pydantic_core (2.41.5) - UNKNOWN
+
+Core functionality for Pydantic validation and serialization
+
+* URL: https://github.com/pydantic/pydantic-core
+* Author(s): Samuel Colvin <s@muelcolvin.com>, Adrian Garcia Badaracco <1755071+adriangb@users.noreply.github.com>, David Montague <david@pydantic.dev>, David Hewitt <mail@davidhewitt.dev>, Sydney Runkle <sydneymarierunkle@gmail.com>, Victorien Plot <contact@vctrn.dev>
+
+### License Text
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2022 Samuel Colvin
+
+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.
+
+```
+
 ## pyparsing (3.3.2) - UNKNOWN
 
 pyparsing - Classes and methods to define and execute parsing grammars
@@ -7747,6 +7849,40 @@ DEALINGS IN THE SOFTWARE.
 
 ```
 
+## typing-inspection (0.4.2) - UNKNOWN
+
+Runtime typing introspection tools
+
+* URL: https://github.com/pydantic/typing-inspection
+* Author(s): Victorien Plot <contact@vctrn.dev>
+
+### License Text
+
+```
+MIT License
+
+Copyright (c) Pydantic Services Inc. 2025 to present
+
+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.
+
+```
+
 ## typing_extensions (4.15.0) - UNKNOWN
 
 Backported and Experimental Type Hints for Python 3.9+

pyproject.toml

@@ -49,7 +49,9 @@ classifiers = [
 
 requires-python = ">=3.11, <3.15"
 
-dependencies = []
+dependencies = [
+    "pydantic>=2,<3",
+]
 
 [dependency-groups]
 dev = [

src/aignostics_foundry_core/AGENTS.md

@@ -8,21 +8,27 @@ This file provides an overview of all modules in `aignostics_foundry_core`, thei
 
 | Module | Purpose | Description |
 |--------|---------|-------------|
-| **greet** | Example module | Provides greeting functionality |
+| **health** | Service health checks | `Health` model and `HealthStatus` enum for tree-structured health status |
 
 ## Module Descriptions
 
 <!-- For each module, document its purpose, features, dependencies, and usage. -->
 
-### greet
+### health
 
-**Greeting functionality for Foundry Python Core**
+**Tree-structured health status for service health checks**
 
-- **Purpose**: Provides greeting utilities
-- **Key Features**: Simple greeting with logging
-- **Location**: `aignostics_foundry_core/greet.py`
-
-<!-- Add descriptions for additional modules as you develop them -->
+- **Purpose**: Provides `Health` and `HealthStatus` for modelling UP / DEGRADED / DOWN status across a tree of service components
+- **Key Features**:
+  - `HealthStatus(StrEnum)` — `UP`, `DEGRADED`, `DOWN` values
+  - `Health(BaseModel)` — pydantic model with `status`, `reason`, `components`, `uptime_statistics`
+  - `compute_health_from_components()` — recursively propagates DOWN/DEGRADED from children to parent (DOWN trumps DEGRADED)
+  - `validate_health_state()` — model validator: DOWN/DEGRADED require a reason; UP must not have one
+  - `__str__` — returns `"UP"`, `"DEGRADED: <reason>"`, or `"DOWN: <reason>"`
+  - `__bool__` — `True` iff status is `UP`
+  - `Health.Code` — `ClassVar` alias for `HealthStatus` (convenience)
+- **Location**: `aignostics_foundry_core/health.py`
+- **Dependencies**: `pydantic>=2`
 
 ## Architecture
 
@@ -34,30 +40,37 @@ This file provides an overview of all modules in `aignostics_foundry_core`, thei
 -->
 
 ```text
-<!-- Example architecture diagram (customize for your project):
-
 ┌─────────────────────────────┐
 │     Your Application        │
 └──────────────┬──────────────┘
                │
 ┌──────────────┴──────────────┐
-│      aignostics_foundry_core      │
+│    aignostics_foundry_core  │
 ├─────────────────────────────┤
-│  module_a  │  module_b  │   │
+│           health            │
 └─────────────────────────────┘
--->
 ```
 
 ## Usage Examples
 
-<!-- Document common usage patterns for your package -->
-
 ```python
-from aignostics_foundry_core import greet
-
-# Example usage
-result = greet("World")
-print(result)  # Hello, World!
+from aignostics_foundry_core import Health, HealthStatus
+
+# Simple UP status
+health = Health(status=HealthStatus.UP)
+assert bool(health)  # True
+assert str(health) == "UP"
+
+# Composite health — DOWN propagates from components automatically
+system = Health(
+    status=HealthStatus.UP,
+    components={
+        "db": Health(status=HealthStatus.UP),
+        "cache": Health(status=HealthStatus.DOWN, reason="Connection refused"),
+    },
+)
+assert system.status == HealthStatus.DOWN
+assert "cache" in system.reason
 ```
 
 ## Development Guidelines

src/aignostics_foundry_core/__init__.py

@@ -1,5 +1,5 @@
 """Foundational infrastructure for Foundry components."""
 
-from .greet import greet
+from .health import Health, HealthStatus
 
-__all__ = ["greet"]
+__all__ = ["Health", "HealthStatus"]