[gabrielvfonseca]

Summary

• Redesign the resource API and harden shared HTTP transport behavior.
• Establish the Python SDK 1.0.0 interface and update docs, examples, and tests.
• Rebase on the latest main; upstream workflow and repository policy changes are retained.

Validation

• git diff --check origin/main...HEAD passed.
• CI quality checks were not run locally; GitHub Actions will run on this PR.

Summary by CodeRabbit

• New Features
  • SDK operations now use resource-oriented names and descriptive identifiers across resources.
  • Request bodies distinguish omitted content from explicit JSON null and {}.
• Behavior Changes
  • Errors expose transient status and a separate safe_to_retry signal. Streaming POST requests now default to no retries.
  • Polling enforces deadlines, and SSE streams preserve event IDs across events.
  • The in-memory AI tool registry is no longer available.
• Bug Fixes
  • Improved error-detail handling and validation for pagination limits, retry settings, and AI token counts.
• Documentation
  • Updated usage guidance for request bodies, retries, client ownership, and resource operations.

[coderabbitai]

Warning

Review limit reached

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

Next included review available in 26 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Free
• Run ID: 8c5339a5-a62c-4ad2-81bc-898aad36fa39

---

📥 Commits

Reviewing files that changed from the base of the PR and between fd6bb1a and 90d4dcc.

---

📒 Files selected for processing (7)

• .github/workflows/ci.yml
• .github/workflows/publish.yml
• frontal_sdk/core/config.py
• frontal_sdk/core/http.py
• frontal_sdk/resources/ai.py
• scripts/check_contracts.py
• tests/test_client.py

---

---

frontal-labs is on CodeRabbit Free, which includes PR summaries. Ask your admin to upgrade for code reviews.

• Ask an admin to upgrade

Open in CodeRabbit

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Free
• Run ID: 120c9a66-ac2b-43e0-8b0f-99bb496d1dd7

---

📥 Commits

Reviewing files that changed from the base of the PR and between 5fa9e44 and fd6bb1a.

---

📒 Files selected for processing (45)

• .github/workflows/ci.yml
• .github/workflows/publish.yml
• CHANGELOG.md
• README.md
• docs/ARCHITECTURE.md
• docs/ENTERPRISE_READINESS.md
• docs/RESOURCES.md
• docs/ROADMAP.md
• examples/SDKS_GUIDE.md
• frontal_sdk/__init__.py
• frontal_sdk/client.py
• frontal_sdk/core/config.py
• frontal_sdk/core/errors.py
• frontal_sdk/core/http.py
• frontal_sdk/core/pagination.py
• frontal_sdk/core/polling.py
• frontal_sdk/models/__init__.py
• frontal_sdk/models/ai.py
• frontal_sdk/models/requests.py
• frontal_sdk/resources/_base.py
• frontal_sdk/resources/agents.py
• frontal_sdk/resources/ai.py
• frontal_sdk/resources/audit.py
• frontal_sdk/resources/auth.py
• frontal_sdk/resources/billing.py
• frontal_sdk/resources/blob.py
• frontal_sdk/resources/connectors.py
• frontal_sdk/resources/data.py
• frontal_sdk/resources/governance.py
• frontal_sdk/resources/lineage.py
• frontal_sdk/resources/observability.py
• frontal_sdk/resources/ontology.py
• frontal_sdk/resources/pipelines.py
• frontal_sdk/resources/sandbox.py
• frontal_sdk/resources/schedules.py
• frontal_sdk/resources/webhooks.py
• frontal_sdk/resources/workflows.py
• scripts/README.md
• scripts/benchmark_transport.py
• scripts/check_contracts.py
• scripts/check_distribution.py
• templates/async-client/src/frontal_async/__main__.py
• templates/batch-job/src/frontal_batch/__main__.py
• templates/cli/src/frontal_cli/__main__.py
• tests/test_client.py

---

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

---

---

📝 Walkthrough

Walkthrough

The SDK updates request-body handling, error and retry signals, resource method names, and helper validation. It also adds distribution validation to build workflows and a mocked transport benchmark.

Changes

Request behavior and validation

Layer / File(s)	Summary
Request bodies, errors, and transport behavior frontal_sdk/models/requests.py, frontal_sdk/core/http.py, frontal_sdk/core/errors.py, frontal_sdk/resources/_base.py, frontal_sdk/__init__.py, tests/test_client.py, README.md, docs/ARCHITECTURE.md	The SDK distinguishes an omitted body from JSON null and {}. Errors expose transient and safe_to_retry; streaming requests default to zero retries. HTTP error details, retry delays, SSE event IDs, and debug request logging also change.
Configuration, polling, and pagination validation frontal_sdk/core/config.py, frontal_sdk/core/polling.py, frontal_sdk/core/pagination.py, tests/test_client.py, docs/RESOURCES.md	Header values and reserved header names receive checks. Polling and pagination validate inputs and enforce deadlines.
AI helpers and model contracts frontal_sdk/resources/ai.py, frontal_sdk/models/ai.py, frontal_sdk/models/__init__.py, tests/test_client.py	The in-memory AI tool registry is removed. AI endpoint methods are renamed, token fields use integer constraints, and cost estimation and object-generation retry validation change.

Resource API

Layer / File(s)	Summary
Resource methods and accessor wiring frontal_sdk/resources/agents.py, frontal_sdk/resources/{audit,auth,billing,blob,connectors,data,governance,lineage,observability,ontology,pipelines,sandbox,schedules,webhooks,workflows}.py, frontal_sdk/client.py	Resource methods use concise names and semantic path arguments. Agent run and version namespaces are added, and workflow and agent accessors call the updated methods. Endpoint paths and HTTP operations are retained for the renamed methods.
Public API documentation and coverage README.md, docs/RESOURCES.md, examples/SDKS_GUIDE.md, templates/*, tests/test_client.py, scripts/check_contracts.py, CHANGELOG.md	Documentation, templates, contract checks, and tests are updated to use the resource-oriented API and describe request behavior and client ownership.

Distribution and tooling

Layer / File(s)	Summary
Build artifact validation .github/workflows/{ci,publish}.yml, scripts/check_distribution.py, docs/{ENTERPRISE_READINESS,ROADMAP}.md	The CI and publishing workflows run a distribution check after building. The script checks wheel metadata, package markers, wheel importability, and source archive contents.
Mock transport benchmark scripts/benchmark_transport.py, scripts/README.md	A command-line script measures sync and async request throughput using mocked HTTPX responses.

Estimated code review effort: 4 (Complex) | ~45 minutes

---

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

_{Comment @coderabbitai help to get the list of available commands.}

[sonarqubecloud]

❌ The last analysis has failed.

See analysis details on SonarQube Cloud