Metadata-Version: 2.4
Name: viksa-platform-runtime
Version: 0.2.0
Summary: Typed cross-cutting runtime contracts for Viksa platform services
Author-email: Viksa AI <support@viksaai.com>
License-Expression: Apache-2.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp<4,>=3.9
Requires-Dist: async-timeout<6,>=4
Requires-Dist: fastapi<1,>=0.104
Requires-Dist: httpx<1,>=0.25
Requires-Dist: pydantic<3,>=2
Requires-Dist: pydantic-settings<3,>=2
Requires-Dist: python-json-logger<5,>=2
Requires-Dist: uvicorn<1,>=0.24
Requires-Dist: uvloop<1,>=0.19; platform_system != "Windows"
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: mypy<2,>=1.11.0; extra == "dev"
Requires-Dist: pytest<9,>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio<1,>=0.23.0; extra == "dev"
Requires-Dist: redis<6,>=5; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: setuptools>=77; extra == "dev"
Requires-Dist: tomli>=2; python_version < "3.11" and extra == "dev"
Requires-Dist: twine<7,>=5; extra == "dev"
Requires-Dist: wheel>=0.43; extra == "dev"
Dynamic: license-file

# viksa-platform-runtime

`viksa-platform-runtime` is the independently versioned, PEP 561-typed boundary
for cross-cutting Viksa service behavior. Version `0.2.0` provides:

- instance-based, bounded trace and usage recorders;
- typed trace, usage, tenant, and caller contexts;
- transport and bounded-lifecycle protocols for dependency injection;
- exact-body HMAC request signing with current/previous key verification;
- immutable secret-strength classification for service-owned startup policy;
- tenant-safe display extraction and recursive secret redaction;
- structure-aware truncation for bounded LLM context payloads; and
- thin functional facades for staged migration from copied `common/` modules.

Version `0.2.0` also owns the stable tracing primitives historically copied as
`common.platform_traces.ids`, `tracestate`, `tenant`, `sampling`, `constants`,
`errors`, `labels`, `semconv`, `workflow`, and `internal_headers`. Those legacy
module paths may be retained as identity-preserving import-only aliases.

It also owns the fleet's legacy-compatible platform-metrics modules and shared
internal request-signing, tenant-header, tenant-guard, internal-key, and JWT
secret helpers. The compatibility tenant guard uses FastAPI's historical
`HTTPException` contract; Pydantic v2 and FastAPI are therefore explicit
runtime dependencies of this release.

Tenant-facing display and redaction code should import
`viksa_platform.security.tenant_safe_display`. Existing service-owned display
module paths may remain as identity-preserving import-only aliases during the
migration.

Shared structured-payload truncation should import
`viksa_platform.truncation.smart_truncate`. The helper preserves whole list
items, emits an explicit downsampling note, and retains the historical
`DEFAULT_SYNTHESIS_BUDGET` contract.

The fleet migration has a hard release dependency: version `0.2.0` must exist
in the package index used by production builds before any service-side alias or
requirement pin is merged or deployed. Local source and wheel installs are for
validation only; production builds must never substitute an unpinned package
or workspace path. See the release gate in [`MIGRATION.md`](MIGRATION.md).

The instance APIs are canonical. Functional `configure_*`, `start_*`,
`record_*`, and `stop_*` helpers hold process-global state only to support a
bounded compatibility migration. New service code should construct recorders,
signers, and verifiers in its composition root and inject their protocols.

## Ownership exclusions

Apart from the exact legacy `requires_internal_signature` compatibility helper,
this package intentionally does **not** own:

- environment-variable loading or the decision of when startup policy applies;
- route-specific caller allowlists or authorization decisions;
- MongoDB, Redis, HTTP, Temporal, Kubernetes, or cloud-provider clients;
- durable queues, retries, dead-letter handling, or replay/idempotency stores;
- trace/metric ingestion repositories and analytics;
- service/domain event names or business resource semantics; or
- application lifespan ordering beyond the bounded lifecycle protocol.

Services must inject transports that provide the durability and retry semantics
their domain requires. A successful in-memory `record` call means only that the
item entered the bounded local queue; transport acknowledgement defines actual
delivery.

## Development

```bash
python -m pip install -e '.[dev]'
pytest
ruff check src tests
ruff format --check src tests
mypy
python -m build
python -m twine check dist/*
python ../../scripts/verify_python_release.py \
  --project-directory . \
  --dist-directory dist \
  --expected-name viksa-platform-runtime
```

The distribution supports Python 3.10–3.12.

See [`MIGRATION.md`](MIGRATION.md) for the audited mapping from copied service
modules to the canonical APIs and for the boundaries intentionally deferred to
service-owned adapters.
