This README.md is designed to be the definitive guide for your team. It explains the "Why" and the "How," shifting the focus from manual configuration to a Foundation-first approach.
GuardianHub SDK (Foundation)
Welcome to the core backbone of the GuardianHub ecosystem. This SDK is designed to provide Zero-Config capabilities for all microservices. By using this library, your service automatically inherits our standards for configuration, logging, and observability.
🚀 The "One-Minute" Setup
The goal of this SDK is to allow you to focus on business logic. You no longer need to manage config.json files or manually set up OpenTelemetry.
1. Installation
pip install guardianhub-sdk
2. Implementation
In your microservice's main.py, simply call the initialization utility:
from fastapi import FastAPI
from guardianhub.utils.fastapi_utils import initialize_guardian_service
from guardianhub import settings
app = FastAPI(title="My Service")
# This single call configures:
# - Environment-aware settings (K8s vs Local)
# - JSON Logging
# - Prometheus Metrics (/metrics)
# - Health Checks (/health)
# - OpenTelemetry Tracing (to Langfuse & OTEL Collector)
initialize_guardian_service(app)
@app.get("/task")
async def do_work():
# Use the pre-configured LLM client
# It already knows the Aura-LLM endpoint based on the environment
from guardianhub.clients import LLMClient
client = LLMClient()
return await client.generate("Hello world")
🛠 Configuration Philosophy
We have moved away from local config.json files in every repository. The SDK now uses a Hierarchical Provider system:
- SDK Defaults: Hardcoded "safe" fallbacks (usually
localhost). - Bundled Profiles: The SDK contains
config_dev.jsonandconfig_kubernetes-dev.json. It detects yourENVIRONMENTvariable and loads the correct infrastructure URLs automatically. - Environment Overrides: Any setting can be overridden using the
GH_prefix.
- Example: To change the LLM temperature without code changes, set
GH_LLM__TEMPERATURE=0.7. - Example: To point to a specific Vector DB, set
GH_ENDPOINTS__VECTOR_SERVICE_URL=http://my-db:8005.
Standard Endpoints
Every service using initialize_guardian_service(app) exposes:
GET /health: Returns uptime, version, environment, and active request count.GET /metrics: Prometheus-compatible metrics.
📊 Observability & Tracing
The SDK automatically instruments both incoming FastAPI requests and outgoing HTTPX calls.
- Trace Propagation: Traces automatically flow from Service A to Service B via W3C headers.
- Langfuse Integration: Traces are sent to the centralized Langfuse instance for LLM monitoring.
- Excluded URLs: Health checks and metrics endpoints are automatically filtered out of your traces to keep them clean.
🛡️ Best Practices for the Team
- No Local Configs: Do not create
config.jsonin your service repo. If an endpoint is missing, update it in the SDK and bump the version. - Use the
settingsobject: Never useos.getenvdirectly for shared infra. Usefrom guardianhub import settings. - Secrets: Sensitive keys (Postgres passwords, API keys) should be injected via K8s Secrets into environment variables following the
GH_pattern.
To explain this to the team, you need to highlight that we’ve moved from "Hardcoded Configuration" to "Dynamic Parameters." The SDK now acts as a smart proxy. It doesn't just hold values; it resolves them based on where the code is running. Here is the detailed breakdown of how we manage parameters in the CoreSettings system.
1. The Parameter Hierarchy (The "Resolution Chain")
When a developer calls settings.endpoints.VECTOR_SERVICE_URL, the SDK looks for the value in this specific order. The first one it finds wins.
| Priority | Source | Use Case |
|---|---|---|
| 1 (Highest) | Environment Variables | Injecting Secrets (DB Passwords) or emergency overrides. |
| 2 | Direct Code Initialization | Used mostly in unit tests to mock behavior. |
| 3 | Bundled JSON Profiles | The Backbone. Defines where internal services live in K8s. |
| 4 (Lowest) | Python Class Defaults | The safety net. Usually points to localhost. |
2. Parameter Grouping (The "Pillars")
We don't have a flat list of 50 variables. We group parameters into Pillars so the team can find what they need via autocompletion.
A. The service Pillar
Defines "Who am I?"
settings.service.name: Used for Logging and Jaeger/OTEL traces.settings.service.port: The port the internal server listens on.
B. The endpoints Pillar
Defines "Where is everyone else?"
- These are strictly URL strings.
- Note: We use
extra="allow"here. If you addNEW_AI_SERVICE_URLto the JSON, it is immediately available viasettings.endpoints.get("NEW_AI_SERVICE_URL")without needing an SDK code update.
C. The llm Pillar
Defines "How do I think?"
- Standardizes AI behavior across the fleet. If we decide
temperatureshould be0.2instead of0.1for the whole company, we change it here once.
3. Naming Convention for Overrides
To override a nested parameter via the environment (e.g., in a Dockerfile or K8s Manifest), we use the Double Underscore (__) convention.
Pattern: GH_[PILLAR]__[PARAMETER]
- To change the LLM model:
export GH_LLM__MODEL_NAME="gpt-4o" - To change the Vector URL:
export GH_ENDPOINTS__VECTOR_SERVICE_URL="http://custom-vector-db:8005" - To change Logging Level:
export GH_LOGGING__LEVEL="DEBUG"
4. How We Manage Secrets
Rule: No passwords or API Keys are ever stored in the config_*.json files.
The SDK defines the field in the LLMSettings or ServiceEndpoints class, but we leave the value as a placeholder. The team must map K8s Secrets to the corresponding GH_ environment variable:
# Kubernetes Deployment Example
env:
- name: GH_LLM__API_KEY
valueFrom:
secretKeyRef:
name: llm-secrets
key: api_key
5. Maintenance: Adding a New Parameter
If a service needs a new configuration parameter (e.g., RETRY_COUNT):
- Does it apply to everyone? Add it to
src/guardianhub/config/config_dev.jsonandconfig_kubernetes-dev.json. - Is it a new "Pillar"? Add a new
BaseModelclass insettings.py. - Is it just a URL? Just add it to the
endpointssection of the JSON files.
🛡️ Summary for the Team
"The SDK is the Backbone. The JSON files are the Maps. The Environment Variables are the Keys."
By following this, we ensure that if we move our entire infrastructure from AWS to Azure, or from one K8s namespace to another, we only update the JSON files in the SDK, and every microservice "teleports" to the new location on its next restart.
Would you like me to create a "Configuration Cheat Sheet" table that lists all current standard parameters and their default values for the team to print out?
🏗️ Contributing to the SDK
If you need to add a new shared client (e.g., Redis, S3) or a new endpoint:
- Add the endpoint to
src/guardianhub/config/config_*.json. - (Optional) Add a Pydantic model in
settings.pyif you want strict typing. - Bump the version using
./scripts/bump_version.sh. - Publish the new wheel.
Would you like me to generate a bootstrap_service.py script now, which your team can run to instantly generate a folder with this exact structure for a new microservice?
1 maintainer
Metadata
1 maintainer
Release files for guardianhub 0.1.665
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| guardianhub-0.1.665.tar.gz | 198.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| guardianhub-0.1.665-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 462.3 kB
Release files / guardianhub-0.1.665.tar.gz
| Download URL | guardianhub-0.1.665.tar.gz |
|---|---|
| Size | 198.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1fa33b4fbedf8517570febad5b9b5963fa8fabdb492dd191625fa736f446a481
|
|
BLAKE2b-256 checksum How to use checksums |
9242c0b8694712cf6c51a4f60f174345e236ee274c1b2489493b6ae963be0f9f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.
Transparency logRelease files / guardianhub-0.1.665-py3-none-any.whl
| Download URL | guardianhub-0.1.665-py3-none-any.whl |
|---|---|
| Size | 263.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6476346dd87a88994998ccc8f3d039284c0f1ac06728b2d937c7e8207633ee7b
|
|
BLAKE2b-256 checksum How to use checksums |
ebb51eddb89f4e469e5c28dc48cbcd6bf1aba1407f7b184a2171f40132f55d7d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 6, 2026.
Transparency log
