> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parmanasystems.com/llms.txt
> Use this file to discover all available pages before exploring further.

# parmana.builders

Constructs a fully-formed, internally-consistent BusinessTransaction
from the fields a caller actually decides, deriving every field the
server's own BusinessTransactionValidator checks for cross-consistency
(packages/runtime/src/validators/BusinessTransactionValidator.ts) so a
caller can never build a request that fails one of those checks by
mistake:

* metadata.business\_transaction\_id always equals business\_transaction\_id
* authorization.authority\_id always equals authority.authority\_id
* intent.authorization\_id always equals authorization.authorization\_id

Hand-building a BusinessTransaction by constructing all five nested
dataclasses and keeping three id pairs in sync by hand is exactly the
class of mistake that produced every "X must match Y" 400 response
documented in END-TO-END-FLOW\.md (repo root) -- this function exists so
that mistake is structurally impossible when going through the SDK, not
merely documented as something to be careful about.

Not auto-generated: unlike everything in parmana.models, this is a
hand-maintained convenience layer, not a 1:1 mirror of a TypeScript
domain type -- python/scripts/generate\_models.ts never touches this
file.

#### create\_business\_transaction

```python theme={null}
def create_business_transaction(
        *,
        principal_id: str,
        purpose: str,
        action: str,
        target: str,
        parameters: dict[str, Any],
        policy: PolicyReference,
        signals: dict[str, Any],
        business_transaction_id: str | None = None,
        authority_type: AuthorityType = AuthorityType.SERVICE,
        display_name: str | None = None,
        correlation_id: str | None = None,
        tenant_id: str | None = None,
        source_system: str | None = None,
        submitted_by: str | None = None) -> BusinessTransaction
```

Builds a BusinessTransaction with every cross-referenced id
derived and kept consistent automatically.

business\_transaction\_id defaults to a fresh uuid4() if omitted --
a caller providing one explicitly is responsible for it being
unique per attempt, since it doubles as the server's own
idempotency key (see docs/site/guides/end-to-end-paytm-flow\.mdx,
"businessTransactionId is an idempotency key").

authority\_type defaults to SERVICE -- the correct value for an
autonomous agent. There is no "AGENT" value; it does not exist
server-side.

principal\_id must match one of the caller API key's own
allowed\_principal\_ids server-side, or the request is rejected
before policy ever runs -- see GET /callers/me.