aikit-platform 0.3.0__tar.gz

aikit_platform-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,15 @@
+name: ci
+on:
+  push: { branches: [main] }
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.11" }
+      - run: pip install -e ".[eval,dev]"
+      - run: ruff check .
+      - run: mypy src
+      - run: pytest -q

aikit_platform-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,16 @@
+name: release
+on:
+  push:
+    tags: ["v*"]
+permissions:
+  id-token: write        # PyPI trusted publishing (OIDC) — no API token needed
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "3.12" }
+      - run: pip install build hatchling
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

aikit_platform-0.3.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.env
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.DS_Store

aikit_platform-0.3.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+All notable changes follow [Keep a Changelog] and [SemVer].
+
+## [Unreleased]
+### Added
+- Public interfaces: ModelClient, EmbeddingService, JobQueue, MetricsSink,
+  BaseServiceSettings, DB base (stub).

aikit_platform-0.3.0/LICENSE

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

aikit_platform-0.3.0/Makefile

@@ -0,0 +1,6 @@
+.PHONY: install lint type test all
+install: ; pip install -e ".[dev]"
+lint:    ; ruff check .
+type:    ; mypy src
+test:    ; pytest -q
+all: lint type test

aikit_platform-0.3.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.5
+Name: aikit-platform
+Version: 0.3.0
+Summary: Shared platform layer for AI-backend systems: model client, embeddings, observability, config, db, queue.
+Project-URL: Homepage, https://github.com/Aaryan123456679/aikit
+Project-URL: Repository, https://github.com/Aaryan123456679/aikit
+Author: Aaryan Mahajan
+License: MIT
+License-File: LICENSE
+Keywords: embeddings,infrastructure,llm,observability
+Requires-Python: >=3.11
+Requires-Dist: pydantic-settings>=2.3
+Requires-Dist: pydantic>=2.7
+Provides-Extra: db
+Requires-Dist: asyncpg>=0.29; extra == 'db'
+Requires-Dist: pgvector>=0.3; extra == 'db'
+Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'db'
+Provides-Extra: dev
+Requires-Dist: aiosqlite>=0.20; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: embeddings
+Requires-Dist: sentence-transformers>=3.0; extra == 'embeddings'
+Provides-Extra: eval
+Requires-Dist: arq>=0.26; extra == 'eval'
+Requires-Dist: asyncpg>=0.29; extra == 'eval'
+Requires-Dist: httpx>=0.27; extra == 'eval'
+Requires-Dist: pgvector>=0.3; extra == 'eval'
+Requires-Dist: prometheus-client>=0.20; extra == 'eval'
+Requires-Dist: redis>=5.0; extra == 'eval'
+Requires-Dist: sentence-transformers>=3.0; extra == 'eval'
+Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'eval'
+Requires-Dist: structlog>=24.1; extra == 'eval'
+Provides-Extra: gateway
+Requires-Dist: asyncpg>=0.29; extra == 'gateway'
+Requires-Dist: httpx>=0.27; extra == 'gateway'
+Requires-Dist: pgvector>=0.3; extra == 'gateway'
+Requires-Dist: prometheus-client>=0.20; extra == 'gateway'
+Requires-Dist: redis>=5.0; extra == 'gateway'
+Requires-Dist: sentence-transformers>=3.0; extra == 'gateway'
+Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'gateway'
+Requires-Dist: structlog>=24.1; extra == 'gateway'
+Provides-Extra: http
+Requires-Dist: httpx>=0.27; extra == 'http'
+Provides-Extra: memory
+Requires-Dist: arq>=0.26; extra == 'memory'
+Requires-Dist: asyncpg>=0.29; extra == 'memory'
+Requires-Dist: httpx>=0.27; extra == 'memory'
+Requires-Dist: pgvector>=0.3; extra == 'memory'
+Requires-Dist: prometheus-client>=0.20; extra == 'memory'
+Requires-Dist: redis>=5.0; extra == 'memory'
+Requires-Dist: sentence-transformers>=3.0; extra == 'memory'
+Requires-Dist: sqlalchemy[asyncio]>=2.0; extra == 'memory'
+Requires-Dist: structlog>=24.1; extra == 'memory'
+Provides-Extra: observability
+Requires-Dist: prometheus-client>=0.20; extra == 'observability'
+Requires-Dist: structlog>=24.1; extra == 'observability'
+Provides-Extra: queue
+Requires-Dist: arq>=0.26; extra == 'queue'
+Requires-Dist: redis>=5.0; extra == 'queue'
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# aikit
+
+*The shared library behind three AI-backend services — see the [AI Infrastructure Suite overview](https://github.com/Aaryan123456679/ai-infrastructure-suite).*
+
+Shared platform layer for a suite of AI-backend systems (LLM eval platform,
+inference gateway, agent-memory service). Publishes clean, SOLID interfaces
+and reusable infrastructure so each downstream service depends on contracts,
+not implementations.
+
+## Modules
+| Module | Contract | Concrete implementation |
+|---|---|---|
+| `model_client` | `ModelClient` | `OllamaClient`, `HostedClient` (OpenAI-compatible) — `complete` / `stream` (text + terminal `Usage`) / `health` / `aclose` |
+| `embeddings` | `EmbeddingService` | `SentenceTransformerEmbeddingService` — local batched embeddings + cosine |
+| `db` | async SQLAlchemy `Base` | `make_engine` / `make_sessionmaker` / `session_scope` |
+| `jobqueue` | `JobQueue` | `ArqJobQueue` (Redis/arq) |
+| `observability` | `MetricsSink`, logging | `PrometheusMetricsSink`, structlog JSON |
+| `config` | `BaseServiceSettings` | env-driven |
+
+## Status
+
+**v0.1.0** validated end-to-end by `eval-platform`'s live Docker smoke test:
+a real Postgres migration + advisory-lock-guarded prompt versioning +
+CAS-guarded run finalization, a real Redis-backed arq worker actually
+dispatching jobs, and a real Ollama model producing a scored, completed run
+through the API. That process caught and fixed real bugs — not just code
+review findings:
+
+- `sentence-transformers` version drift breaking `EmbeddingService`'s
+  structural match (`dim` typed wider than `int` in a newer release).
+- `ArqJobQueue` never dispatched a single job — arq names a job function by
+  `coroutine.__qualname__`, not `__name__`, so every registration collided
+  under the same closure qualname regardless of task name.
+- CI installed only `dev` extras, so it silently only ever type-checked and
+  tested the core Protocol stubs, never the concrete implementations.
+
+**v0.2.0** (breaking: `stream()` now yields `str | Usage`, terminal `Usage`
+carries `tokens_in`/`tokens_out`/`finish_reason` — additive to `complete()`,
+`eval-platform` stays pinned at v0.1.0 and is unaffected since it never
+calls `stream()`). Adds `HostedClient` (OpenAI-compatible: OpenAI, Groq,
+Together, Fireworks, OpenRouter, ...) for `inference-gateway`. Both closed
+gaps `eval-platform`'s status page called out:
+
+- `OllamaClient.stream()` is now **live-validated** against a real running
+  Ollama server, including a production-sized model (`llama3.1:8b`, not
+  just the small model used for eval-platform's fast smoke run) — text
+  deltas followed by exactly one terminal `Usage`, asserted live and
+  pinned down as a regression test replaying the real captured response.
+- `HostedClient` is new and mock-tested against the OpenAI-compatible wire
+  format (including the `stream_options.include_usage` SSE shape); it has
+  **not** been live-validated against a real hosted provider (needs a real
+  API key) — that's `inference-gateway`'s job before it goes live there.
+
+**Still open**: `JudgeScorer` (in eval-platform) has no live-model test.
+
+## Install
+Published on PyPI as `aikit-platform` (the import name is still `aikit` -
+only the distribution name differs, because the name `aikit` itself is
+already taken by an unrelated package). Core is light; heavy deps are
+extras:
+```bash
+pip install "aikit-platform[eval]"      # or [gateway], [memory]
+pip install "aikit-platform[embeddings,db,queue,observability,http]"  # à la carte
+```
+```python
+import aikit  # same import either way
+```
+Pin an exact tag from GitHub instead, if you want the git history alongside
+the code (this is what eval-platform/gateway/agent-memory all do):
+```bash
+pip install "aikit-platform[gateway] @ git+https://github.com/Aaryan123456679/aikit@v0.2.0"
+```
+
+## Develop
+```bash
+make install && make all
+```
+
+## Release
+Tag-driven: `git tag vX.Y.Z && git push origin vX.Y.Z` → CI builds and
+publishes to PyPI via trusted publishing (OIDC, no secrets in the repo).

aikit_platform-0.3.0/README.md

@@ -0,0 +1,81 @@
+# aikit
+
+*The shared library behind three AI-backend services — see the [AI Infrastructure Suite overview](https://github.com/Aaryan123456679/ai-infrastructure-suite).*
+
+Shared platform layer for a suite of AI-backend systems (LLM eval platform,
+inference gateway, agent-memory service). Publishes clean, SOLID interfaces
+and reusable infrastructure so each downstream service depends on contracts,
+not implementations.
+
+## Modules
+| Module | Contract | Concrete implementation |
+|---|---|---|
+| `model_client` | `ModelClient` | `OllamaClient`, `HostedClient` (OpenAI-compatible) — `complete` / `stream` (text + terminal `Usage`) / `health` / `aclose` |
+| `embeddings` | `EmbeddingService` | `SentenceTransformerEmbeddingService` — local batched embeddings + cosine |
+| `db` | async SQLAlchemy `Base` | `make_engine` / `make_sessionmaker` / `session_scope` |
+| `jobqueue` | `JobQueue` | `ArqJobQueue` (Redis/arq) |
+| `observability` | `MetricsSink`, logging | `PrometheusMetricsSink`, structlog JSON |
+| `config` | `BaseServiceSettings` | env-driven |
+
+## Status
+
+**v0.1.0** validated end-to-end by `eval-platform`'s live Docker smoke test:
+a real Postgres migration + advisory-lock-guarded prompt versioning +
+CAS-guarded run finalization, a real Redis-backed arq worker actually
+dispatching jobs, and a real Ollama model producing a scored, completed run
+through the API. That process caught and fixed real bugs — not just code
+review findings:
+
+- `sentence-transformers` version drift breaking `EmbeddingService`'s
+  structural match (`dim` typed wider than `int` in a newer release).
+- `ArqJobQueue` never dispatched a single job — arq names a job function by
+  `coroutine.__qualname__`, not `__name__`, so every registration collided
+  under the same closure qualname regardless of task name.
+- CI installed only `dev` extras, so it silently only ever type-checked and
+  tested the core Protocol stubs, never the concrete implementations.
+
+**v0.2.0** (breaking: `stream()` now yields `str | Usage`, terminal `Usage`
+carries `tokens_in`/`tokens_out`/`finish_reason` — additive to `complete()`,
+`eval-platform` stays pinned at v0.1.0 and is unaffected since it never
+calls `stream()`). Adds `HostedClient` (OpenAI-compatible: OpenAI, Groq,
+Together, Fireworks, OpenRouter, ...) for `inference-gateway`. Both closed
+gaps `eval-platform`'s status page called out:
+
+- `OllamaClient.stream()` is now **live-validated** against a real running
+  Ollama server, including a production-sized model (`llama3.1:8b`, not
+  just the small model used for eval-platform's fast smoke run) — text
+  deltas followed by exactly one terminal `Usage`, asserted live and
+  pinned down as a regression test replaying the real captured response.
+- `HostedClient` is new and mock-tested against the OpenAI-compatible wire
+  format (including the `stream_options.include_usage` SSE shape); it has
+  **not** been live-validated against a real hosted provider (needs a real
+  API key) — that's `inference-gateway`'s job before it goes live there.
+
+**Still open**: `JudgeScorer` (in eval-platform) has no live-model test.
+
+## Install
+Published on PyPI as `aikit-platform` (the import name is still `aikit` -
+only the distribution name differs, because the name `aikit` itself is
+already taken by an unrelated package). Core is light; heavy deps are
+extras:
+```bash
+pip install "aikit-platform[eval]"      # or [gateway], [memory]
+pip install "aikit-platform[embeddings,db,queue,observability,http]"  # à la carte
+```
+```python
+import aikit  # same import either way
+```
+Pin an exact tag from GitHub instead, if you want the git history alongside
+the code (this is what eval-platform/gateway/agent-memory all do):
+```bash
+pip install "aikit-platform[gateway] @ git+https://github.com/Aaryan123456679/aikit@v0.2.0"
+```
+
+## Develop
+```bash
+make install && make all
+```
+
+## Release
+Tag-driven: `git tag vX.Y.Z && git push origin vX.Y.Z` → CI builds and
+publishes to PyPI via trusted publishing (OIDC, no secrets in the repo).

aikit_platform-0.3.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aikit-platform"
+dynamic = ["version"]              # sourced from src/aikit/__init__.py; bump there before tagging
+description = "Shared platform layer for AI-backend systems: model client, embeddings, observability, config, db, queue."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Aaryan Mahajan" }]
+keywords = ["llm", "embeddings", "observability", "infrastructure"]
+
+# Core stays dependency-light on purpose. Heavy deps live in extras.
+dependencies = [
+    "pydantic>=2.7",
+    "pydantic-settings>=2.3",
+]
+
+[project.optional-dependencies]
+embeddings   = ["sentence-transformers>=3.0"]
+db           = ["sqlalchemy[asyncio]>=2.0", "asyncpg>=0.29", "pgvector>=0.3"]
+redis        = ["redis>=5.0"]
+queue        = ["aikit-platform[redis]", "arq>=0.26"]
+observability = ["prometheus-client>=0.20", "structlog>=24.1"]
+http         = ["httpx>=0.27"]
+
+# Per-project bundles so downstream repos install exactly what they need.
+eval    = ["aikit-platform[db,queue,observability,http,embeddings]"]
+# No `queue`/arq: the gateway is a synchronous request path, not a fan-out
+# worker system - it uses raw `redis` (cache, circuit breaker, rate limit)
+# directly, never arq.
+gateway = ["aikit-platform[db,redis,observability,http,embeddings]"]
+memory  = ["aikit-platform[db,queue,observability,http,embeddings]"]
+
+dev = ["pytest>=8.2", "pytest-asyncio>=0.23", "aiosqlite>=0.20", "ruff>=0.5", "mypy>=1.10"]
+
+[project.urls]
+Homepage = "https://github.com/Aaryan123456679/aikit"
+Repository = "https://github.com/Aaryan123456679/aikit"
+
+[tool.hatch.version]
+path = "src/aikit/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/aikit"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.mypy]
+python_version = "3.11"
+strict = true

aikit_platform-0.3.0/src/aikit/__init__.py

@@ -0,0 +1,6 @@
+"""aikit — shared platform layer for AI-backend systems.
+
+Public interfaces (SOLID contracts) live here. Concrete implementations are
+optional and gated behind extras so consumers pull only what they use.
+"""
+__version__ = "0.3.0"

aikit_platform-0.3.0/src/aikit/config/__init__.py

@@ -0,0 +1,13 @@
+"""Config — env-driven settings base. Each service subclasses this."""
+from __future__ import annotations
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class BaseServiceSettings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+
+    env: str = "local"
+    log_level: str = "INFO"
+    database_url: str = "postgresql+asyncpg://localhost/app"
+    redis_url: str = "redis://localhost:6379/0"

aikit_platform-0.3.0/src/aikit/db/__init__.py

@@ -0,0 +1,65 @@
+"""DB — async SQLAlchemy engine/session base + pgvector helpers.
+
+Impl requires the `db` extra. Provides:
+- async engine factory
+- transaction-scoped session context manager
+- DeclarativeBase subclass every service builds models on
+"""
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Any
+
+from sqlalchemy.ext.asyncio import (
+    AsyncEngine,
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+from sqlalchemy.orm import DeclarativeBase
+
+__all__ = ["Base", "make_engine", "make_sessionmaker", "session_scope"]
+
+
+class Base(DeclarativeBase):
+    """Declarative base every downstream service builds its ORM models on."""
+
+
+def make_engine(
+    database_url: str,
+    *,
+    echo: bool = False,
+    pool_size: int | None = None,
+    max_overflow: int | None = None,
+) -> AsyncEngine:
+    # pool_size/max_overflow default to None (omitted entirely) rather
+    # than SQLAlchemy's own QueuePool defaults (5/10), because those two
+    # kwargs are QueuePool-specific and blow up with a TypeError against
+    # any other pool class - including SQLite's StaticPool, which this
+    # project's own test suite uses. Omitting them when unset preserves
+    # exact prior behavior for every caller that doesn't pass them.
+    # Callers on Postgres that want a bigger pool (found necessary load-
+    # testing the gateway: every request that logs to Postgres holds a
+    # connection for that write, so 50 concurrent requests need more than
+    # QueuePool's own default 15-connection ceiling) pass them explicitly.
+    kwargs: dict[str, Any] = {"echo": echo, "pool_pre_ping": True}
+    if pool_size is not None:
+        kwargs["pool_size"] = pool_size
+    if max_overflow is not None:
+        kwargs["max_overflow"] = max_overflow
+    return create_async_engine(database_url, **kwargs)
+
+
+def make_sessionmaker(engine: AsyncEngine) -> async_sessionmaker[AsyncSession]:
+    return async_sessionmaker(engine, expire_on_commit=False)
+
+
+@asynccontextmanager
+async def session_scope(
+    sessionmaker: async_sessionmaker[AsyncSession],
+) -> AsyncIterator[AsyncSession]:
+    """Open a session bound to a single transaction: commits on success,
+    rolls back on any exception."""
+    async with sessionmaker() as session, session.begin():
+        yield session

aikit_platform-0.3.0/src/aikit/embeddings/__init__.py

@@ -0,0 +1,20 @@
+"""EmbeddingService — local, batched text embeddings.
+
+Reused by: eval (similarity scorer), gateway (semantic cache), memory (retrieval).
+Concrete impl requires the `embeddings` extra (sentence-transformers).
+"""
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+Vector = list[float]
+
+
+@runtime_checkable
+class EmbeddingService(Protocol):
+    dim: int
+
+    async def embed(self, texts: list[str]) -> list[Vector]: ...
+
+    @staticmethod
+    def cosine(a: Vector, b: Vector) -> float: ...

aikit_platform-0.3.0/src/aikit/embeddings/sentence_transformer.py

@@ -0,0 +1,46 @@
+"""SentenceTransformerEmbeddingService — local, batched embeddings.
+
+Requires the `embeddings` extra (sentence-transformers). Runs the (blocking,
+CPU-bound) model in a thread executor so it never blocks the event loop.
+"""
+from __future__ import annotations
+
+import asyncio
+
+import numpy as np
+from sentence_transformers import SentenceTransformer
+
+from . import Vector
+
+
+class SentenceTransformerEmbeddingService:
+    """LSP: substitutable anywhere an `EmbeddingService` is expected."""
+
+    def __init__(self, model_name: str = "all-MiniLM-L6-v2") -> None:
+        # device="cpu" is deliberate, not a missing feature: auto-detection
+        # picks MPS/CUDA when available, but a server process calls encode()
+        # from multiple concurrent executor threads (one per in-flight
+        # request), and MPS does not tolerate concurrent access from
+        # multiple threads reliably - it can crash the whole process rather
+        # than raise a catchable exception. CPU is also the right choice
+        # for this workload's shape (many small, single-item, latency-
+        # sensitive calls), where GPU dispatch overhead would dominate
+        # anyway.
+        self._model = SentenceTransformer(model_name, device="cpu")
+        dim = self._model.get_sentence_embedding_dimension()
+        if dim is None:
+            raise ValueError(f"model {model_name!r} did not report an embedding dimension")
+        self.dim: int = dim
+
+    async def embed(self, texts: list[str]) -> list[Vector]:
+        loop = asyncio.get_running_loop()
+        vectors = await loop.run_in_executor(None, self._model.encode, texts)
+        return [vector.tolist() for vector in vectors]
+
+    @staticmethod
+    def cosine(a: Vector, b: Vector) -> float:
+        va, vb = np.asarray(a, dtype=float), np.asarray(b, dtype=float)
+        denom = float(np.linalg.norm(va) * np.linalg.norm(vb))
+        if denom == 0.0:
+            return 0.0
+        return float(np.dot(va, vb) / denom)

aikit_platform-0.3.0/src/aikit/jobqueue/__init__.py

@@ -0,0 +1,15 @@
+"""JobQueue — async task fan-out abstraction.
+
+OCP: swap Redis/arq for a Postgres-backed queue without touching producers.
+"""
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any, Protocol
+
+
+class JobQueue(Protocol):
+    async def enqueue(self, task: str, payload: dict[str, Any]) -> str: ...
+    def register(
+        self, task: str, handler: Callable[[dict[str, Any]], Awaitable[None]]
+    ) -> None: ...

aikit_platform-0.3.0/src/aikit/jobqueue/arq_queue.py

@@ -0,0 +1,56 @@
+"""ArqJobQueue — JobQueue implementation over Redis via arq.
+
+Requires the `queue` extra (redis, arq). OCP: producers depend on the
+`JobQueue` Protocol, so swapping this for a Postgres-backed queue later
+touches no call sites.
+"""
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from arq import create_pool
+from arq.connections import ArqRedis, RedisSettings
+from arq.worker import Function, func
+
+
+class ArqJobQueue:
+    def __init__(self, redis_url: str) -> None:
+        self._redis_url = redis_url
+        self._pool: ArqRedis | None = None
+        self._handlers: dict[str, Function] = {}
+
+    async def connect(self) -> None:
+        if self._pool is None:
+            self._pool = await create_pool(RedisSettings.from_dsn(self._redis_url))
+
+    async def enqueue(self, task: str, payload: dict[str, Any]) -> str:
+        await self.connect()
+        assert self._pool is not None
+        job = await self._pool.enqueue_job(task, payload)
+        if job is None:
+            raise RuntimeError(f"job deduped or rejected by arq: {task}")
+        return job.job_id
+
+    def register(
+        self, task: str, handler: Callable[[dict[str, Any]], Awaitable[None]]
+    ) -> None:
+        async def wrapper(ctx: Any, payload: dict[str, Any]) -> None:
+            await handler(payload)
+
+        # arq's `func()` names a job by `name`, defaulting to
+        # `coroutine.__qualname__` (NOT `__name__`) if omitted - a closure's
+        # qualname is always its def-site path (e.g.
+        # "ArqJobQueue.register.<locals>.wrapper"), so the name must be set
+        # explicitly here or every registration collides under that one name.
+        self._handlers[task] = func(wrapper, name=task)
+
+    @property
+    def functions(self) -> list[Function]:
+        """Pass to `arq.worker.WorkerSettings.functions`."""
+        return list(self._handlers.values())
+
+    async def close(self) -> None:
+        if self._pool is not None:
+            await self._pool.close()
+            self._pool = None

aikit_platform-0.3.0/src/aikit/model_client/__init__.py

@@ -0,0 +1,64 @@
+"""ModelClient — unified async interface over heterogeneous LLM backends.
+
+DIP: consumers depend on this Protocol, never on Ollama/hosted specifics.
+LSP: every implementation is substitutable.
+ISP: streaming and non-streaming are separate methods.
+"""
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from typing import Literal, Protocol, runtime_checkable
+
+Role = Literal["system", "user", "assistant"]
+
+
+@dataclass(frozen=True)
+class ChatMessage:
+    role: Role
+    content: str
+
+
+@dataclass(frozen=True)
+class Completion:
+    content: str
+    model: str
+    tokens_in: int
+    tokens_out: int
+    latency_ms: float
+
+
+@dataclass(frozen=True)
+class Usage:
+    """Terminal event on a `stream()` iterator: exactly one, always last."""
+
+    tokens_in: int
+    tokens_out: int
+    finish_reason: str
+
+
+StreamEvent = str | Usage
+
+
+@runtime_checkable
+class ModelClient(Protocol):
+    """A single LLM backend. Implementations: OllamaClient, HostedClient."""
+
+    name: str
+
+    async def complete(
+        self, messages: list[ChatMessage], *, model: str | None = None
+    ) -> Completion: ...
+
+    def stream(
+        self, messages: list[ChatMessage], *, model: str | None = None
+    ) -> AsyncIterator[StreamEvent]:
+        """An async-generator method: called directly (no `await`), then
+        iterated with `async for`. Yields text deltas (`str`) followed by
+        exactly one terminal `Usage` — callers can accumulate text and read
+        cost/finish_reason off the last event without a second round trip."""
+        ...
+
+    async def health(self) -> bool: ...
+
+    async def aclose(self) -> None: ...

aikit_platform-0.3.0/src/aikit/model_client/hosted.py

@@ -0,0 +1,108 @@
+"""HostedClient — ModelClient implementation over any OpenAI-compatible
+chat-completions API (OpenAI itself, and the many providers that mirror
+its wire format: Groq, Together, Fireworks, OpenRouter, ...).
+
+Requires the `http` extra (httpx).
+"""
+from __future__ import annotations
+
+import json
+import time
+from collections.abc import AsyncIterator
+
+import httpx
+
+from . import ChatMessage, Completion, StreamEvent, Usage
+
+
+class HostedClient:
+    """LSP: substitutable anywhere a `ModelClient` is expected."""
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        *,
+        default_model: str,
+        timeout: float = 60.0,
+        name: str = "hosted",
+    ) -> None:
+        self.name = name
+        self._default_model = default_model
+        self._client = httpx.AsyncClient(
+            base_url=base_url.rstrip("/"),
+            timeout=timeout,
+            headers={"Authorization": f"Bearer {api_key}"},
+        )
+
+    async def complete(
+        self, messages: list[ChatMessage], *, model: str | None = None
+    ) -> Completion:
+        target_model = model or self._default_model
+        payload = {
+            "model": target_model,
+            "messages": [{"role": m.role, "content": m.content} for m in messages],
+            "stream": False,
+        }
+        start = time.perf_counter()
+        resp = await self._client.post("/chat/completions", json=payload)
+        resp.raise_for_status()
+        data = resp.json()
+        latency_ms = (time.perf_counter() - start) * 1000
+        choice = data["choices"][0]
+        usage = data.get("usage") or {}
+        return Completion(
+            content=choice.get("message", {}).get("content", ""),
+            model=data.get("model", target_model),
+            tokens_in=usage.get("prompt_tokens", 0),
+            tokens_out=usage.get("completion_tokens", 0),
+            latency_ms=latency_ms,
+        )
+
+    async def stream(
+        self, messages: list[ChatMessage], *, model: str | None = None
+    ) -> AsyncIterator[StreamEvent]:
+        payload = {
+            "model": model or self._default_model,
+            "messages": [{"role": m.role, "content": m.content} for m in messages],
+            "stream": True,
+            # Ask for a final usage-only chunk (OpenAI and most compatible
+            # providers support this) so the terminal Usage is exact, not
+            # estimated client-side.
+            "stream_options": {"include_usage": True},
+        }
+        finish_reason = "stop"
+        async with self._client.stream("POST", "/chat/completions", json=payload) as resp:
+            resp.raise_for_status()
+            async for line in resp.aiter_lines():
+                if not line or not line.startswith("data:"):
+                    continue
+                data = line[len("data:") :].strip()
+                if data == "[DONE]":
+                    break
+                chunk = json.loads(data)
+                choices = chunk.get("choices") or []
+                if choices:
+                    delta = choices[0].get("delta", {})
+                    piece = delta.get("content")
+                    if piece:
+                        yield piece
+                    if choices[0].get("finish_reason"):
+                        finish_reason = choices[0]["finish_reason"]
+                usage = chunk.get("usage")
+                if usage:
+                    yield Usage(
+                        tokens_in=usage.get("prompt_tokens", 0),
+                        tokens_out=usage.get("completion_tokens", 0),
+                        finish_reason=finish_reason,
+                    )
+
+    async def health(self) -> bool:
+        try:
+            resp = await self._client.get("/models")
+            return resp.status_code == 200
+        except httpx.HTTPError:
+            return False
+
+    async def aclose(self) -> None:
+        await self._client.aclose()

aikit_platform-0.3.0/src/aikit/model_client/ollama.py

@@ -0,0 +1,87 @@
+"""OllamaClient — ModelClient implementation over a local Ollama server.
+
+Requires the `http` extra (httpx). This is the only concrete ModelClient
+in v1: it doubles as target and judge model per the eval-platform HLD ($0
+cost, no hosted API keys needed).
+"""
+from __future__ import annotations
+
+import json
+import time
+from collections.abc import AsyncIterator
+
+import httpx
+
+from . import ChatMessage, Completion, StreamEvent, Usage
+
+
+class OllamaClient:
+    """LSP: substitutable anywhere a `ModelClient` is expected."""
+
+    def __init__(
+        self,
+        host: str = "http://localhost:11434",
+        *,
+        default_model: str = "llama3.1",
+        timeout: float = 60.0,
+        name: str = "ollama",
+    ) -> None:
+        self.name = name
+        self._default_model = default_model
+        self._client = httpx.AsyncClient(base_url=host.rstrip("/"), timeout=timeout)
+
+    async def complete(
+        self, messages: list[ChatMessage], *, model: str | None = None
+    ) -> Completion:
+        target_model = model or self._default_model
+        payload = {
+            "model": target_model,
+            "messages": [{"role": m.role, "content": m.content} for m in messages],
+            "stream": False,
+        }
+        start = time.perf_counter()
+        resp = await self._client.post("/api/chat", json=payload)
+        resp.raise_for_status()
+        data = resp.json()
+        latency_ms = (time.perf_counter() - start) * 1000
+        return Completion(
+            content=data.get("message", {}).get("content", ""),
+            model=target_model,
+            tokens_in=data.get("prompt_eval_count", 0),
+            tokens_out=data.get("eval_count", 0),
+            latency_ms=latency_ms,
+        )
+
+    async def stream(
+        self, messages: list[ChatMessage], *, model: str | None = None
+    ) -> AsyncIterator[StreamEvent]:
+        payload = {
+            "model": model or self._default_model,
+            "messages": [{"role": m.role, "content": m.content} for m in messages],
+            "stream": True,
+        }
+        async with self._client.stream("POST", "/api/chat", json=payload) as resp:
+            resp.raise_for_status()
+            async for line in resp.aiter_lines():
+                if not line:
+                    continue
+                chunk = json.loads(line)
+                piece = chunk.get("message", {}).get("content")
+                if piece:
+                    yield piece
+                if chunk.get("done"):
+                    yield Usage(
+                        tokens_in=chunk.get("prompt_eval_count", 0),
+                        tokens_out=chunk.get("eval_count", 0),
+                        finish_reason=chunk.get("done_reason", "stop"),
+                    )
+
+    async def health(self) -> bool:
+        try:
+            resp = await self._client.get("/api/tags")
+            return resp.status_code == 200
+        except httpx.HTTPError:
+            return False
+
+    async def aclose(self) -> None:
+        await self._client.aclose()

aikit_platform-0.3.0/src/aikit/observability/__init__.py

@@ -0,0 +1,77 @@
+"""Observability — structured logging + metrics + health.
+
+Impl requires the `observability` extra. Framework-agnostic helpers so any
+FastAPI service wires them identically.
+"""
+from __future__ import annotations
+
+import logging
+import sys
+from typing import Protocol
+
+import structlog
+from prometheus_client import CONTENT_TYPE_LATEST as PROMETHEUS_CONTENT_TYPE
+from prometheus_client import CollectorRegistry, Counter, Histogram, generate_latest
+
+__all__ = [
+    "MetricsSink",
+    "PrometheusMetricsSink",
+    "PROMETHEUS_CONTENT_TYPE",
+    "configure_logging",
+    "get_logger",
+]
+
+
+class MetricsSink(Protocol):
+    def incr(self, name: str, **labels: str) -> None: ...
+    def observe(self, name: str, value: float, **labels: str) -> None: ...
+
+
+def configure_logging(level: str = "INFO") -> None:
+    """Call once at process start. Renders JSON lines to stdout."""
+    logging.basicConfig(format="%(message)s", stream=sys.stdout, level=level)
+    structlog.configure(
+        processors=[
+            structlog.contextvars.merge_contextvars,
+            structlog.processors.add_log_level,
+            structlog.processors.TimeStamper(fmt="iso"),
+            structlog.processors.JSONRenderer(),
+        ],
+        wrapper_class=structlog.make_filtering_bound_logger(
+            logging.getLevelName(level) if isinstance(level, str) else level
+        ),
+        logger_factory=structlog.PrintLoggerFactory(),
+        cache_logger_on_first_use=True,
+    )
+
+
+def get_logger(name: str) -> structlog.stdlib.BoundLogger:
+    return structlog.get_logger(name)  # type: ignore[no-any-return]
+
+
+class PrometheusMetricsSink:
+    """Counter/Histogram-backed MetricsSink. Series are created lazily on
+    first use, keyed by name; the label set of the first call fixes that
+    series' label names for its lifetime."""
+
+    def __init__(self, registry: CollectorRegistry | None = None):
+        self._registry = registry or CollectorRegistry(auto_describe=True)
+        self._counters: dict[str, Counter] = {}
+        self._histograms: dict[str, Histogram] = {}
+
+    def incr(self, name: str, **labels: str) -> None:
+        counter = self._counters.get(name)
+        if counter is None:
+            counter = Counter(name, name, labelnames=sorted(labels), registry=self._registry)
+            self._counters[name] = counter
+        (counter.labels(**labels) if labels else counter).inc()
+
+    def observe(self, name: str, value: float, **labels: str) -> None:
+        hist = self._histograms.get(name)
+        if hist is None:
+            hist = Histogram(name, name, labelnames=sorted(labels), registry=self._registry)
+            self._histograms[name] = hist
+        (hist.labels(**labels) if labels else hist).observe(value)
+
+    def render(self) -> bytes:
+        return generate_latest(self._registry)

aikit_platform-0.3.0/tests/test_db.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from sqlalchemy import Column, Integer, String, select
+
+from aikit.db import Base, make_engine, make_sessionmaker, session_scope
+
+
+class Widget(Base):
+    __tablename__ = "widget"
+    id = Column(Integer, primary_key=True)
+    name = Column(String, nullable=False)
+
+
+async def test_session_scope_commits_on_success():
+    engine = make_engine("sqlite+aiosqlite://")
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    sessionmaker = make_sessionmaker(engine)
+
+    async with session_scope(sessionmaker) as session:
+        session.add(Widget(id=1, name="a"))
+
+    async with sessionmaker() as session:
+        rows = (await session.execute(select(Widget))).scalars().all()
+        assert [r.name for r in rows] == ["a"]
+
+
+async def test_session_scope_rolls_back_on_error():
+    engine = make_engine("sqlite+aiosqlite://")
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    sessionmaker = make_sessionmaker(engine)
+
+    class Boom(Exception):
+        pass
+
+    try:
+        async with session_scope(sessionmaker) as session:
+            session.add(Widget(id=1, name="a"))
+            raise Boom
+    except Boom:
+        pass
+
+    async with sessionmaker() as session:
+        rows = (await session.execute(select(Widget))).scalars().all()
+        assert rows == []

aikit_platform-0.3.0/tests/test_jobqueue_arq.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from aikit.jobqueue.arq_queue import ArqJobQueue
+
+
+def test_registered_function_is_named_by_task_not_qualname():
+    """Regression test: arq's `func()` names a job from `coroutine.__qualname__`
+    when `name` is omitted, and a closure's qualname is always its def-site
+    path (e.g. "ArqJobQueue.register.<locals>.wrapper") - never the task
+    name. Caught in a live Docker run where the worker registered the
+    wrapper under its qualname and every job then failed with
+    "function 'execute_case' not found"."""
+    queue = ArqJobQueue("redis://localhost:6379/0")
+
+    async def handler(payload: dict) -> None:
+        pass
+
+    queue.register("execute_case", handler)
+
+    [registered] = queue.functions
+    assert registered.name == "execute_case"
+
+
+def test_multiple_registrations_keep_distinct_names():
+    queue = ArqJobQueue("redis://localhost:6379/0")
+
+    async def handler_a(payload: dict) -> None:
+        pass
+
+    async def handler_b(payload: dict) -> None:
+        pass
+
+    queue.register("task_a", handler_a)
+    queue.register("task_b", handler_b)
+
+    names = {f.name for f in queue.functions}
+    assert names == {"task_a", "task_b"}

aikit_platform-0.3.0/tests/test_model_client_hosted.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import httpx
+
+from aikit.model_client import ChatMessage, Usage
+from aikit.model_client.hosted import HostedClient
+
+
+def _client_with_transport(handler) -> HostedClient:
+    client = HostedClient("http://hosted.local", "sk-test", default_model="gpt-4o-mini")
+    client._client = httpx.AsyncClient(
+        base_url="http://hosted.local",
+        headers={"Authorization": "Bearer sk-test"},
+        transport=httpx.MockTransport(handler),
+    )
+    return client
+
+
+async def test_complete_parses_openai_response():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.headers["authorization"] == "Bearer sk-test"
+        assert request.url.path == "/chat/completions"
+        return httpx.Response(
+            200,
+            json={
+                "model": "gpt-4o-mini",
+                "choices": [{"message": {"content": "hi there"}, "finish_reason": "stop"}],
+                "usage": {"prompt_tokens": 10, "completion_tokens": 3},
+            },
+        )
+
+    client = _client_with_transport(handler)
+    result = await client.complete([ChatMessage(role="user", content="hello")])
+    assert result.content == "hi there"
+    assert result.model == "gpt-4o-mini"
+    assert result.tokens_in == 10
+    assert result.tokens_out == 3
+
+
+async def test_stream_yields_text_then_exactly_one_terminal_usage():
+    """SSE shape per the OpenAI-compatible spec with stream_options.include_usage."""
+    sse_lines = [
+        'data: {"choices":[{"delta":{"content":"hi"},"finish_reason":null}]}',
+        'data: {"choices":[{"delta":{"content":" there"},"finish_reason":"stop"}]}',
+        'data: {"choices":[],"usage":{"prompt_tokens":10,"completion_tokens":2}}',
+        "data: [DONE]",
+    ]
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, text="\n\n".join(sse_lines) + "\n\n")
+
+    client = _client_with_transport(handler)
+    events = [event async for event in client.stream([ChatMessage(role="user", content="hi")])]
+
+    assert events[:-1] == ["hi", " there"]
+    assert events[-1] == Usage(tokens_in=10, tokens_out=2, finish_reason="stop")
+    assert sum(isinstance(e, Usage) for e in events) == 1
+
+
+async def test_health_true_on_200():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json={"data": []})
+
+    client = _client_with_transport(handler)
+    assert await client.health() is True
+
+
+async def test_health_false_on_error():
+    def handler(request: httpx.Request) -> httpx.Response:
+        raise httpx.ConnectError("refused", request=request)
+
+    client = _client_with_transport(handler)
+    assert await client.health() is False

aikit_platform-0.3.0/tests/test_model_client_ollama.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import httpx
+
+from aikit.model_client import ChatMessage, Usage
+from aikit.model_client.ollama import OllamaClient
+
+
+def _client_with_transport(handler) -> OllamaClient:
+    client = OllamaClient(default_model="llama3.1")
+    client._client = httpx.AsyncClient(
+        base_url="http://ollama.local", transport=httpx.MockTransport(handler)
+    )
+    return client
+
+
+async def test_complete_parses_ollama_response():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.url.path == "/api/chat"
+        return httpx.Response(
+            200,
+            json={
+                "message": {"role": "assistant", "content": "hi there"},
+                "prompt_eval_count": 5,
+                "eval_count": 3,
+            },
+        )
+
+    client = _client_with_transport(handler)
+    result = await client.complete([ChatMessage(role="user", content="hello")])
+    assert result.content == "hi there"
+    assert result.model == "llama3.1"
+    assert result.tokens_in == 5
+    assert result.tokens_out == 3
+    assert result.latency_ms >= 0
+
+
+async def test_health_false_on_error():
+    def handler(request: httpx.Request) -> httpx.Response:
+        raise httpx.ConnectError("refused", request=request)
+
+    client = _client_with_transport(handler)
+    assert await client.health() is False
+
+
+async def test_stream_yields_text_then_exactly_one_terminal_usage():
+    """Response lines captured verbatim from a real Ollama server (see
+    aikit v0.2.0's HLD/LLD B.0 - live-validated separately against a real
+    llama3.1:8b before this mock was written)."""
+    lines = [
+        '{"model":"llama3.2:latest","message":{"role":"assistant","content":"Hi"},"done":false}',
+        '{"model":"llama3.2:latest","message":{"role":"assistant","content":" there"},'
+        '"done":false}',
+        '{"model":"llama3.2:latest","message":{"role":"assistant","content":"!"},"done":false}',
+        '{"model":"llama3.2:latest","message":{"role":"assistant","content":""},'
+        '"done":true,"done_reason":"stop","prompt_eval_count":32,"eval_count":4}',
+    ]
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, text="\n".join(lines))
+
+    client = _client_with_transport(handler)
+    events = [event async for event in client.stream([ChatMessage(role="user", content="hi")])]
+
+    assert events[:-1] == ["Hi", " there", "!"]
+    assert events[-1] == Usage(tokens_in=32, tokens_out=4, finish_reason="stop")
+    assert sum(isinstance(e, Usage) for e in events) == 1
+
+
+async def test_health_true_on_200():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json={"models": []})
+
+    client = _client_with_transport(handler)
+    assert await client.health() is True

aikit_platform-0.3.0/tests/test_observability.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from aikit.observability import PrometheusMetricsSink
+
+
+def test_incr_and_observe_render_as_prometheus_text():
+    sink = PrometheusMetricsSink()
+    sink.incr("jobs_total", status="ok")
+    sink.incr("jobs_total", status="ok")
+    sink.observe("latency_ms", 12.5, backend="ollama")
+
+    body = sink.render().decode()
+    assert 'jobs_total{status="ok"} 2.0' in body
+    assert "latency_ms_sum" in body
+    assert 'backend="ollama"' in body

aikit_platform-0.3.0/tests/test_smoke.py

@@ -0,0 +1,17 @@
+from aikit import __version__
+from aikit.embeddings import EmbeddingService
+from aikit.model_client import ChatMessage, ModelClient
+
+
+def test_version():
+    assert isinstance(__version__, str)
+
+
+def test_chat_message_immutable():
+    m = ChatMessage(role="user", content="hi")
+    assert m.role == "user"
+
+
+def test_protocols_importable():
+    assert ModelClient is not None
+    assert EmbeddingService is not None