langchain-sofya 0.1.0__tar.gz

langchain_sofya-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+uv.lock

langchain_sofya-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sofya, Inc.
+
+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.

langchain_sofya-0.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.5
+Name: langchain-sofya
+Version: 0.1.0
+Summary: LangChain tools for Sofya: web search, page fetch, extraction and cited research for AI agents.
+Project-URL: Homepage, https://sofya.co
+Project-URL: Documentation, https://sofya.co/docs
+Project-URL: Repository, https://github.com/sofya-co/langchain-sofya
+Project-URL: Issues, https://github.com/sofya-co/langchain-sofya/issues
+Author-email: "Sofya, Inc." <contact@sofya.co>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai agents,langchain,search api,sofya,tools,web scraping,web search
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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 :: Internet :: WWW/HTTP :: Indexing/Search
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1.0.0,>=0.27.0
+Requires-Dist: langchain-core<2.0.0,>=0.3.15
+Requires-Dist: pydantic<3.0.0,>=2.7.4
+Description-Content-Type: text/markdown
+
+# langchain-sofya
+
+LangChain tools for [Sofya](https://sofya.co): live web search, any page or document as clean markdown, AI extraction from a page, and multi-source research with citations. One API key for all four.
+
+## Install
+
+```bash
+pip install -U langchain-sofya
+```
+
+Get an API key at [sofya.co/dashboard](https://sofya.co/dashboard) and set it:
+
+```bash
+export SOFYA_API_KEY="sofya_live_..."
+```
+
+Or pass `api_key="sofya_live_..."` to any tool.
+
+## Tools
+
+| Tool | Name the model sees | What it does | Credits |
+|---|---|---|---|
+| `SofyaSearch` | `sofya_search` | Web search. Results with the text of each page, or snippets only, plus an optional short AI answer. Filter by domain, topic (general or news) and freshness. | 2 (basic), 1 (snippets), +2 for the answer |
+| `SofyaFetch` | `sofya_fetch` | Up to 10 URLs as clean markdown. Web pages plus PDF, Word, Excel, PowerPoint, OpenDocument, EPUB and more. | 1 per URL, failed URLs free |
+| `SofyaExtract` | `sofya_extract` | Reads one page and answers a prompt about it. | 10 |
+| `SofyaResearch` | `sofya_research` | Splits a question into several searches, reads the sources and writes a report with citations. | 50 |
+
+A credit is $0.0025. Pricing: [sofya.co/pricing](https://sofya.co/pricing).
+
+## Use
+
+```python
+from langchain_sofya import SofyaSearch
+
+search = SofyaSearch(max_results=5, include_answer=True)
+result = search.invoke({"query": "latest stable Python release"})
+print(result["answer"])
+for r in result["results"]:
+    print(r["title"], r["url"])
+```
+
+Arguments set on the tool are defaults; the model can override them per call (for example `max_results`, `include_domains` or `freshness`).
+
+```python
+from langchain_sofya import SofyaExtract, SofyaFetch, SofyaResearch
+
+SofyaFetch().invoke({"urls": ["https://example.com/report.pdf"]})
+
+SofyaExtract().invoke({
+    "url": "https://en.wikipedia.org/wiki/Eiffel_Tower",
+    "prompt": "How tall is it and when did it open?",
+})
+
+SofyaResearch(max_sources=15).invoke({"query": "How do heat pumps perform in cold climates?"})
+```
+
+Every tool also has an async version through `ainvoke`.
+
+### With an agent
+
+```python
+from langchain.agents import create_agent
+from langchain_sofya import SofyaExtract, SofyaFetch, SofyaSearch
+
+agent = create_agent(
+    "anthropic:claude-sonnet-5-5",
+    tools=[SofyaSearch(), SofyaFetch(), SofyaExtract()],
+)
+agent.invoke({"messages": [{"role": "user", "content": "What changed in the latest Node.js LTS?"}]})
+```
+
+Errors (invalid key, out of credits, rate limits) come back to the model as a tool message instead of raising, so an agent can tell the user what happened.
+
+## Settings
+
+| Argument | Env var | Default |
+|---|---|---|
+| `api_key` | `SOFYA_API_KEY` | required |
+| `base_url` | `SOFYA_BASE_URL` | `https://sofya.co` |
+| `timeout` | - | 120 seconds (research can take up to a minute) |
+
+## Links
+
+- API docs: [sofya.co/docs](https://sofya.co/docs)
+- MCP server, for clients that speak MCP instead: `https://mcp.sofya.co/mcp`
+- Support: support@sofya.co
+
+## License
+
+MIT

langchain_sofya-0.1.0/README.md

@@ -0,0 +1,90 @@
+# langchain-sofya
+
+LangChain tools for [Sofya](https://sofya.co): live web search, any page or document as clean markdown, AI extraction from a page, and multi-source research with citations. One API key for all four.
+
+## Install
+
+```bash
+pip install -U langchain-sofya
+```
+
+Get an API key at [sofya.co/dashboard](https://sofya.co/dashboard) and set it:
+
+```bash
+export SOFYA_API_KEY="sofya_live_..."
+```
+
+Or pass `api_key="sofya_live_..."` to any tool.
+
+## Tools
+
+| Tool | Name the model sees | What it does | Credits |
+|---|---|---|---|
+| `SofyaSearch` | `sofya_search` | Web search. Results with the text of each page, or snippets only, plus an optional short AI answer. Filter by domain, topic (general or news) and freshness. | 2 (basic), 1 (snippets), +2 for the answer |
+| `SofyaFetch` | `sofya_fetch` | Up to 10 URLs as clean markdown. Web pages plus PDF, Word, Excel, PowerPoint, OpenDocument, EPUB and more. | 1 per URL, failed URLs free |
+| `SofyaExtract` | `sofya_extract` | Reads one page and answers a prompt about it. | 10 |
+| `SofyaResearch` | `sofya_research` | Splits a question into several searches, reads the sources and writes a report with citations. | 50 |
+
+A credit is $0.0025. Pricing: [sofya.co/pricing](https://sofya.co/pricing).
+
+## Use
+
+```python
+from langchain_sofya import SofyaSearch
+
+search = SofyaSearch(max_results=5, include_answer=True)
+result = search.invoke({"query": "latest stable Python release"})
+print(result["answer"])
+for r in result["results"]:
+    print(r["title"], r["url"])
+```
+
+Arguments set on the tool are defaults; the model can override them per call (for example `max_results`, `include_domains` or `freshness`).
+
+```python
+from langchain_sofya import SofyaExtract, SofyaFetch, SofyaResearch
+
+SofyaFetch().invoke({"urls": ["https://example.com/report.pdf"]})
+
+SofyaExtract().invoke({
+    "url": "https://en.wikipedia.org/wiki/Eiffel_Tower",
+    "prompt": "How tall is it and when did it open?",
+})
+
+SofyaResearch(max_sources=15).invoke({"query": "How do heat pumps perform in cold climates?"})
+```
+
+Every tool also has an async version through `ainvoke`.
+
+### With an agent
+
+```python
+from langchain.agents import create_agent
+from langchain_sofya import SofyaExtract, SofyaFetch, SofyaSearch
+
+agent = create_agent(
+    "anthropic:claude-sonnet-5-5",
+    tools=[SofyaSearch(), SofyaFetch(), SofyaExtract()],
+)
+agent.invoke({"messages": [{"role": "user", "content": "What changed in the latest Node.js LTS?"}]})
+```
+
+Errors (invalid key, out of credits, rate limits) come back to the model as a tool message instead of raising, so an agent can tell the user what happened.
+
+## Settings
+
+| Argument | Env var | Default |
+|---|---|---|
+| `api_key` | `SOFYA_API_KEY` | required |
+| `base_url` | `SOFYA_BASE_URL` | `https://sofya.co` |
+| `timeout` | - | 120 seconds (research can take up to a minute) |
+
+## Links
+
+- API docs: [sofya.co/docs](https://sofya.co/docs)
+- MCP server, for clients that speak MCP instead: `https://mcp.sofya.co/mcp`
+- Support: support@sofya.co
+
+## License
+
+MIT

langchain_sofya-0.1.0/langchain_sofya/__init__.py

@@ -0,0 +1,19 @@
+"""Sofya integration for LangChain: web search, fetch, extract and research."""
+
+from langchain_sofya._client import SofyaAPIWrapper
+from langchain_sofya._version import __version__
+from langchain_sofya.tools import (
+    SofyaExtract,
+    SofyaFetch,
+    SofyaResearch,
+    SofyaSearch,
+)
+
+__all__ = [
+    "SofyaAPIWrapper",
+    "SofyaExtract",
+    "SofyaFetch",
+    "SofyaResearch",
+    "SofyaSearch",
+    "__version__",
+]

langchain_sofya-0.1.0/langchain_sofya/_client.py

@@ -0,0 +1,111 @@
+"""HTTP client for the Sofya REST API."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+from langchain_core.tools import ToolException
+from pydantic import BaseModel, ConfigDict, Field, SecretStr, model_validator
+
+from langchain_sofya._version import __version__
+
+DEFAULT_BASE_URL = "https://sofya.co"
+# Research and AI answers can take up to a minute; leave headroom.
+DEFAULT_TIMEOUT = 120.0
+
+
+class SofyaAPIWrapper(BaseModel):
+    """Calls the Sofya API (https://sofya.co/docs).
+
+    The API key is read from the ``SOFYA_API_KEY`` environment variable unless
+    passed as ``api_key``. Create one at https://sofya.co/dashboard.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    api_key: SecretStr = Field(default=SecretStr(""))
+    base_url: str = Field(default=DEFAULT_BASE_URL)
+    timeout: float = Field(default=DEFAULT_TIMEOUT)
+
+    @model_validator(mode="before")
+    @classmethod
+    def _from_env(cls, values: Any) -> Any:
+        if not isinstance(values, dict):
+            return values
+        if not values.get("api_key"):
+            key = os.environ.get("SOFYA_API_KEY", "")
+            if not key:
+                raise ValueError(
+                    "Sofya API key not found. Pass api_key or set the "
+                    "SOFYA_API_KEY environment variable. Get a key at "
+                    "https://sofya.co/dashboard"
+                )
+            values["api_key"] = key
+        if not values.get("base_url"):
+            values["base_url"] = os.environ.get("SOFYA_BASE_URL") or DEFAULT_BASE_URL
+        return values
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key.get_secret_value()}",
+            "Content-Type": "application/json",
+            "User-Agent": f"langchain-sofya/{__version__}",
+        }
+
+    def _url(self, path: str) -> str:
+        return self.base_url.rstrip("/") + path
+
+    def post(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        """POST a JSON body and return the JSON response."""
+        try:
+            with httpx.Client(timeout=self.timeout) as client:
+                resp = client.post(self._url(path), json=payload, headers=self._headers())
+        except httpx.HTTPError as exc:
+            raise ToolException(f"Sofya request failed: {exc}") from exc
+        return _handle(resp)
+
+    async def apost(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        """Async version of :meth:`post`."""
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout) as client:
+                resp = await client.post(self._url(path), json=payload, headers=self._headers())
+        except httpx.HTTPError as exc:
+            raise ToolException(f"Sofya request failed: {exc}") from exc
+        return _handle(resp)
+
+
+def _handle(resp: httpx.Response) -> dict[str, Any]:
+    if resp.is_success:
+        data = resp.json()
+        if not isinstance(data, dict):
+            raise ToolException("Sofya returned an unexpected response.")
+        return data
+    raise ToolException(_error_message(resp))
+
+
+def _error_message(resp: httpx.Response) -> str:
+    detail: Any = None
+    try:
+        body = resp.json()
+        detail = body.get("detail") if isinstance(body, dict) else body
+        if isinstance(detail, dict):
+            detail = detail.get("message") or detail.get("error") or detail
+    except ValueError:
+        detail = resp.text[:500] or None
+
+    status = resp.status_code
+    if status == 401:
+        prefix = "Sofya API key is missing or invalid."
+    elif status == 402:
+        prefix = "The Sofya account is out of credits. Top up at https://sofya.co/dashboard."
+    elif status == 429:
+        prefix = "Sofya rate limit reached; retry shortly."
+    elif status == 422:
+        prefix = "Sofya rejected the request parameters."
+    else:
+        prefix = f"Sofya API error (HTTP {status})."
+    if detail and not isinstance(detail, str):
+        detail = str(detail)
+    return f"{prefix} {detail}" if detail and detail not in prefix else prefix

langchain_sofya-0.1.0/langchain_sofya/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

langchain_sofya-0.1.0/langchain_sofya/tools.py

@@ -0,0 +1,350 @@
+"""LangChain tools for Sofya: web search, fetch, extract and research."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from langchain_core.callbacks import (
+    AsyncCallbackManagerForToolRun,
+    CallbackManagerForToolRun,
+)
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field, model_validator
+
+from langchain_sofya._client import SofyaAPIWrapper
+
+_FRESHNESS = (
+    'Only results from this period: "day", "week", "month", "year", '
+    'or a date range "YYYY-MM-DD:YYYY-MM-DD".'
+)
+_TOPIC = '"general" for web search, "news" for news articles.'
+
+
+class _SofyaTool(BaseTool):
+    """Shared setup: an API wrapper built from api_key / SOFYA_API_KEY."""
+
+    api_wrapper: SofyaAPIWrapper = Field(default=None)  # type: ignore[assignment]
+    handle_tool_error: bool = True
+
+    @model_validator(mode="before")
+    @classmethod
+    def _build_wrapper(cls, values: Any) -> Any:
+        if isinstance(values, dict) and values.get("api_wrapper") is None:
+            values["api_wrapper"] = SofyaAPIWrapper(
+                **{k: values.pop(k) for k in ("api_key", "base_url", "timeout") if k in values}
+            )
+        return values
+
+    def _payload(self, given: dict[str, Any], keys: tuple[str, ...]) -> dict[str, Any]:
+        """Call arguments win; unset ones fall back to the tool's own settings."""
+        out: dict[str, Any] = {}
+        for k in keys:
+            v = given.get(k)
+            if v is None:
+                v = getattr(self, k, None)
+            if v is not None:
+                out[k] = v
+        return out
+
+
+# --------------------------------------------------------------------- search
+
+
+class SofyaSearchInput(BaseModel):
+    """Input for SofyaSearch."""
+
+    query: str = Field(description="What to search the web for.")
+    search_depth: Literal["basic", "snippets"] | None = Field(
+        default=None,
+        description='"basic" returns the text of each result page (2 credits); '
+        '"snippets" returns short snippets only (1 credit).',
+    )
+    max_results: int | None = Field(
+        default=None, ge=1, le=20, description="How many results to return, 1-20."
+    )
+    include_answer: bool | None = Field(
+        default=None,
+        description="Add a short AI answer written from the results (+2 credits).",
+    )
+    include_domains: list[str] | None = Field(
+        default=None,
+        description='Only return results from these domains, e.g. ["github.com"]. Up to 10.',
+    )
+    exclude_domains: list[str] | None = Field(
+        default=None,
+        description='Leave out results from these domains, e.g. ["pinterest.com"]. Up to 10.',
+    )
+    topic: Literal["general", "news"] | None = Field(default=None, description=_TOPIC)
+    freshness: str | None = Field(default=None, description=_FRESHNESS)
+
+
+_SEARCH_KEYS = (
+    "query",
+    "search_depth",
+    "max_results",
+    "include_answer",
+    "include_domains",
+    "exclude_domains",
+    "topic",
+    "freshness",
+)
+
+
+class SofyaSearch(_SofyaTool):  # type: ignore[override]
+    """Search the web with Sofya.
+
+    Returns ranked results with the text of each page (or short snippets), and
+    optionally a short AI answer.
+
+    Setup:
+        .. code-block:: bash
+
+            pip install -U langchain-sofya
+            export SOFYA_API_KEY="sofya_live_..."
+
+    Instantiate:
+        .. code-block:: python
+
+            from langchain_sofya import SofyaSearch
+
+            tool = SofyaSearch(max_results=5, include_answer=True)
+
+    Invoke:
+        .. code-block:: python
+
+            tool.invoke({"query": "latest stable Python release"})
+    """
+
+    name: str = "sofya_search"
+    description: str = (
+        "Search the web for current information. Returns ranked results with "
+        "title, URL and page text, and optionally a short AI answer. Input is a "
+        "search query; you can filter by domain, topic (general or news) and "
+        "freshness."
+    )
+    args_schema: type[BaseModel] = SofyaSearchInput
+
+    search_depth: Literal["basic", "snippets"] | None = None
+    """Default depth when the call does not set one (API default: basic)."""
+    max_results: int | None = None
+    """Default number of results, 1-20 (API default: 10)."""
+    include_answer: bool | None = None
+    """Add a short AI answer by default."""
+    include_domains: list[str] | None = None
+    """Domains to restrict results to by default."""
+    exclude_domains: list[str] | None = None
+    """Domains to leave out by default."""
+    topic: Literal["general", "news"] | None = None
+    """Default topic."""
+    freshness: str | None = None
+    """Default freshness filter."""
+
+    def _run(
+        self,
+        query: str,
+        run_manager: CallbackManagerForToolRun | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        payload = self._payload({"query": query, **kwargs}, _SEARCH_KEYS)
+        return self.api_wrapper.post("/v1/search", payload)
+
+    async def _arun(
+        self,
+        query: str,
+        run_manager: AsyncCallbackManagerForToolRun | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        payload = self._payload({"query": query, **kwargs}, _SEARCH_KEYS)
+        return await self.api_wrapper.apost("/v1/search", payload)
+
+
+# ---------------------------------------------------------------------- fetch
+
+
+class SofyaFetchInput(BaseModel):
+    """Input for SofyaFetch."""
+
+    urls: list[str] = Field(
+        min_length=1,
+        max_length=10,
+        description="URLs to read, up to 10. Web pages and documents (PDF, Word, "
+        "Excel, PowerPoint and more).",
+    )
+
+
+class SofyaFetch(_SofyaTool):  # type: ignore[override]
+    """Read web pages and documents as clean markdown with Sofya.
+
+    Handles HTML pages and documents such as PDF, DOCX, XLSX and PPTX. Costs
+    1 credit per URL; URLs that fail are not charged.
+
+    Instantiate:
+        .. code-block:: python
+
+            from langchain_sofya import SofyaFetch
+
+            tool = SofyaFetch()
+
+    Invoke:
+        .. code-block:: python
+
+            tool.invoke({"urls": ["https://example.com"]})
+    """
+
+    name: str = "sofya_fetch"
+    description: str = (
+        "Read one or more web pages or documents (PDF, Word, Excel, PowerPoint) "
+        "and return their text as clean markdown. Input is a list of up to 10 URLs."
+    )
+    args_schema: type[BaseModel] = SofyaFetchInput
+
+    include_raw_html: bool = False
+    """Also return each page's raw HTML."""
+
+    def _run(
+        self,
+        urls: list[str],
+        run_manager: CallbackManagerForToolRun | None = None,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {"urls": urls}
+        if self.include_raw_html:
+            payload["include_raw_html"] = True
+        return self.api_wrapper.post("/v1/fetch", payload)
+
+    async def _arun(
+        self,
+        urls: list[str],
+        run_manager: AsyncCallbackManagerForToolRun | None = None,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {"urls": urls}
+        if self.include_raw_html:
+            payload["include_raw_html"] = True
+        return await self.api_wrapper.apost("/v1/fetch", payload)
+
+
+# -------------------------------------------------------------------- extract
+
+
+class SofyaExtractInput(BaseModel):
+    """Input for SofyaExtract."""
+
+    url: str = Field(description="The page or document to read.")
+    prompt: str = Field(
+        description='What to pull out of it, e.g. "list every pricing tier with its price".'
+    )
+
+
+class SofyaExtract(_SofyaTool):  # type: ignore[override]
+    """Answer a question about one page with Sofya.
+
+    Sofya reads the page and an AI model answers the prompt from its text.
+    Costs 10 credits (1 when the page has too little text to answer).
+
+    Instantiate:
+        .. code-block:: python
+
+            from langchain_sofya import SofyaExtract
+
+            tool = SofyaExtract()
+
+    Invoke:
+        .. code-block:: python
+
+            tool.invoke({
+                "url": "https://en.wikipedia.org/wiki/Eiffel_Tower",
+                "prompt": "How tall is it and when did it open?",
+            })
+    """
+
+    name: str = "sofya_extract"
+    description: str = (
+        "Read one web page or document and return just the information asked "
+        "for. Input is a URL and a prompt describing what to extract."
+    )
+    args_schema: type[BaseModel] = SofyaExtractInput
+
+    def _run(
+        self,
+        url: str,
+        prompt: str,
+        run_manager: CallbackManagerForToolRun | None = None,
+    ) -> dict[str, Any]:
+        return self.api_wrapper.post("/v1/extract", {"url": url, "prompt": prompt})
+
+    async def _arun(
+        self,
+        url: str,
+        prompt: str,
+        run_manager: AsyncCallbackManagerForToolRun | None = None,
+    ) -> dict[str, Any]:
+        return await self.api_wrapper.apost("/v1/extract", {"url": url, "prompt": prompt})
+
+
+# ------------------------------------------------------------------- research
+
+
+class SofyaResearchInput(BaseModel):
+    """Input for SofyaResearch."""
+
+    query: str = Field(description="The research question or topic.")
+    topic: Literal["general", "news"] | None = Field(default=None, description=_TOPIC)
+    freshness: str | None = Field(default=None, description=_FRESHNESS)
+    max_sources: int | None = Field(
+        default=None, ge=5, le=30, description="Most sources to read, 5-30."
+    )
+
+
+_RESEARCH_KEYS = ("query", "topic", "freshness", "max_sources")
+
+
+class SofyaResearch(_SofyaTool):  # type: ignore[override]
+    """Research a question across many sources with Sofya.
+
+    Splits the question into several searches, reads the sources and writes a
+    report with citations. Costs 50 credits and usually takes 20-60 seconds.
+
+    Instantiate:
+        .. code-block:: python
+
+            from langchain_sofya import SofyaResearch
+
+            tool = SofyaResearch(max_sources=15)
+
+    Invoke:
+        .. code-block:: python
+
+            tool.invoke({"query": "How do heat pumps perform in cold climates?"})
+    """
+
+    name: str = "sofya_research"
+    description: str = (
+        "Research an open-ended question across many web sources and return a "
+        "written report with citations and the source list. Input is the "
+        "question."
+    )
+    args_schema: type[BaseModel] = SofyaResearchInput
+
+    topic: Literal["general", "news"] | None = None
+    """Default topic."""
+    freshness: str | None = None
+    """Default freshness filter."""
+    max_sources: int | None = None
+    """Default number of sources, 5-30 (API default: 20)."""
+
+    def _run(
+        self,
+        query: str,
+        run_manager: CallbackManagerForToolRun | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        payload = self._payload({"query": query, **kwargs}, _RESEARCH_KEYS)
+        return self.api_wrapper.post("/v1/research", payload)
+
+    async def _arun(
+        self,
+        query: str,
+        run_manager: AsyncCallbackManagerForToolRun | None = None,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        payload = self._payload({"query": query, **kwargs}, _RESEARCH_KEYS)
+        return await self.api_wrapper.apost("/v1/research", payload)

langchain_sofya-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langchain-sofya"
+dynamic = ["version"]
+description = "LangChain tools for Sofya: web search, page fetch, extraction and cited research for AI agents."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Sofya, Inc.", email = "contact@sofya.co" }]
+requires-python = ">=3.10"
+keywords = ["langchain", "sofya", "web search", "search api", "web scraping", "ai agents", "tools"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "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 :: Internet :: WWW/HTTP :: Indexing/Search",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = [
+    "langchain-core>=0.3.15,<2.0.0",
+    "httpx>=0.27.0,<1.0.0",
+    "pydantic>=2.7.4,<3.0.0",
+]
+
+[project.urls]
+Homepage = "https://sofya.co"
+Documentation = "https://sofya.co/docs"
+Repository = "https://github.com/sofya-co/langchain-sofya"
+Issues = "https://github.com/sofya-co/langchain-sofya/issues"
+
+[dependency-groups]
+test = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "pytest-socket>=0.7",
+    "langchain-tests>=0.3.20",
+]
+lint = ["ruff>=0.8", "mypy>=1.13"]
+
+[tool.hatch.version]
+path = "langchain_sofya/_version.py"
+
+[tool.hatch.build.targets.sdist]
+include = ["langchain_sofya", "tests", "README.md", "LICENSE"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "T201", "UP"]
+
+[tool.mypy]
+disallow_untyped_defs = true
+plugins = ["pydantic.mypy"]
+
+[tool.pytest.ini_options]
+addopts = "--strict-markers --strict-config"
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

langchain_sofya-0.1.0/tests/integration_tests/test_standard.py

@@ -0,0 +1,75 @@
+"""LangChain standard integration tests. Need SOFYA_API_KEY; they spend credits.
+
+Research is left out by default (50 credits a call); set SOFYA_TEST_RESEARCH=1
+to include it.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import pytest
+from langchain_core.tools import BaseTool
+from langchain_tests.integration_tests import ToolsIntegrationTests
+
+from langchain_sofya import SofyaExtract, SofyaFetch, SofyaResearch, SofyaSearch
+
+pytestmark = pytest.mark.skipif(not os.environ.get("SOFYA_API_KEY"), reason="SOFYA_API_KEY not set")
+
+
+class TestSofyaSearchIntegration(ToolsIntegrationTests):
+    @property
+    def tool_constructor(self) -> type[BaseTool]:
+        return SofyaSearch
+
+    @property
+    def tool_constructor_params(self) -> dict[str, Any]:
+        return {"max_results": 3, "search_depth": "snippets"}
+
+    @property
+    def tool_invoke_params_example(self) -> dict[str, Any]:
+        return {"query": "Python programming language"}
+
+
+class TestSofyaFetchIntegration(ToolsIntegrationTests):
+    @property
+    def tool_constructor(self) -> type[BaseTool]:
+        return SofyaFetch
+
+    @property
+    def tool_constructor_params(self) -> dict[str, Any]:
+        return {}
+
+    @property
+    def tool_invoke_params_example(self) -> dict[str, Any]:
+        return {"urls": ["https://example.com"]}
+
+
+class TestSofyaExtractIntegration(ToolsIntegrationTests):
+    @property
+    def tool_constructor(self) -> type[BaseTool]:
+        return SofyaExtract
+
+    @property
+    def tool_constructor_params(self) -> dict[str, Any]:
+        return {}
+
+    @property
+    def tool_invoke_params_example(self) -> dict[str, Any]:
+        return {"url": "https://example.com", "prompt": "What is the page's heading?"}
+
+
+@pytest.mark.skipif(not os.environ.get("SOFYA_TEST_RESEARCH"), reason="set SOFYA_TEST_RESEARCH=1")
+class TestSofyaResearchIntegration(ToolsIntegrationTests):
+    @property
+    def tool_constructor(self) -> type[BaseTool]:
+        return SofyaResearch
+
+    @property
+    def tool_constructor_params(self) -> dict[str, Any]:
+        return {"max_sources": 5}
+
+    @property
+    def tool_invoke_params_example(self) -> dict[str, Any]:
+        return {"query": "What is the capital of Australia and why was it chosen?"}

langchain_sofya-0.1.0/tests/unit_tests/test_standard.py

@@ -0,0 +1,87 @@
+"""LangChain standard unit tests for each Sofya tool."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from langchain_core.tools import BaseTool
+from langchain_tests.unit_tests import ToolsUnitTests
+
+from langchain_sofya import SofyaExtract, SofyaFetch, SofyaResearch, SofyaSearch
+
+_KEY = "sofya_live_test"
+
+
+class TestSofyaSearchUnit(ToolsUnitTests):
+    @property
+    def tool_constructor(self) -> type[BaseTool]:
+        return SofyaSearch
+
+    @property
+    def tool_constructor_params(self) -> dict[str, Any]:
+        return {"api_key": _KEY, "max_results": 5}
+
+    @property
+    def tool_invoke_params_example(self) -> dict[str, Any]:
+        return {"query": "latest stable Python release", "include_answer": True}
+
+    @property
+    def init_from_env_params(self) -> tuple[dict[str, str], dict[str, Any], dict[str, Any]]:
+        return {"SOFYA_API_KEY": "sofya_live_env"}, {}, {"name": "sofya_search"}
+
+
+class TestSofyaFetchUnit(ToolsUnitTests):
+    @property
+    def tool_constructor(self) -> type[BaseTool]:
+        return SofyaFetch
+
+    @property
+    def tool_constructor_params(self) -> dict[str, Any]:
+        return {"api_key": _KEY}
+
+    @property
+    def tool_invoke_params_example(self) -> dict[str, Any]:
+        return {"urls": ["https://example.com"]}
+
+    @property
+    def init_from_env_params(self) -> tuple[dict[str, str], dict[str, Any], dict[str, Any]]:
+        return {"SOFYA_API_KEY": "sofya_live_env"}, {}, {"name": "sofya_fetch"}
+
+
+class TestSofyaExtractUnit(ToolsUnitTests):
+    @property
+    def tool_constructor(self) -> type[BaseTool]:
+        return SofyaExtract
+
+    @property
+    def tool_constructor_params(self) -> dict[str, Any]:
+        return {"api_key": _KEY}
+
+    @property
+    def tool_invoke_params_example(self) -> dict[str, Any]:
+        return {
+            "url": "https://en.wikipedia.org/wiki/Eiffel_Tower",
+            "prompt": "How tall is it and when did it open?",
+        }
+
+    @property
+    def init_from_env_params(self) -> tuple[dict[str, str], dict[str, Any], dict[str, Any]]:
+        return {"SOFYA_API_KEY": "sofya_live_env"}, {}, {"name": "sofya_extract"}
+
+
+class TestSofyaResearchUnit(ToolsUnitTests):
+    @property
+    def tool_constructor(self) -> type[BaseTool]:
+        return SofyaResearch
+
+    @property
+    def tool_constructor_params(self) -> dict[str, Any]:
+        return {"api_key": _KEY, "max_sources": 10}
+
+    @property
+    def tool_invoke_params_example(self) -> dict[str, Any]:
+        return {"query": "How do heat pumps perform in cold climates?"}
+
+    @property
+    def init_from_env_params(self) -> tuple[dict[str, str], dict[str, Any], dict[str, Any]]:
+        return {"SOFYA_API_KEY": "sofya_live_env"}, {}, {"name": "sofya_research"}

langchain_sofya-0.1.0/tests/unit_tests/test_tools.py

@@ -0,0 +1,169 @@
+"""Behaviour tests with the HTTP layer mocked: payloads, defaults and errors."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import httpx
+import pytest
+from langchain_core.messages import ToolMessage
+from langchain_core.tools import ToolException
+
+from langchain_sofya import (
+    SofyaAPIWrapper,
+    SofyaExtract,
+    SofyaFetch,
+    SofyaResearch,
+    SofyaSearch,
+    __version__,
+)
+
+
+class _Recorder:
+    """Swaps httpx's transport for one that records requests and replies."""
+
+    def __init__(self, monkeypatch: pytest.MonkeyPatch, status: int = 200, body: Any = None):
+        self.requests: list[httpx.Request] = []
+        self.body = {"ok": True, "credits_used": 1} if body is None else body
+        self.status = status
+        transport = httpx.MockTransport(self._handle)
+        real_client, real_async = httpx.Client, httpx.AsyncClient
+
+        def client(*a: Any, **kw: Any) -> httpx.Client:
+            return real_client(*a, transport=transport, **kw)
+
+        def async_client(*a: Any, **kw: Any) -> httpx.AsyncClient:
+            return real_async(*a, transport=transport, **kw)
+
+        monkeypatch.setattr(httpx, "Client", client)
+        monkeypatch.setattr(httpx, "AsyncClient", async_client)
+
+    def _handle(self, request: httpx.Request) -> httpx.Response:
+        self.requests.append(request)
+        if isinstance(self.body, str):
+            return httpx.Response(self.status, text=self.body)
+        return httpx.Response(self.status, json=self.body)
+
+    @property
+    def last(self) -> httpx.Request:
+        return self.requests[-1]
+
+    @property
+    def last_json(self) -> dict[str, Any]:
+        return json.loads(self.last.content)
+
+
+def test_missing_key_raises(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("SOFYA_API_KEY", raising=False)
+    with pytest.raises(ValueError, match="SOFYA_API_KEY"):
+        SofyaSearch()
+
+
+def test_key_from_env_and_base_url(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("SOFYA_API_KEY", "sofya_live_env")
+    monkeypatch.setenv("SOFYA_BASE_URL", "http://localhost:9999/")
+    w = SofyaAPIWrapper()
+    assert w.api_key.get_secret_value() == "sofya_live_env"
+    assert w._url("/v1/search") == "http://localhost:9999/v1/search"
+
+
+def test_key_is_secret() -> None:
+    tool = SofyaSearch(api_key="sofya_live_secret")
+    assert "sofya_live_secret" not in repr(tool)
+
+
+def test_search_payload_headers_and_defaults(monkeypatch: pytest.MonkeyPatch) -> None:
+    rec = _Recorder(monkeypatch)
+    tool = SofyaSearch(api_key="k", max_results=5, include_answer=True, topic="news")
+    out = tool.invoke({"query": "q", "max_results": 3, "include_domains": ["github.com"]})
+    assert out == {"ok": True, "credits_used": 1}
+    assert str(rec.last.url) == "https://sofya.co/v1/search"
+    assert rec.last.headers["authorization"] == "Bearer k"
+    assert rec.last.headers["user-agent"] == f"langchain-sofya/{__version__}"
+    # the call's own value wins, tool defaults fill the rest, unset keys are omitted
+    assert rec.last_json == {
+        "query": "q",
+        "max_results": 3,
+        "include_answer": True,
+        "include_domains": ["github.com"],
+        "topic": "news",
+    }
+
+
+def test_search_minimal_payload(monkeypatch: pytest.MonkeyPatch) -> None:
+    rec = _Recorder(monkeypatch)
+    SofyaSearch(api_key="k").invoke({"query": "q"})
+    assert rec.last_json == {"query": "q"}
+
+
+def test_fetch(monkeypatch: pytest.MonkeyPatch) -> None:
+    rec = _Recorder(monkeypatch)
+    SofyaFetch(api_key="k").invoke({"urls": ["https://a.test", "https://b.test"]})
+    assert str(rec.last.url).endswith("/v1/fetch")
+    assert rec.last_json == {"urls": ["https://a.test", "https://b.test"]}
+    SofyaFetch(api_key="k", include_raw_html=True).invoke({"urls": ["https://a.test"]})
+    assert rec.last_json == {"urls": ["https://a.test"], "include_raw_html": True}
+
+
+def test_fetch_rejects_too_many_urls() -> None:
+    tool = SofyaFetch(api_key="k")
+    with pytest.raises(Exception):
+        tool.invoke({"urls": [f"https://x{i}.test" for i in range(11)]})
+
+
+def test_extract(monkeypatch: pytest.MonkeyPatch) -> None:
+    rec = _Recorder(monkeypatch)
+    SofyaExtract(api_key="k").invoke({"url": "https://a.test", "prompt": "p"})
+    assert str(rec.last.url).endswith("/v1/extract")
+    assert rec.last_json == {"url": "https://a.test", "prompt": "p"}
+
+
+def test_research(monkeypatch: pytest.MonkeyPatch) -> None:
+    rec = _Recorder(monkeypatch)
+    SofyaResearch(api_key="k", max_sources=10).invoke({"query": "q", "topic": "news"})
+    assert str(rec.last.url).endswith("/v1/research")
+    assert rec.last_json == {"query": "q", "topic": "news", "max_sources": 10}
+
+
+async def test_async(monkeypatch: pytest.MonkeyPatch) -> None:
+    rec = _Recorder(monkeypatch)
+    out = await SofyaSearch(api_key="k").ainvoke({"query": "q"})
+    assert out["ok"] is True
+    assert rec.last_json == {"query": "q"}
+
+
+@pytest.mark.parametrize(
+    ("status", "body", "expected"),
+    [
+        (401, {"detail": "Invalid API key"}, "missing or invalid"),
+        (402, {"detail": "Insufficient credits"}, "out of credits"),
+        (429, {"detail": "Too many requests"}, "rate limit"),
+        (422, {"detail": [{"msg": "bad"}]}, "rejected the request"),
+        (500, "boom", "HTTP 500"),
+    ],
+)
+def test_errors_become_tool_messages(
+    monkeypatch: pytest.MonkeyPatch, status: int, body: Any, expected: str
+) -> None:
+    _Recorder(monkeypatch, status=status, body=body)
+    tool = SofyaSearch(api_key="k")
+    with pytest.raises(ToolException, match=expected):
+        tool._run(query="q")
+    # Through invoke with a tool call, the error is returned to the model.
+    msg = tool.invoke({"name": tool.name, "args": {"query": "q"}, "id": "1", "type": "tool_call"})
+    assert isinstance(msg, ToolMessage)
+    assert expected in str(msg.content)
+
+
+def test_network_error(monkeypatch: pytest.MonkeyPatch) -> None:
+    real_client = httpx.Client
+
+    def boom(request: httpx.Request) -> httpx.Response:
+        raise httpx.ConnectError("no route")
+
+    monkeypatch.setattr(
+        httpx, "Client", lambda *a, **kw: real_client(*a, transport=httpx.MockTransport(boom), **kw)
+    )
+    with pytest.raises(ToolException, match="request failed"):
+        SofyaSearch(api_key="k")._run(query="q")