Official Python SDK (structx-sdk) for struct-x — agent-native structured extraction.

Navigation

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for StructXOps from gravatar.com StructXOps

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License (MIT)
  • Author: struct-x
  • Tags agent , ai , extraction , json-schema , llm , mcp , structured-extraction
  • Requires: Python >=3.10
  • Provides-Extra: dev
Classifiers
Report project as malware

Project description

structx-sdk — Python SDK for struct-x

PyPI Python License

Official Python client for struct-x — the agent-native structured-extraction API. Send raw content and a JSON Schema, get back validated, typed JSON with per-field confidence scores.

Install

pip install structx-sdk

Quickstart

from structx_sdk import StructX

client = StructX(api_key="sx_...")

result = client.extract(
    content="<div><h1>Aeron Chair</h1><span>$1,795.00</span></div>",
    schema={
        "type": "object",
        "required": ["title", "price_cents"],
        "properties": {
            "title":       {"type": "string"},
            "price_cents": {"type": "integer"},
        },
    },
)

print(result.data)
# {'title': 'Aeron Chair', 'price_cents': 179500}

print(result.field_confidences[0])
# FieldConfidence(field='title', confidence=0.96, source_snippet=None)

Use a catalog template instead of an inline schema

result = client.extract(
    content=stripe_webhook_payload,
    template_slug="logs.stripe.event",   # latest published version
)

Pin to a specific template version with family_slug@version:

template_slug="logs.stripe.event@1.0.0"

Don't have a schema yet? Let the API infer one

inference = client.infer_schema(
    content="<html>… some product page …</html>",
    content_type="html",
)

print(inference.inferred.json_schema)   # ready to pass back to extract()
for f in inference.inferred.fields:
    print(f"{f.name} ({f.type}) — {f.rationale}")

# Plus template recommendations, if any matched:
for r in inference.recommendations:
    print(f"{r.slug} (score={r.score:.2f})")

Async

Same surface, await-flavored:

import asyncio
from structx_sdk import AsyncStructX

async def main():
    async with AsyncStructX(api_key="sx_...") as client:
        result = await client.extract(content="…", schema={…})
        print(result.data)

asyncio.run(main())

Configuration

Param Default Notes
api_key STRUCTX_API_KEY env var Required.
base_url STRUCTX_BASE_URL env var, else https://api.structx.ai Override for staging / self-hosted.
timeout 30.0 seconds Applied per request.
retry RetryPolicy(max_attempts=3, …) Tune via RetryPolicy(...).
default_headers {} Merged into every request — e.g., for tracing IDs.

Pick up credentials from the environment with StructX.from_env():

import os
os.environ["STRUCTX_API_KEY"] = "sx_..."

from structx_sdk import StructX
client = StructX.from_env()

Errors

All exceptions inherit from StructXError. Catch the specific class you care about:

from structx_sdk import RateLimitError, ValidationError, ServerError

try:
    result = client.extract(content=…, schema=…)
except RateLimitError as e:
    # 429 — back off; e.retry_after, e.credits_used, e.credits_remaining are populated
    print(f"Sleep {e.retry_after}s. Used {e.credits_used}/{e.credits_used + e.credits_remaining}.")
except ValidationError as e:
    # 400/422 — fix your input. e.code carries the machine-readable reason.
    print(f"Bad input: {e.code} — {e.message}")
except ServerError as e:
    # 5xx — retry or contact support; e.request_id is your handle.
    print(f"Server error (request_id={e.request_id})")

Full hierarchy:

StructXError
├── TransportError              # network failure — request never reached the server
└── ApiError                    # server responded with an error status
    ├── AuthenticationError     # 401
    ├── PermissionDeniedError   # 403
    ├── NotFoundError           # 404
    ├── ValidationError         # 400, 422
    ├── RateLimitError          # 429  (carries retry_after, credits info)
    └── ServerError             # 5xx

Retries

By default, read calls (list_templates, list_models, usage) auto-retry on transient 5xx and connection errors with exponential backoff.

Write calls (extract, infer_schema) retry ONLY on transport errors, never on 5xx — because a 5xx after a partial backend run may have already billed the call.

Customize via RetryPolicy:

from structx_sdk import StructX, RetryPolicy

client = StructX(
    api_key="sx_...",
    retry=RetryPolicy(
        max_attempts=5,
        initial_backoff=0.5,
        max_backoff=60.0,
        retry_on_5xx=True,
        respect_retry_after=True,
    ),
)

Forward compatibility

Response models accept extra fields silently. When the API adds a new field, old SDK versions don't break — they just don't surface it as a typed attribute. Reach it via result.model_dump() or result.__pydantic_extra__.

Development

git clone https://github.com/struct-x-ai/struct-x
cd struct-x/sdk/python
pip install -e ".[dev]"
pytest -q

License

MIT — see LICENSE.

Project details

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for StructXOps from gravatar.com StructXOps

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License (MIT)
  • Author: struct-x
  • Tags agent , ai , extraction , json-schema , llm , mcp , structured-extraction
  • Requires: Python >=3.10
  • Provides-Extra: dev
Classifiers

Release history Release notifications | RSS feed

This version

0.2.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

structx_sdk-0.2.0.tar.gz (14.0 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

structx_sdk-0.2.0-py3-none-any.whl (15.3 kB view details)

Uploaded Python 3

File details

Details for the file structx_sdk-0.2.0.tar.gz.

File metadata

  • Download URL: structx_sdk-0.2.0.tar.gz
  • Upload date:
  • Size: 14.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for structx_sdk-0.2.0.tar.gz
Algorithm Hash digest
SHA256 c7eb6139fc6ccc34c64d8ed6242f5ef1b368bd8aea3e988dc93e3e3fdaaffea4
MD5 4a124a6688682cda49696b6a5b60f246
BLAKE2b-256 4fae721fedaae0a4cee1b451f7f4c1150de2e31170bc813a7c71cf6bc34b3927

See more details on using hashes here.

Provenance

The following attestation bundles were made for structx_sdk-0.2.0.tar.gz:

Publisher: sdk-python-publish.yml on struct-x-ai/struct-x

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file structx_sdk-0.2.0-py3-none-any.whl.

File metadata

  • Download URL: structx_sdk-0.2.0-py3-none-any.whl
  • Upload date:
  • Size: 15.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for structx_sdk-0.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 4098d4e367c52c6a4b2378ac164d9f849d2c1e0d4930a95ee1b3332b0ae68f0c
MD5 4b42f22c4c53e54d8a6e3c4d766e99cf
BLAKE2b-256 99ac37808739ec6db0cd59821cc46eed83396d0cdc502dfaa4d387cbb131c079

See more details on using hashes here.

Provenance

The following attestation bundles were made for structx_sdk-0.2.0-py3-none-any.whl:

Publisher: sdk-python-publish.yml on struct-x-ai/struct-x

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page