[divyeshradadiya]

Description

This brings llama-index-tools-serpex in line with the current Serpex API: what it sends, how it reads the response, how it reports errors, and the docs. I checked each point against the Serpex backend and against live responses.

Request. search() used to send engine, category=web, num and time_range. The API reads none of them, and engine also earns a Deprecation response header. Now it sends only q, plus include_content / content_results when page content is on.

• engine (constructor and search()) and time_range stay accepted for backward compatibility. They emit a DeprecationWarning and are not sent.
• Both are kept out of the tool schema, so the agent only sees search(query, num_results). Before, the LLM was offered a time_range "filter" that did nothing. The README now points to after:YYYY-MM-DD / before:YYYY-MM-DD in the query.
• num_results limits results client-side to 1-10, since the API returns at most 10. The docstring used to say "max: 100".

Page content. New optional include_content / content_results (5 or 10) on the constructor. The top results' page markdown is appended to the document text, and metadata["content_error"] explains a page that could not be fetched.

Typed responses. SerpexSearchResponse, SerpexSearchResult and SerpexErrorBody are TypedDicts. Document metadata adds position and credits_used. engine stays in the metadata as the constant "auto", so existing readers keep working.

Errors. A failed request raises SerpexAPIError, a subclass of requests.exceptions.HTTPError, so existing except clauses still work. Its message is one sentence per status:

• 400: the API's reason.
• 401: check SERPEX_API_KEY.
• 402: out of credits, with the balance.
• 429: the plan limit and the wait in ms.
• 5xx: not charged, retry.

It also carries status_code, details and retryable.

Timeout. 60 s, or 100 s with page content. The old 30 s was shorter than the server's own budget. Requests also send a User-Agent.

Example. examples/serpex_example.py no longer calls methods that don't exist (search_with_location, gl / hl). The README is updated.

The version stays at 0.3.1, the unreleased bump from the first commit of this PR.

New Package?

• Yes
• No

Version Bump?

• Yes (0.3.0 → 0.3.1, already in this PR)
• No

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• This change requires a documentation update

How Has This Been Tested?

• I added new unit tests to cover this change
• I ran uv run -- pytest in the package

The tests use sanitized responses recorded from the live API (tests/fixtures/), with requests.get patched, so they need no network. They cover:

• the exact params sent, including deprecated arguments that are never sent;
• the tool schema;
• num_results capping;
• page content and content_error;
• empty results;
• every error status.

uv run -- pytest tests      25 passed, 1 skipped (live test, needs SERPEX_API_KEY)
ruff check                  All checks passed!
ruff format --check         5 files already formatted
pre-commit (repo config)    all hooks pass on the package files
mypy (1.18, Python 3.12)    Success: no issues found in 2 source files

The pinned mypy==0.991 in this package's dev group cannot parse the numpy 2.x stubs that llama-index-core pulls in ("Type statement is only supported in Python 3.12"), with or without this change. That is why mypy was run with a current release.

Suggested Checklist

• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• New and existing unit tests pass locally with my changes

I maintain Serpex.