ai4i-core 1.0.0__tar.gz

ai4i_core-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI4I Team
+
+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.

ai4i_core-1.0.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: ai4i-core
+Version: 1.0.0
+Summary: AI4I Core - consolidated utility libraries (exceptions, logging, telemetry, observability, bootstrap, email) for AI4I microservices
+Author-email: AI4Inclusion <support@ai4inclusion.org>
+License: MIT
+Project-URL: Homepage, https://github.com/COSS-India/ai4i-core
+Project-URL: Repository, https://github.com/COSS-India/ai4i-core
+Project-URL: Issues, https://github.com/COSS-India/ai4i-core/issues
+Project-URL: Source, https://github.com/COSS-India/ai4i-core/tree/master/libs/ai4i_core
+Keywords: ai4i,fastapi,logging,telemetry,observability,bootstrap,email,exceptions
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: FastAPI
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Logging
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.104.0
+Requires-Dist: starlette>=0.27.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: redis>=5.0.0
+Requires-Dist: sqlalchemy[asyncio]>=2.0.0
+Requires-Dist: slowapi>=0.1.9
+Requires-Dist: aiosmtplib<4.0.0,>=3.0.0
+Requires-Dist: jinja2<4.0.0,>=3.1.0
+Requires-Dist: python-json-logger>=2.0.7
+Requires-Dist: kafka-python>=2.0.2
+Requires-Dist: aiokafka>=0.8.0
+Requires-Dist: prometheus-client>=0.19.0
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: PyJWT>=2.8.0
+Requires-Dist: tritonclient[http]>=2.40.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: packaging>=21.0
+Requires-Dist: opentelemetry-api>=1.20.0
+Requires-Dist: opentelemetry-sdk>=1.20.0
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.41b0
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Dynamic: license-file
+
+# ai4i-core
+
+Consolidated utility libraries for AI4ICore microservices. A single installable package that bundles what used to live across ten standalone libraries — constants, env, exceptions, logging, telemetry, observability, model management, service base, bootstrap, and email.
+
+## Installation
+
+```bash
+pip install ai4i-core
+```
+
+## Subpackages
+
+| Subpackage | Purpose |
+| --- | --- |
+| `ai4i_core.bootstrap` | FastAPI app bootstrap helpers (cache, database, redis, schemas, versioning) |
+| `ai4i_core.constants` | Static error codes, messages, and back-compat re-exports |
+| `ai4i_core.email` | Provider-agnostic transactional email client (SMTP, console, pluggable) |
+| `ai4i_core.env` | Pydantic-based environment / settings |
+| `ai4i_core.exceptions` | Shared exception hierarchy, response envelope, FastAPI handlers |
+| `ai4i_core.logging` | Structured JSON logging with trace correlation |
+| `ai4i_core.model_management` | Model management client, Triton inference, FastAPI middleware |
+| `ai4i_core.observability` | Prometheus metrics, dashboards, middleware |
+| `ai4i_core.service_base` | App factory, health, rate limit, service registry, inference headers |
+| `ai4i_core.telemetry` | OpenTelemetry tracing, OpenSearch query clients |
+
+## Usage
+
+```python
+from ai4i_core.env import app_env
+from ai4i_core.logging import get_logger, register_logging_plugin
+from ai4i_core.exceptions import register_exception_handlers
+from ai4i_core.observability import ObservabilityPlugin, PluginConfig
+from ai4i_core.telemetry import register_telemetry_plugin, TelemetryConfig
+from ai4i_core.service_base import create_inference_app
+```
+
+See each subpackage's source for the full surface.
+
+## Requirements
+
+- Python `>= 3.11`
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Links
+
+- Source: <https://github.com/COSS-India/ai4i-core>
+- Issues: <https://github.com/COSS-India/ai4i-core/issues>

ai4i_core-1.0.0/README.md

