structx-sdk 0.2.0__tar.gz

structx_sdk-0.2.0/.gitignore

@@ -0,0 +1,20 @@
+# Build outputs
+dist/
+build/
+*.egg-info/
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# Caches
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Editor
+.vscode/
+.idea/

structx_sdk-0.2.0/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+All notable changes to the `structx-sdk` Python SDK are documented here.
+This project follows [Semantic Versioning](https://semver.org/).
+
+## [0.2.0] — 2026-05-25
+
+### BREAKING
+- Renamed the package from `structx` to `structx-sdk` on PyPI. Pre-existing unrelated package at `structx` on PyPI made coexistence impossible.
+- Renamed the Python module from `structx` to `structx_sdk`. Update imports: `from structx_sdk import StructX, AsyncStructX, ...`
+- Renamed the public classes to use capital `X`: `Structx` → `StructX`, `AsyncStructx` → `AsyncStructX`, `StructxError` → `StructXError`. Brand-consistent with marketing's "Struct-X" spelling.
+- Env variables (`STRUCTX_API_KEY`, `STRUCTX_BASE_URL`) unchanged.
+- User-Agent header prefix updated to `structx-sdk/<version>`.
+
+### Migration
+Replace `from structx import Structx` with `from structx_sdk import StructX`. The class API is otherwise unchanged.
+
+## [0.1.1] - 2026-05-25
+
+### Security
+- `ApiError.response_body` now has sensitive-key values redacted at exception-construction time (Phase 5.5 / rho). Closes a credential/PII leak that surfaced when customer code logged `repr(exc)` or routed exceptions to error trackers like Sentry. Redacted keys (case-insensitive): `x-api-key`, `authorization`, `apikey`, `api_key`, `password`, `token`, `secret`, `private_key`, `content`. Values become `<redacted N chars>` (length preserved for debugging).
+- `ApiError.__repr__` now omits `response_body` entirely — second layer of defense against accidental `f"{exc!r}"` logging.
+- Backward compatible: `.response_body` attribute is still accessible for programmatic inspection; only the values for sensitive keys are sentinelized.
+
+## [0.1.0] — 2026-05-24
+
+Initial release.
+
+### Added
+- `Structx` sync client + `AsyncStructx` async client (parallel surfaces).
+- `extract(content, *, schema=None, template_slug=None, tier=..., options=...)`.
+- `infer_schema(content, *, content_type=None, hints=None, ...)`.
+- `list_templates()`, `list_models()`, `usage()`.
+- Typed exception hierarchy: `StructxError → ApiError → {Authentication, PermissionDenied, NotFound, Validation, RateLimit, Server}Error`, plus `TransportError` for network failures.
+- Typed Pydantic response models: `Extraction`, `FieldConfidence`, `TokenCounts`, `InferenceResult`, `InferredSchema`, `InferredField`, `Recommendation`, `Template`, `Model`, `Usage`. All accept extra fields silently for forward compatibility.
+- `RetryPolicy` with read-vs-write retry differentiation — reads auto-retry on 5xx, writes only on transport errors (avoid double-billing).
+- `STRUCTX_API_KEY` / `STRUCTX_BASE_URL` environment fallbacks, plus `Structx.from_env()`.
+- Context-manager support (`with Structx(...)` closes the underlying httpx client).
+- `py.typed` marker for full type-checker support.
+
+### Compatible with
+- Python 3.10, 3.11, 3.12, 3.13.
+- struct-x API v1.x.
+- httpx 0.27 / 0.28; pydantic 2.5+.

structx_sdk-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 struct-x
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

structx_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: structx-sdk
+Version: 0.2.0
+Summary: Official Python SDK (structx-sdk) for struct-x — agent-native structured extraction.
+Project-URL: Homepage, https://structx.ai
+Project-URL: Documentation, https://docs.structx.ai
+Project-URL: Repository, https://github.com/struct-x-ai/struct-x
+Project-URL: Issues, https://github.com/struct-x-ai/struct-x/issues
+Project-URL: Changelog, https://github.com/struct-x-ai/struct-x/blob/main/sdk/python/CHANGELOG.md
+Author-email: struct-x <support@structx.ai>
+License: MIT
+License-File: LICENSE
+Keywords: agent,ai,extraction,json-schema,llm,mcp,structured-extraction
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+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 :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<0.29,>=0.27
+Requires-Dist: pydantic<3.0,>=2.5
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# structx-sdk — Python SDK for struct-x
+
+[![PyPI](https://img.shields.io/pypi/v/structx-sdk.svg)](https://pypi.org/project/structx-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/structx-sdk.svg)](https://pypi.org/project/structx-sdk/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Official Python client for **[struct-x](https://structx.ai)** — the agent-native structured-extraction API. Send raw content and a JSON Schema, get back validated, typed JSON with per-field confidence scores.
+
+## Install
+
+```bash
+pip install structx-sdk
+```
+
+## Quickstart
+
+```python
+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
+
+```python
+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`:
+
+```python
+template_slug="logs.stripe.event@1.0.0"
+```
+
+## Don't have a schema yet? Let the API infer one
+
+```python
+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:
+
+```python
+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()`:
+
+```python
+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:
+
+```python
+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`:
+
+```python
+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
+
+```bash
+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](LICENSE).

structx_sdk-0.2.0/README.md

@@ -0,0 +1,181 @@
+# structx-sdk — Python SDK for struct-x
+
+[![PyPI](https://img.shields.io/pypi/v/structx-sdk.svg)](https://pypi.org/project/structx-sdk/)
+[![Python](https://img.shields.io/pypi/pyversions/structx-sdk.svg)](https://pypi.org/project/structx-sdk/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Official Python client for **[struct-x](https://structx.ai)** — the agent-native structured-extraction API. Send raw content and a JSON Schema, get back validated, typed JSON with per-field confidence scores.
+
+## Install
+
+```bash
+pip install structx-sdk
+```
+
+## Quickstart
+
+```python
+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
+
+```python
+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`:
+
+```python
+template_slug="logs.stripe.event@1.0.0"
+```
+
+## Don't have a schema yet? Let the API infer one
+
+```python
+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:
+
+```python
+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()`:
+
+```python
+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:
+
+```python
+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`:
+
+```python
+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
+
+```bash
+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](LICENSE).

structx_sdk-0.2.0/pyproject.toml

@@ -0,0 +1,90 @@
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name = "structx-sdk"
+dynamic = ["version"]
+description = "Official Python SDK (structx-sdk) for struct-x — agent-native structured extraction."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "struct-x", email = "support@structx.ai" },
+]
+keywords = [
+    "structured-extraction",
+    "llm",
+    "json-schema",
+    "extraction",
+    "ai",
+    "agent",
+    "mcp",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27,<0.29",
+    "pydantic>=2.5,<3.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+    "mypy>=1.8",
+    "ruff>=0.5",
+]
+
+[project.urls]
+Homepage = "https://structx.ai"
+Documentation = "https://docs.structx.ai"
+Repository = "https://github.com/struct-x-ai/struct-x"
+Issues = "https://github.com/struct-x-ai/struct-x/issues"
+Changelog = "https://github.com/struct-x-ai/struct-x/blob/main/sdk/python/CHANGELOG.md"
+
+[tool.hatch.version]
+path = "src/structx_sdk/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/structx_sdk"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/structx_sdk",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "pyproject.toml",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+filterwarnings = ["error"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "N"]
+ignore = ["E501"]
+
+[tool.mypy]
+strict = true
+python_version = "3.10"
+files = ["src/structx_sdk"]

