[Chkhikvadze]

What this adds

Two LangChain tools for Desearch People Search, in a new people_tools group. Both are also exported from langchain_desearch.

PeopleSearchTool (people_search_tool)

• Starts a search on x, linkedin, youtube or tiktok (POST /desearch/people/search/{platform}), polls GET /desearch/people/tasks/{task_id} and waits up to timeout seconds (default 300, max 1800). It then reads every page of GET .../results.
• Returns compact people: name, handle, url, platform, audience (followers, or subscribers on YouTube), location, score, why (the score summary), contacts, links and one evidence URL. Also verified/headline/company when present, plus task status and cost and a next_step sentence.
• If the search is still running when timeout runs out, it returns the people found so far with the task_id. Calling the tool again with only task_id keeps waiting on that search: it is free and starts nothing new.
• Supports count (5-200), min_score, exclude, idempotency_key (sent as Idempotency-Key; a replayed key is marked existing_task), and the platform filters (min_followers, verified_only, min_subscribers, require_contact, countries, keywords, …).
• A filter that does not apply to the chosen platform (for example verified_only on LinkedIn) is rejected during input validation, before any request is sent, so nothing is billed.
• The description says the tool is billed and that searches take 1-5 minutes.

PeopleProfilesTool (people_profiles_tool)

• Reads the free profiles library (GET /desearch/people/profiles) for one platform: q, sort (score/recent/audience), limit, cursor, plus the result filters has (email, website, x, linkedin, instagram, youtube, tiktok), min_audience, max_audience, min_score, location and verified.
• Returns total, compact people (with found_by) and next_cursor.

people_tools is kept out of search_tools, so create_search_agent never starts a billed search. Both tools follow the existing conventions: _run/_arun, return_direct=True, DESEARCH_API_KEY from the environment, and errors returned as "An error occurred while calling Desearch: HTTP <status>: <detail>". The API key never appears in an error.

Why direct HTTP instead of desearch-py

The tools call the /desearch/people routes directly with aiohttp (new file langchain_desearch/people.py). They send the same Authorization: <api key> header as the SDK. The People Search methods are in desearch-py 1.4.0, which is merged on GitHub but not on PyPI yet (PyPI has 1.2.1). The desearch-py>=1.1.0,<2.0.0 requirement is unchanged. aiohttp>=3.8,<4.0.0 is now declared explicitly; desearch-py already installs it. Once desearch-py 1.4.0 is on PyPI, these tools can switch to the SDK methods (x_profile_search, wait_for_people_task, iter_people_results, list_people_profiles, …) and people.py can be dropped.

Version

1.0.7 → 1.1.0 in setup.py and pyproject.toml. The README has a new People Tools section with an example, a table of filters by platform, and a note on billing and timing.

Tests

tests/unit_tests/test_people_tools.py (22 tests) runs the tools against a local aiohttp server and never calls the live API. It checks the URLs, the Authorization and Idempotency-Key headers, the request bodies and query encoding, polling, the timeout path, resuming with task_id, results pagination, idempotent replay, platform filter rejection with no request sent, HTTP errors without the key, sync calls inside a running loop, and ainvoke.

pytest tests/unit_tests -q
45 passed

Passes on Python 3.12 with langchain-core 1.6.12, Python 3.10 with langchain-core 0.3.51 / pydantic 2.11.3 (the setup.py pins), and Python 3.9.

Publishing

Merging ships this to PyPI. For this repo the Publish workflow runs when a GitHub release is published from main. PyPI publishing is currently blocked for Desearch until the PyPI token is fixed, so hold the merge and release until then.

🤖 Generated with Claude Code