Metadata-Version: 2.4
Name: agentbuck
Version: 0.1.0
Summary: Python SDK for AgentBuck runtime validation over gRPC.
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/FirstEigen-Labs/agentbuck_sdk
Project-URL: Source, https://github.com/FirstEigen-Labs/agentbuck_sdk
Project-URL: Issues, https://github.com/FirstEigen-Labs/agentbuck_sdk/issues
Keywords: agentbuck,data-quality,grpc,sdk,validation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: grpcio<2.0.0,>=1.71.2
Requires-Dist: protobuf<6.0.0,>=5.29.0
Requires-Dist: python-dotenv<2.0.0,>=1.0.0
Provides-Extra: dev
Requires-Dist: grpcio-tools==1.71.2; extra == "dev"
Dynamic: license-file

# AgentBuck Python SDK

`agentbuck` is the public Python SDK for AgentBuck runtime validation.

## Install

```bash
pip install agentbuck
```

## Import

```python
import agentbuck

api_key = "<api key provided by caller>"
client = agentbuck.AgentBuckClient(api_key=api_key)
result = client.validate_bulk(
    agent_id="agent-123",
    idApp=456,
    data=[{"email": "user@example.com"}],
)
```

Successful validation returns a dictionary with engine status, message, and
decisions:

```python
{
    "status": "success",
    "message": "",
    "decisions": ["PROCEED", "BLOCK"],
}
```

Authorization failures are returned by the engine in the same response shape:

```python
{
    "status": "failed",
    "message": "idApp not accessible",
    "decisions": [],
}
```

The SDK endpoint can be provided directly, loaded from a custom env file, or
read from `AGENTBUCK_GRPC_TARGET` in the process environment. If no endpoint or
custom env file is provided, the SDK also loads a standard `.env` file from the
current working directory when present.

Examples:

```text
AGENTBUCK_GRPC_TARGET=tcp://127.0.0.1:50051
```

```python
client = agentbuck.AgentBuckClient(
    api_key=api_key,
    endpoint="tcp://127.0.0.1:50051",
)
```

```python
client = agentbuck.AgentBuckClient(
    api_key=api_key,
    env_file="/path/to/custom.env",
)
```

Endpoint lookup order:

1. Explicit `endpoint=...`
2. Explicit `env_file=...`
3. `AGENTBUCK_GRPC_TARGET` from the process environment or `.env` in the current working directory

Endpoint values must use `tcp://host:port` format.

## Authentication

Pass an API key when creating the client:

```python
api_key = "<api key provided by caller>"
client = agentbuck.AgentBuckClient(api_key=api_key)
```

The API key must be provided by the caller through `api_key=...`.

## Public API

- `agentbuck.AgentBuckClient`
- `agentbuck.HealthResult`
- `agentbuck.ValidateBulkResult`

## License

The SDK is licensed under
[Apache-2.0](https://github.com/FirstEigen-Labs/agentbuck_sdk/blob/main/LICENSE).
Copyright 2026 AgentBuck.

## Build and verify a release

From a clean checkout, install the release tools and build both distribution
formats:

```bash
python -m pip install build twine
python -m build
python -m twine check --strict dist/*
python scripts/verify_release.py dist
```

`verify_release.py` checks that the wheel and source distribution have matching
versions, Apache-2.0 metadata, the license files, the type marker, and the
generated gRPC modules. It also checks that the source distribution contains
`validation.proto` and the generator script. The generated Python modules are
checked in; installing the SDK does not run the generator or need
`grpcio-tools`.

GitHub Actions runs these checks and installs both archives in clean
environments on Python 3.10, 3.11, 3.12, and 3.13.

### Verify against a running engine

On Windows, install the built wheel into a fresh environment, then run the
interactive check:

```powershell
py -3.12 -m venv .venv-pypi-check
.\.venv-pypi-check\Scripts\python.exe -m pip install .\dist\agentbuck-0.1.0-py3-none-any.whl
.\.venv-pypi-check\Scripts\python.exe .\scripts\verify_live.py --csv "C:\path\to\data.csv" --endpoint "tcp://host:port" --agent-id "agent-123" --idapp 370
```

The script prompts for `api_key` without echoing it. If omitted, `--csv` and
`--endpoint` are prompted for too. The defaults are `agent-123` and `370` for
`--agent-id` and `--idapp`. It reads CSV records using the same header handling
as the SDK, times `validate_bulk`, and shows each row whose decision is `BLOCK`.
It checks the decision count before pairing decisions with rows. A successful
live check ends with `Live SDK validation succeeded`. The server must be
running and the API key must be allowed to validate the chosen `idapp` and
`agent_id`.

## Publish to PyPI

One-time setup:

1. Publish this repository at the public
   [FirstEigen-Labs/agentbuck_sdk](https://github.com/FirstEigen-Labs/agentbuck_sdk)
   path and update this checkout's `origin` URL to that repository.
2. In that repository's **Settings → Environments**, create `pypi`. Require a
   reviewer before deployment and allow release tags matching `v*`.
3. In [PyPI's publishing settings](https://pypi.org/manage/account/publishing/),
   register a pending GitHub trusted publisher with project `agentbuck`, owner
   `FirstEigen-Labs`, repository `agentbuck_sdk`, workflow `release.yml`, and
   environment `pypi`. A pending publisher does not reserve the project name.

For the first release, keep `pyproject.toml` and `agentbuck.__version__` at
`0.1.0`. After CI passes, push the `v0.1.0` tag:

```bash
git tag v0.1.0
git push origin v0.1.0
```

The [release workflow](https://github.com/FirstEigen-Labs/agentbuck_sdk/blob/main/.github/workflows/release.yml) checks the tag against
the distribution version, rebuilds and verifies the archives, and waits for
approval in the `pypi` environment before uploading through trusted
publishing. For later releases, update both version values before tagging.