structx_sdk-0.2.0/src/structx_sdk/__init__.py

@@ -0,0 +1,82 @@
+"""struct-x Python SDK — official client for the structured-extraction API.
+
+Quickstart:
+
+    from structx_sdk import StructX
+
+    client = StructX(api_key="sx_...")
+    result = client.extract(
+        content="<div>$99 Widget</div>",
+        schema={
+            "type": "object",
+            "properties": {
+                "price_cents": {"type": "integer"},
+                "title": {"type": "string"},
+            },
+        },
+    )
+    print(result.data)               # {'price_cents': 9900, 'title': 'Widget'}
+    print(result.field_confidences)  # [FieldConfidence(field='price_cents', ...)]
+
+Async variant — same surface:
+
+    from structx_sdk import AsyncStructX
+
+    async with AsyncStructX(api_key="sx_...") as client:
+        result = await client.extract(content="...", schema={...})
+"""
+from ._client import AsyncStructX, RetryPolicy, StructX
+from ._exceptions import (
+    ApiError,
+    AuthenticationError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+    StructXError,
+    TransportError,
+    ValidationError,
+)
+from ._models import (
+    Extraction,
+    FieldConfidence,
+    InferenceResult,
+    InferredField,
+    InferredSchema,
+    Model,
+    Recommendation,
+    Template,
+    TokenCounts,
+    Usage,
+)
+from ._version import __version__
+
+__all__ = [
+    # Clients
+    "StructX",
+    "AsyncStructX",
+    "RetryPolicy",
+    # Exceptions
+    "StructXError",
+    "TransportError",
+    "ApiError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ValidationError",
+    "RateLimitError",
+    "ServerError",
+    # Models
+    "Extraction",
+    "FieldConfidence",
+    "TokenCounts",
+    "InferenceResult",
+    "InferredSchema",
+    "InferredField",
+    "Recommendation",
+    "Template",
+    "Model",
+    "Usage",
+    # Meta
+    "__version__",
+]