@@ -0,0 +1,50 @@
+# ai4i-core
+
+Consolidated utility libraries for AI4ICore microservices. A single installable package that bundles what used to live across ten standalone libraries — constants, env, exceptions, logging, telemetry, observability, model management, service base, bootstrap, and email.
+
+## Installation
+
+```bash
+pip install ai4i-core
+```
+
+## Subpackages
+
+| Subpackage | Purpose |
+| --- | --- |
+| `ai4i_core.bootstrap` | FastAPI app bootstrap helpers (cache, database, redis, schemas, versioning) |
+| `ai4i_core.constants` | Static error codes, messages, and back-compat re-exports |
+| `ai4i_core.email` | Provider-agnostic transactional email client (SMTP, console, pluggable) |
+| `ai4i_core.env` | Pydantic-based environment / settings |
+| `ai4i_core.exceptions` | Shared exception hierarchy, response envelope, FastAPI handlers |
+| `ai4i_core.logging` | Structured JSON logging with trace correlation |
+| `ai4i_core.model_management` | Model management client, Triton inference, FastAPI middleware |
+| `ai4i_core.observability` | Prometheus metrics, dashboards, middleware |
+| `ai4i_core.service_base` | App factory, health, rate limit, service registry, inference headers |
+| `ai4i_core.telemetry` | OpenTelemetry tracing, OpenSearch query clients |
+
+## Usage
+
+```python
+from ai4i_core.env import app_env
+from ai4i_core.logging import get_logger, register_logging_plugin
+from ai4i_core.exceptions import register_exception_handlers
+from ai4i_core.observability import ObservabilityPlugin, PluginConfig
+from ai4i_core.telemetry import register_telemetry_plugin, TelemetryConfig
+from ai4i_core.service_base import create_inference_app
+```
+
+See each subpackage's source for the full surface.
+
+## Requirements
+
+- Python `>= 3.11`
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Links
+
+- Source: <https://github.com/COSS-India/ai4i-core>
+- Issues: <https://github.com/COSS-India/ai4i-core/issues>

ai4i_core-1.0.0/ai4i_core/__init__.py

@@ -0,0 +1,13 @@
+"""
+ai4i_core — Consolidated AI4I utility libraries.
+
+Subpackages:
+    bootstrap          — FastAPI app bootstrap helpers (cache, db, redis, schemas, versioning)
+    email              — Provider-agnostic transactional email client (SMTP, console, ...)
+    exceptions         — Shared exception hierarchy, response envelope, FastAPI handlers
+    logging            — Structured JSON logging with trace correlation
+    observability      — Prometheus metrics, middleware
+    telemetry          — OpenTelemetry tracing, OpenSearch query clients
+"""
+
+__version__ = "1.1.5"

ai4i_core-1.0.0/ai4i_core/bootstrap/__init__.py

@@ -0,0 +1,32 @@
+"""
+ai4icore_bootstrap — Infrastructure building blocks for ALL AI4I-Core microservices.
+
+Provides:
+- create_service_app() — single-call app factory
+- Database: init_database, close_database, get_db
+- Redis: init_redis, close_redis, get_redis
+- Rate limiting: setup_rate_limiting, limiter
+- Health: create_health_router
+- Caching: CacheService
+- Schemas: BaseSchema
+"""
+
+from .factory import create_service_app, ServiceConfig
+from .database import init_database, close_database, get_db, get_engine
+from .redis import init_redis, close_redis, get_redis, get_redis_client
+from .rate_limit import setup_rate_limiting, limiter
+from .health import create_health_router
+from .cache import CacheService
+from .schemas import BaseSchema
+from .versioning import APIVersioning, VersionInfo
+
+__all__ = [
+    "create_service_app", "ServiceConfig",
+    "init_database", "close_database", "get_db", "get_engine",
+    "init_redis", "close_redis", "get_redis", "get_redis_client",
+    "setup_rate_limiting", "limiter",
+    "create_health_router",
+    "CacheService",
+    "BaseSchema",
+    "APIVersioning", "VersionInfo",
+]

ai4i_core-1.0.0/ai4i_core/bootstrap/cache.py

