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).
