langchain-sofya 0.1.0__py3-none-any.whl

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/_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/_version.py

@@ -0,0 +1 @@
+__version__ = "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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+langchain_sofya/__init__.py,sha256=yDCixYxOqorjn6rzPi39LXeJa1JwaM-2DboC2ukR1us,425
+langchain_sofya/_client.py,sha256=IsdAuihJdtS4FQadcQvk0hCbG5McK_MBDzT6ybKnPRE,4081
+langchain_sofya/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+langchain_sofya/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+langchain_sofya/tools.py,sha256=amSSPFy5SCb-httudyXZqOgm6AiW0BfkVQKPzlwJslc,11165
+langchain_sofya-0.1.0.dist-info/METADATA,sha256=veXS-8ke4pqyupzKrzPR4sb4iyZt6boXdYRo8rDqZns,4287
+langchain_sofya-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+langchain_sofya-0.1.0.dist-info/licenses/LICENSE,sha256=ZG-YkZd8UposWuGcPaZ9D3OIjnqw-Ub4B0a0paKe7bg,1068
+langchain_sofya-0.1.0.dist-info/RECORD,,

langchain_sofya-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

langchain_sofya-0.1.0.dist-info/licenses/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.