Metadata-Version: 2.5
Name: vintraa-agent
Version: 0.1.3
Summary: Framework-neutral Python SDK for native Vintraa agents.
Project-URL: Homepage, https://vintraa.zyntrialabs.com/developers
Project-URL: Documentation, https://api-vintraa.zyntrialabs.com/public#/
Project-URL: Security, https://vintraa.zyntrialabs.com/security
Author: Zyntria Labs
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: a2a,agent,ai,sdk,vintraa
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: cryptography<51,>=48.0.1
Requires-Dist: jsonschema[format]<5,>=4.25
Requires-Dist: pydantic<3,>=2.11
Requires-Dist: pyyaml<7,>=6.0.2
Provides-Extra: dev
Requires-Dist: build>=1.3; extra == 'dev'
Requires-Dist: fastapi<1,>=0.116; extra == 'dev'
Requires-Dist: httpx2<3,>=2; extra == 'dev'
Requires-Dist: jsonschema[format]>=4.25; extra == 'dev'
Requires-Dist: mypy>=1.17; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.1; extra == 'dev'
Requires-Dist: pytest>=8.4; extra == 'dev'
Requires-Dist: ruff>=0.12; extra == 'dev'
Requires-Dist: twine<8,>=7; extra == 'dev'
Requires-Dist: types-jsonschema>=4.25; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.12; extra == 'dev'
Provides-Extra: fastapi
Requires-Dist: fastapi<1,>=0.116; extra == 'fastapi'
Provides-Extra: redis
Requires-Dist: redis<8,>=6; extra == 'redis'
Description-Content-Type: text/markdown

# vintraa-agent

`vintraa-agent` is the Python SDK for native Vintraa agent integrations, with
a framework-neutral core and an optional FastAPI adapter.

This package is an alpha release. Its API may change before `1.0.0`.

```bash
python -m pip install vintraa-agent
# FastAPI and Redis adapters:
python -m pip install 'vintraa-agent[fastapi,redis]'
```

See the [Vintraa developer guide](https://vintraa.zyntrialabs.com/developers)
and [public API reference](https://api-vintraa.zyntrialabs.com/public#/). Using
the SDK is optional and does not itself certify an agent.

```python
from vintraa_agent import (
    AsyncInMemoryIdempotencyStore,
    HostedPublicKeyProvider,
    InvocationExecutor,
    SuccessResult,
)
from vintraa_agent.fastapi import create_fastapi_router


async def generate_roster(invocation):
    return SuccessResult(
        output={
            "workspaceId": invocation.envelope.context.workspace.id,
        }
    )


async def authorize(invocation):
    return "ROSTER_MANAGER" in invocation.envelope.context.user.roles


executor = InvocationExecutor(
    public_keys=HostedPublicKeyProvider(),
    idempotency=AsyncInMemoryIdempotencyStore(),  # use Redis in production
    handlers={"roster.generate": generate_roster},
    authorize=authorize,
)

app.include_router(create_fastapi_router(executor))
```

The FastAPI adapter streams and bounds the untouched request body before
verification; tune `max_body_bytes` only when the signed protocol limit changes. Use
`AsyncRedisIdempotencyStore` with `redis.asyncio` in multi-process production;
the in-memory store is development-only. `PublisherClient.register_draft`
remains a compatibility alias. `PublisherClient` is an equivalent async client
for canonical contract `2026-09-05.11`: device identity, scoped credentials,
ownership verification, publishers, applications, releases, conformance,
private test creation, publisher-safe review responses, certification reads,
controlled activation/deprecation/withdrawal, deployment upgrade/rollback,
principal-owned import/conformance jobs, governed assets and asset sets,
conformance history, signed publisher webhook lifecycle/history, ETags, cursors,
and Operations.
Publisher analytics add the closed event dictionary, privacy-gated summary and
timeseries reads, plus idempotent aggregate-only exports with a dedicated typed
operation poll. Suppressed values remain `None`, unknown optional SDK coverage
remains `UNKNOWN`, and truncation is explicit.
Successful analytics responses are hard-bounded to 1,000 cells or rows and use
a dedicated bounded decoder so the contract maximum remains consumable.
It validates manifest v2 before mutations; review and certification remain
server-authoritative. See [the raw HTTP operation guide](../docs/publishing-v1.md).

Publisher webhook verification requires the untouched request bytes:

```python
from vintraa_agent import verify_publisher_webhook

verified = verify_publisher_webhook(
    raw_body,
    request_headers,
    {current_secret_prefix: current_secret},
)
```

Persist `verified.event_id` in a durable inbox before side effects. HMAC and
freshness verification do not themselves deduplicate retries or order events.

Anonymous discovery uses `MarketplaceClient`, which deliberately sends no
bearer credentials:

```python
from vintraa_agent import MarketplaceClient

marketplace = MarketplaceClient()
page = await marketplace.search_applications(category="productivity", limit=25)
passport = await marketplace.get_application(page["items"][0]["appId"])
```

Authenticated install and reputation mutations remain on `PublisherClient`;
workspace role, acknowledgement, eligibility, and moderation stay
server-authoritative.

Hosted signing-key discovery uses a bounded negative cache, a refresh cooldown,
a rolling fetch-rate cap, and one in-flight refresh so attacker-controlled key
identifiers cannot amplify registry traffic.

For a developer-hosted customer UI, use
`create_external_experience_exchange_proof` on the server that receives
Vintraa's top-level launch POST. Keep both the private key and exchanged access
token out of browser JavaScript and browser storage.
