feat!: kwargs API — replace *Request objects on public methods

[FrancescoSaverioZuppichini]

Summary

• Public client methods now take inline kwargs instead of Pydantic *Request objects — matches the JS SDK and standard Python SDK ergonomics (OpenAI, Anthropic, Stripe).
• *Request classes remain exported for users who want to build payloads manually, but client methods no longer accept them.
• Structured types (FetchConfig, format configs, schema dicts) are still passed as-is.

Before / After

# Before
sgai.scrape(ScrapeRequest(url="https://example.com", formats=[MarkdownFormatConfig()]))

# After
sgai.scrape("https://example.com", formats=[MarkdownFormatConfig()])

Scope

• ScrapeGraphAI / AsyncScrapeGraphAI: scrape, extract, search
• crawl.start
• monitor.create, monitor.update, monitor.activity
• history.list
• Unchanged: credits, health, crawl.get/stop/resume/delete, monitor.get/list/delete/pause/resume, history.get

Internal detail

A small _compact helper strips None kwargs so Pydantic fields with non-None defaults (e.g. formats, max_depth, page) fall back to their defaults instead of raising a ValidationError on None.

Breaking Change

Callers must switch from sgai.method(SomeRequest(...)) → sgai.method(...) per the new signatures. Suggest minor version bump (2.1.0) — fresh 2.x line, low blast radius.

Test plan

• All 28 unit tests pass (uv run pytest tests/)
• Live smoke test against default host — credits, scrape, search, crawl.start + poll, extract (with and without schema) all succeed
• uv run ruff format src tests clean
• uv run ruff check src tests clean
• uv build succeeds
• Integration tests (live API) — updated to new shape, ran a subset manually

Files

• src/scrapegraph_py/{client,async_client}.py — public method signatures
• tests/test_client.py, tests/test_integration.py — updated call sites
• examples/**/*.py — all 30 examples updated
• README.md — every snippet updated

🤖 Generated with Claude Code

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[gitguardian]

️✅ There are no secrets present in this pull request anymore.

If these secrets were true positive and are still valid, we highly recommend you to revoke them.
While these secrets were previously flagged, we no longer have a reference to the
specific commits where they were detected. Once a secret has been leaked into a git
repository, you should consider it compromised, even if it was deleted immediately.
Find here more information about risks.

---

^{_{🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request.}}

[github-actions]

🎉 This PR is included in version 3.0.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