@@ -0,0 +1,31 @@
+"""
+Shared Redis caching patterns for microservices.
+
+Provides generic key-value helpers on a single Redis connection (logical DB 0).
+"""
+
+import logging
+from typing import Optional
+
+import redis.asyncio as aioredis
+
+logger = logging.getLogger(__name__)
+
+
+class CacheService:
+    """Generic Redis caching operations on one client."""
+
+    def __init__(self, redis_client: aioredis.Redis) -> None:
+        self._redis = redis_client
+
+    async def set(self, key: str, value: str, ttl: int) -> None:
+        await self._redis.setex(key, ttl, value)
+
+    async def get(self, key: str) -> Optional[str]:
+        return await self._redis.get(key)
+
+    async def delete(self, key: str) -> None:
+        await self._redis.delete(key)
+
+    async def exists(self, key: str) -> bool:
+        return await self._redis.exists(key) > 0

ai4i_core-1.0.0/ai4i_core/bootstrap/database.py

@@ -0,0 +1,75 @@
+"""
+Async SQLAlchemy engine, session factory, and get_db dependency.
+
+Used by ALL microservices. No service-specific imports.
+"""
+
+import logging
+from collections.abc import AsyncGenerator
+
+from sqlalchemy.ext.asyncio import (
+    AsyncEngine,
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+
+logger = logging.getLogger(__name__)
+
+_engine: AsyncEngine | None = None
+_session_factory: async_sessionmaker[AsyncSession] | None = None
+
+
+def init_database(
+    db_url: str,
+    pool_size: int = 20,
+    max_overflow: int = 10,
+    echo: bool = False,
+) -> None:
+    """Create the async engine and session factory. Called during app startup."""
+    global _engine, _session_factory
+
+    logger.info("Connecting to database: %s", db_url.split("@")[-1])
+
+    _engine = create_async_engine(
+        db_url,
+        pool_size=pool_size,
+        max_overflow=max_overflow,
+        pool_pre_ping=True,
+        echo=echo,
+    )
+    _session_factory = async_sessionmaker(
+        bind=_engine,
+        class_=AsyncSession,
+        expire_on_commit=False,
+    )
+    logger.info("Database engine initialized.")
+
+
+async def close_database() -> None:
+    """Dispose of the engine. Called during app shutdown."""
+    global _engine, _session_factory
+    if _engine:
+        await _engine.dispose()
+        logger.info("Database engine disposed.")
+    _engine = None
+    _session_factory = None
+
+
+async def get_db() -> AsyncGenerator[AsyncSession, None]:
+    """FastAPI dependency that yields an async DB session."""
+    if _session_factory is None:
+        raise RuntimeError("Database not initialized. Call init_database() first.")
+    async with _session_factory() as session:
+        try:
+            yield session
+        except Exception:
+            await session.rollback()
+            raise
+
+
+def get_engine() -> AsyncEngine:
+    """Return the current engine (for Alembic / telemetry instrumentation)."""
+    if _engine is None:
+        raise RuntimeError("Database not initialized.")
+    return _engine

ai4i_core-1.0.0/ai4i_core/bootstrap/factory.py

@@ -0,0 +1,114 @@
+"""
+Service app factory — the single way to create a FastAPI app in AI4I-Core.
+
+Middleware execution order (LIFO — last added runs first on request):
+
+  CORSMiddleware               ← outermost: applies CORS headers before anything else
+  RequestMiddleware            ← seeds trace_id, logs the request
+  OTel / FastAPIInstrumentor   ← CorrelationPropagator reads trace_id here
+
+CORSMiddleware MUST be added last so it is outermost and CORS headers are
+applied even when inner middleware short-circuits the request.
+RequestMiddleware is added before CORSMiddleware so it still runs before OTel.
+"""
+
+import logging
+from dataclasses import dataclass, field
+from typing import Optional
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ServiceConfig:
+    service_name: str
+    version: str = "1.0.0"
+    description: str = ""
+    environment: str = "development"
+
+    cors_origins: list[str] = field(default_factory=lambda: ["*"])
+    hide_docs_in_production: bool = True
+
+    telemetry_enabled: bool = True
+    jaeger_endpoint: Optional[str] = None
+
+    log_level: str = "INFO"
+
+    telemetry_exclude_paths: set[str] = field(default_factory=lambda: {
+        "/health", "/ready", "/docs", "/redoc", "/openapi.json",
+    })
+
+
+def create_service_app(config: Optional[ServiceConfig] = None, **kwargs) -> FastAPI:
+    """Create a fully bootstrapped FastAPI application."""
+    if config is None:
+        config = ServiceConfig(**kwargs)
+
+    is_prod = config.environment in ("production", "staging")
+
+    app = FastAPI(
+        title=config.service_name,
+        version=config.version,
+        description=config.description or f"{config.service_name} microservice",
+        docs_url=None if (is_prod and config.hide_docs_in_production) else "/docs",
+        redoc_url=None if (is_prod and config.hide_docs_in_production) else "/redoc",
+        openapi_url=None if (is_prod and config.hide_docs_in_production) else "/openapi.json",
+    )
+
+    # ── 1. Exception handlers ──
+    try:
+        from ai4i_core.exceptions import register_exception_handlers
+        register_exception_handlers(app)
+    except ImportError:
+        pass
+
+    # ── 2. Configure logging ──
+    from ai4i_core.logging import configure_logging
+    configure_logging(service_name=config.service_name, log_level=config.log_level)
+
+    # ── 3. OTel instrumentation ──
+    if config.telemetry_enabled:
+        try:
+            from ai4i_core.telemetry import setup_tracing
+            setup_tracing(config.service_name, config.jaeger_endpoint)
+        except ImportError:
+            pass
+
+        try:
+            from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
+            FastAPIInstrumentor.instrument_app(
+                app,
+                excluded_urls=",".join(config.telemetry_exclude_paths),
+            )
+        except ImportError:
+            pass
+
+    # ── 4. Request middleware (seeds trace_id before OTel propagator runs) ──
+    from ai4i_core.logging import RequestMiddleware
+    app.add_middleware(RequestMiddleware)
+
+    # ── 5. CORS (outermost — added last, runs first) ──
+    allow_all = config.cors_origins == ["*"]
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=config.cors_origins,
+        allow_credentials=not allow_all,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # ── 6. Health endpoints ──
+    @app.get("/")
+    async def _root():
+        return {"service": config.service_name, "version": config.version, "status": "running"}
+
+    @app.get("/health")
+    async def _health():
+        return {"status": "healthy"}
+
+    app.state.service_config = config
+    logger.info("[bootstrap] %s v%s ready [%s]", config.service_name, config.version, config.environment)
+    return app

ai4i_core-1.0.0/ai4i_core/bootstrap/health.py

@@ -0,0 +1,64 @@
+"""
+Health and readiness endpoints.
+
+Used by ALL microservices. Returns 503 on probe failure (K8s compatible).
+"""
+
+import logging
+
+from fastapi import APIRouter, Depends
+from fastapi.responses import JSONResponse
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+import redis.asyncio as aioredis
+
+from .database import get_db
+from .redis import get_redis
+
+logger = logging.getLogger(__name__)
+
+
+def create_health_router(service_name: str = "service", version: str = "1.0.0") -> APIRouter:
+    """
+    Create a health router with /, /health, /ready endpoints.
+    The /ready endpoint checks DB and Redis connectivity.
+    """
+    router = APIRouter()
+
+    @router.get("/")
+    async def root():
+        return {"service": service_name, "version": version, "status": "running"}
+
+    @router.get("/health")
+    async def health():
+        return {"status": "healthy"}
+
+    @router.get("/ready")
+    async def readiness(
+        db: AsyncSession = Depends(get_db),
+        redis_client: aioredis.Redis = Depends(get_redis),
+    ):
+        checks: dict[str, str] = {}
+
+        try:
+            await db.execute(text("SELECT 1"))
+            checks["database"] = "ok"
+        except Exception as exc:
+            logger.warning("Readiness: database check failed: %s", exc)
+            checks["database"] = "unavailable"
+
+        try:
+            await redis_client.ping()
+            checks["redis"] = "ok"
+        except Exception as exc:
+            logger.warning("Readiness: redis check failed: %s", exc)
+            checks["redis"] = "unavailable"
+
+        all_ok = all(v == "ok" for v in checks.values())
+        return JSONResponse(
+            status_code=200 if all_ok else 503,
+            content={"success": True, "data": {"ready": all_ok, "checks": checks}},
+        )
+
+    return router

ai4i_core-1.0.0/ai4i_core/bootstrap/rate_limit.py

@@ -0,0 +1,38 @@
+"""
+Rate limiting using slowapi.
+
+Used by ALL microservices. Defense-in-depth alongside APISIX.
+"""
+
+from slowapi import Limiter
+from slowapi.util import get_remote_address
+from slowapi.errors import RateLimitExceeded
+from slowapi.middleware import SlowAPIMiddleware
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+limiter = Limiter(
+    key_func=get_remote_address,
+    default_limits=["200/minute"],
+    storage_uri="memory://",
+)
+
+
+def setup_rate_limiting(app: FastAPI) -> None:
+    """Register rate limiter and error handler on any FastAPI app."""
+    app.state.limiter = limiter
+    app.add_middleware(SlowAPIMiddleware)
+
+    @app.exception_handler(RateLimitExceeded)
+    async def _rate_limit_handler(request: Request, exc: RateLimitExceeded) -> JSONResponse:
+        return JSONResponse(
+            status_code=429,
+            content={
+                "success": False,
+                "error": {
+                    "code": "RATE_LIMIT_EXCEEDED",
+                    "message": f"Rate limit exceeded: {exc.detail}",
+                },
+            },
+        )

ai4i_core-1.0.0/ai4i_core/bootstrap/redis.py

@@ -0,0 +1,66 @@
+"""
+Redis client lifecycle and get_redis dependency.
+
+Used by ALL microservices. No service-specific imports.
+"""
+
+import logging
+from collections.abc import AsyncGenerator
+
+import redis.asyncio as aioredis
+
+logger = logging.getLogger(__name__)
+
+_redis_client: aioredis.Redis | None = None
+
+MAX_CONNECT_RETRIES = 3
+
+
+async def init_redis(
+    url: str,
+    socket_timeout: int = 10,
+) -> None:
+    """Create the async Redis client. Called during app startup."""
+    global _redis_client
+
+    logger.info("Connecting to Redis: %s", url.split("@")[-1] if "@" in url else url)
+
+    _redis_client = aioredis.from_url(
+        url,
+        socket_timeout=socket_timeout,
+        socket_connect_timeout=socket_timeout,
+        decode_responses=True,
+    )
+
+    for attempt in range(1, MAX_CONNECT_RETRIES + 1):
+        try:
+            await _redis_client.ping()
+            logger.info("Redis connection established.")
+            return
+        except (aioredis.ConnectionError, aioredis.TimeoutError) as exc:
+            logger.warning("Redis attempt %d/%d failed: %s", attempt, MAX_CONNECT_RETRIES, exc)
+            if attempt == MAX_CONNECT_RETRIES:
+                raise
+
+
+async def close_redis() -> None:
+    """Close the Redis connection. Called during app shutdown."""
+    global _redis_client
+    if _redis_client:
+        await _redis_client.aclose()
+        logger.info("Redis connection closed.")
+    _redis_client = None
+
+
+async def get_redis() -> AsyncGenerator[aioredis.Redis, None]:
+    """FastAPI dependency that yields the Redis client."""
+    if _redis_client is None:
+        raise RuntimeError("Redis not initialized. Call init_redis() first.")
+    yield _redis_client
+
+
+def get_redis_client() -> aioredis.Redis:
+    """Return the raw Redis client (for non-DI contexts)."""
+    if _redis_client is None:
+        raise RuntimeError("Redis not initialized.")
+    return _redis_client

ai4i_core-1.0.0/ai4i_core/bootstrap/schemas.py

@@ -0,0 +1,15 @@
+"""
+Base Pydantic schema for ALL microservices.
+"""
+
+from pydantic import BaseModel, ConfigDict
+
+
+class BaseSchema(BaseModel):
+    """Base schema for all request/response models across all services."""
+
+    model_config = ConfigDict(
+        from_attributes=True,
+        populate_by_name=True,
+        str_strip_whitespace=True,
+    )