langchain-youdotcom 0.1.0__tar.gz

langchain_youdotcom-0.1.0/.claude/settings.local.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv sync:*)",
+      "Bash(make check_imports:*)",
+      "Bash(make test:*)",
+      "Bash(uv run python -c:*)",
+      "Bash(uv run python:*)",
+      "Bash(uv build:*)"
+    ]
+  }
+}

langchain_youdotcom-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,182 @@
+name: Publish Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: "Version bump type"
+        required: true
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+      prerelease:
+        description: "Prerelease number (optional, creates x.y.z.devN)"
+        required: false
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  update-version:
+    runs-on: ubuntu-latest
+    name: Update Version
+    permissions:
+      contents: write
+    outputs:
+      version: ${{ steps.set_version.outputs.version }}
+      is_prerelease: ${{ steps.set_version.outputs.is_prerelease }}
+    steps:
+      - name: Validate inputs
+        env:
+          INPUT_BUMP: ${{ inputs.bump }}
+          INPUT_PRERELEASE: ${{ inputs.prerelease }}
+        run: |
+          if [[ "$INPUT_BUMP" != "patch" && "$INPUT_BUMP" != "minor" && "$INPUT_BUMP" != "major" ]]; then
+            echo "::error::Invalid bump type: $INPUT_BUMP"
+            exit 1
+          fi
+
+          if [[ -n "$INPUT_PRERELEASE" ]] && ! echo "$INPUT_PRERELEASE" | grep -qE '^[0-9]+$'; then
+            echo "::error::Prerelease must be a number, got: $INPUT_PRERELEASE"
+            exit 1
+          fi
+
+          echo "✓ Input validation passed"
+
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.PUBLISH_TOKEN }}
+
+      - name: Compute version
+        id: set_version
+        env:
+          INPUT_BUMP: ${{ inputs.bump }}
+          INPUT_PRERELEASE: ${{ inputs.prerelease }}
+          BRANCH_NAME: ${{ github.ref_name }}
+        run: |
+          CURRENT=$(grep '^version = ' pyproject.toml | sed 's/version = "\(.*\)"/\1/')
+          echo "Current version: $CURRENT"
+
+          BASE=$(echo "$CURRENT" | grep -oE '^[0-9]+\.[0-9]+\.[0-9]+')
+          IFS='.' read -r MAJOR MINOR PATCH <<< "$BASE"
+
+          case "$INPUT_BUMP" in
+            major) BASE_VERSION="$((MAJOR + 1)).0.0" ;;
+            minor) BASE_VERSION="${MAJOR}.$((MINOR + 1)).0" ;;
+            patch) BASE_VERSION="${MAJOR}.${MINOR}.$((PATCH + 1))" ;;
+          esac
+
+          echo "Bumped base: $BASE_VERSION"
+
+          if [[ -n "$INPUT_PRERELEASE" ]]; then
+            echo "version=${BASE_VERSION}.dev${INPUT_PRERELEASE}" >> "$GITHUB_OUTPUT"
+            echo "is_prerelease=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "version=${BASE_VERSION}" >> "$GITHUB_OUTPUT"
+            echo "is_prerelease=false" >> "$GITHUB_OUTPUT"
+          fi
+
+          echo "✅ Computed version: $(grep '^version=' "$GITHUB_OUTPUT" | head -1)"
+
+      - name: Validate computed version
+        env:
+          VERSION: ${{ steps.set_version.outputs.version }}
+        run: |
+          if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(\.dev[0-9]+)?$ ]]; then
+            echo "::error::Invalid version: $VERSION"
+            exit 1
+          fi
+          echo "✅ Version format valid: $VERSION"
+
+      - uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Configure Git
+        env:
+          GIT_AUTHOR_NAME: ${{ github.actor }}
+          GIT_AUTHOR_EMAIL: ${{ github.actor }}@users.noreply.github.com
+        run: |
+          git config user.name "$GIT_AUTHOR_NAME"
+          git config user.email "$GIT_AUTHOR_EMAIL"
+
+      - name: Bump version in pyproject.toml and lock
+        env:
+          VERSION: ${{ steps.set_version.outputs.version }}
+          BRANCH_NAME: ${{ github.ref_name }}
+        run: |
+          sed -i "s/^version = \".*\"/version = \"${VERSION}\"/" pyproject.toml
+          uv lock
+
+          WRITTEN=$(grep '^version = ' pyproject.toml | sed 's/version = "\(.*\)"/\1/')
+          if [[ "$WRITTEN" != "$VERSION" ]]; then
+            echo "::error::Version mismatch after write: $WRITTEN != $VERSION"
+            exit 1
+          fi
+
+          git add pyproject.toml uv.lock
+          if ! git diff --staged --quiet; then
+            git commit -m "ci: publish v${VERSION} [skip ci]"
+            git push origin "$BRANCH_NAME"
+          fi
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    name: Publish to PyPI
+    needs: [update-version]
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.ref_name }}
+
+      - uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI (Trusted Publishing)
+        env:
+          IS_PRERELEASE: ${{ needs.update-version.outputs.is_prerelease }}
+        run: uv publish --trusted-publishing always
+
+  create-release:
+    runs-on: ubuntu-latest
+    name: Create GitHub Release
+    needs: [update-version, pypi-publish]
+    if: always() && needs.pypi-publish.result == 'success'
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.ref_name }}
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.PUBLISH_TOKEN }}
+          VERSION: ${{ needs.update-version.outputs.version }}
+          IS_PRERELEASE: ${{ needs.update-version.outputs.is_prerelease }}
+        run: |
+          TAG="v${VERSION}"
+
+          if [[ "$IS_PRERELEASE" == "true" ]]; then
+            gh release create "${TAG}" \
+              --title "${TAG}" \
+              --generate-notes \
+              --prerelease
+          else
+            gh release create "${TAG}" \
+              --title "${TAG}" \
+              --generate-notes
+          fi

langchain_youdotcom-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,51 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      run_integration:
+        description: "Run integration tests"
+        type: boolean
+        default: false
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+      - run: uv sync --all-groups
+      - run: make lint
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv sync --all-groups --python ${{ matrix.python-version }}
+      - run: make test
+
+  integration:
+    if: github.event_name == 'workflow_dispatch' && inputs.run_integration
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+      - run: uv sync --all-groups
+      - run: make integration_tests
+        env:
+          YDC_API_KEY: ${{ secrets.YDC_API_KEY }}

langchain_youdotcom-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+*.so
+.venv/
+.env

langchain_youdotcom-0.1.0/CLAUDE.md

@@ -0,0 +1,27 @@
+# langchain-youdotcom
+
+LangChain partner package for You.com search and content APIs.
+
+## Build & test
+
+```bash
+uv sync --all-groups     # install all deps
+make format              # ruff format + fix
+make lint                # ruff check + format diff + mypy
+make test                # unit tests (pytest)
+make integration_tests   # integration tests (needs YDC_API_KEY)
+make check_imports       # verify all .py files importable
+```
+
+## Architecture
+
+- `langchain_youdotcom/_utilities.py` — `YouSearchAPIWrapper` (API client)
+- `langchain_youdotcom/retrievers.py` — `YouRetriever` (BaseRetriever subclass)
+- `langchain_youdotcom/tools.py` — `YouSearchTool` + `YouContentsTool` (BaseTool subclasses)
+
+## Conventions
+
+- Depends on `langchain-core` only, never full `langchain`
+- Delegates HTTP to the `youdotcom` SDK
+- Google-style docstrings, full type hints
+- Ruff for linting/formatting, mypy for type checking

langchain_youdotcom-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 You.com 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_youdotcom-0.1.0/Makefile

@@ -0,0 +1,42 @@
+.PHONY: all format lint type test tests integration_tests check_imports help
+
+.EXPORT_ALL_VARIABLES:
+UV_FROZEN = true
+
+PYTHON_FILES = langchain_youdotcom tests scripts
+MYPY_CACHE = .mypy_cache
+
+TEST_FILE ?= tests/unit_tests/
+integration_tests: TEST_FILE=tests/integration_tests/
+
+test tests integration_tests:
+	uv run --all-groups pytest $(TEST_FILE)
+
+check_imports: $(shell find langchain_youdotcom -name '*.py')
+	uv run --all-groups python ./scripts/check_imports.py $^
+
+lint lint_diff lint_package lint_tests:
+	./scripts/lint_imports.sh
+	[ "$(PYTHON_FILES)" = "" ] || uv run --all-groups ruff check $(PYTHON_FILES)
+	[ "$(PYTHON_FILES)" = "" ] || uv run --all-groups ruff format $(PYTHON_FILES) --diff
+	[ "$(PYTHON_FILES)" = "" ] || mkdir -p $(MYPY_CACHE) && uv run --all-groups mypy $(PYTHON_FILES) --cache-dir $(MYPY_CACHE)
+
+type:
+	mkdir -p $(MYPY_CACHE) && uv run --all-groups mypy $(PYTHON_FILES) --cache-dir $(MYPY_CACHE)
+
+format format_diff:
+	[ "$(PYTHON_FILES)" = "" ] || uv run --all-groups ruff format $(PYTHON_FILES)
+	[ "$(PYTHON_FILES)" = "" ] || uv run --all-groups ruff check --fix $(PYTHON_FILES)
+
+lint_diff format_diff: PYTHON_FILES=$(shell git diff --name-only --diff-filter=d main | grep -E '\.py$$|\.ipynb$$')
+lint_package: PYTHON_FILES=langchain_youdotcom
+lint_tests: PYTHON_FILES=tests
+
+help:
+	@echo "Available targets:"
+	@echo "  format            - Format code with ruff"
+	@echo "  lint              - Run ruff check, ruff format --diff, and mypy"
+	@echo "  type              - Run mypy type checking"
+	@echo "  test              - Run unit tests"
+	@echo "  integration_tests - Run integration tests"
+	@echo "  check_imports     - Verify all modules are importable"

langchain_youdotcom-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: langchain-youdotcom
+Version: 0.1.0
+Summary: An integration package connecting You.com and LangChain
+Project-URL: Homepage, https://you.com
+Project-URL: Documentation, https://docs.you.com
+Project-URL: Repository, https://github.com/youdotcom-oss/langchain-youdotcom
+Project-URL: Issues, https://github.com/youdotcom-oss/langchain-youdotcom/issues
+Project-URL: Changelog, https://github.com/youdotcom-oss/langchain-youdotcom/releases
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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 :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: <4.0.0,>=3.10.0
+Requires-Dist: langchain-core<2.0.0,>=1.0.0
+Requires-Dist: youdotcom<3.0.0,>=2.2.0
+Description-Content-Type: text/markdown
+
+# langchain-youdotcom
+
+[![PyPI - Version](https://img.shields.io/pypi/v/langchain-youdotcom?label=%20)](https://pypi.org/project/langchain-youdotcom/#history)
+[![PyPI - License](https://img.shields.io/pypi/l/langchain-youdotcom)](https://opensource.org/licenses/MIT)
+[![PyPI - Downloads](https://img.shields.io/pepy/dt/langchain-youdotcom)](https://pypistats.org/packages/langchain-youdotcom)
+
+LangChain partner package for [You.com](https://you.com) search and content APIs.
+
+## Installation
+
+```bash
+pip install -U langchain-youdotcom
+```
+
+## Credentials
+
+Get an API key at [you.com/platform/api-keys](https://you.com/platform/api-keys), then set it as an environment variable:
+
+```bash
+export YDC_API_KEY="your-api-key"
+```
+
+Or pass it directly when instantiating any component:
+
+```python
+retriever = YouRetriever(ydc_api_key="your-api-key")
+```
+
+## Retriever
+
+The simplest way to get You.com search results as LangChain documents.
+
+```python
+from langchain_youdotcom import YouRetriever
+
+retriever = YouRetriever()
+docs = retriever.invoke("latest AI news")
+
+for doc in docs:
+    print(doc.metadata["title"])
+    print(doc.page_content[:200])
+    print()
+```
+
+All search parameters are available directly on the retriever:
+
+```python
+retriever = YouRetriever(
+    k=5,                    # max documents to return
+    count=10,               # max results per API section
+    livecrawl="web",        # fetch live page content
+    livecrawl_formats="markdown",
+    country="US",
+    freshness="week",       # day, week, month, year
+    safesearch="moderate",  # off, moderate, strict
+)
+```
+
+## Tools
+
+### YouSearchTool
+
+Search the web with You.com. Works with any LangChain agent.
+
+```python
+from langchain_youdotcom import YouSearchTool
+
+tool = YouSearchTool()
+result = tool.invoke("what is retrieval augmented generation")
+print(result)
+```
+
+### YouContentsTool
+
+Fetch and extract content from web pages.
+
+```python
+from langchain_youdotcom import YouContentsTool
+
+tool = YouContentsTool()
+result = tool.invoke({"urls": ["https://example.com"]})
+print(result)
+```
+
+### Using with an agent
+
+```python
+from langchain_openai import ChatOpenAI
+from langgraph.prebuilt import create_react_agent
+
+from langchain_youdotcom import YouSearchTool
+
+tools = [YouSearchTool()]
+agent = create_react_agent(ChatOpenAI(model="gpt-4o"), tools)
+
+response = agent.invoke(
+    {"messages": [{"role": "user", "content": "what happened in AI today?"}]}
+)
+```
+
+## YouSearchAPIWrapper
+
+For more control, use the wrapper directly. It powers the retriever and tools under the hood.
+
+```python
+from langchain_youdotcom import YouSearchAPIWrapper
+
+wrapper = YouSearchAPIWrapper()
+
+# search -> list[Document]
+docs = wrapper.results("latest AI news")
+
+# raw SDK response
+raw = wrapper.raw_results("latest AI news")
+
+# contents API -> list[Document]
+pages = wrapper.contents(
+    ["https://example.com"],
+    formats=["markdown", "metadata"],
+)
+```
+
+Async variants are available as `results_async`, `raw_results_async`, and `contents_async`.
+
+## Documentation
+
+- [You.com API docs](https://docs.you.com)
+- [You.com API keys](https://you.com/platform/api-keys)
+
+## Development
+
+```bash
+uv sync --all-groups
+make format            # ruff format + fix
+make lint              # ruff check + format diff + mypy
+make test              # unit tests
+make integration_tests # requires YDC_API_KEY
+make check_imports     # verify all modules importable
+```

langchain_youdotcom-0.1.0/README.md

@@ -0,0 +1,139 @@
+# langchain-youdotcom
+
+[![PyPI - Version](https://img.shields.io/pypi/v/langchain-youdotcom?label=%20)](https://pypi.org/project/langchain-youdotcom/#history)
+[![PyPI - License](https://img.shields.io/pypi/l/langchain-youdotcom)](https://opensource.org/licenses/MIT)
+[![PyPI - Downloads](https://img.shields.io/pepy/dt/langchain-youdotcom)](https://pypistats.org/packages/langchain-youdotcom)
+
+LangChain partner package for [You.com](https://you.com) search and content APIs.
+
+## Installation
+
+```bash
+pip install -U langchain-youdotcom
+```
+
+## Credentials
+
+Get an API key at [you.com/platform/api-keys](https://you.com/platform/api-keys), then set it as an environment variable:
+
+```bash
+export YDC_API_KEY="your-api-key"
+```
+
+Or pass it directly when instantiating any component:
+
+```python
+retriever = YouRetriever(ydc_api_key="your-api-key")
+```
+
+## Retriever
+
+The simplest way to get You.com search results as LangChain documents.
+
+```python
+from langchain_youdotcom import YouRetriever
+
+retriever = YouRetriever()
+docs = retriever.invoke("latest AI news")
+
+for doc in docs:
+    print(doc.metadata["title"])
+    print(doc.page_content[:200])
+    print()
+```
+
+All search parameters are available directly on the retriever:
+
+```python
+retriever = YouRetriever(
+    k=5,                    # max documents to return
+    count=10,               # max results per API section
+    livecrawl="web",        # fetch live page content
+    livecrawl_formats="markdown",
+    country="US",
+    freshness="week",       # day, week, month, year
+    safesearch="moderate",  # off, moderate, strict
+)
+```
+
+## Tools
+
+### YouSearchTool
+
+Search the web with You.com. Works with any LangChain agent.
+
+```python
+from langchain_youdotcom import YouSearchTool
+
+tool = YouSearchTool()
+result = tool.invoke("what is retrieval augmented generation")
+print(result)
+```
+
+### YouContentsTool
+
+Fetch and extract content from web pages.
+
+```python
+from langchain_youdotcom import YouContentsTool
+
+tool = YouContentsTool()
+result = tool.invoke({"urls": ["https://example.com"]})
+print(result)
+```
+
+### Using with an agent
+
+```python
+from langchain_openai import ChatOpenAI
+from langgraph.prebuilt import create_react_agent
+
+from langchain_youdotcom import YouSearchTool
+
+tools = [YouSearchTool()]
+agent = create_react_agent(ChatOpenAI(model="gpt-4o"), tools)
+
+response = agent.invoke(
+    {"messages": [{"role": "user", "content": "what happened in AI today?"}]}
+)
+```
+
+## YouSearchAPIWrapper
+
+For more control, use the wrapper directly. It powers the retriever and tools under the hood.
+
+```python
+from langchain_youdotcom import YouSearchAPIWrapper
+
+wrapper = YouSearchAPIWrapper()
+
+# search -> list[Document]
+docs = wrapper.results("latest AI news")
+
+# raw SDK response
+raw = wrapper.raw_results("latest AI news")
+
+# contents API -> list[Document]
+pages = wrapper.contents(
+    ["https://example.com"],
+    formats=["markdown", "metadata"],
+)
+```
+
+Async variants are available as `results_async`, `raw_results_async`, and `contents_async`.
+
+## Documentation
+
+- [You.com API docs](https://docs.you.com)
+- [You.com API keys](https://you.com/platform/api-keys)
+
+## Development
+
+```bash
+uv sync --all-groups
+make format            # ruff format + fix
+make lint              # ruff check + format diff + mypy
+make test              # unit tests
+make integration_tests # requires YDC_API_KEY
+make check_imports     # verify all modules importable
+```

langchain_youdotcom-0.1.0/langchain_youdotcom/__init__.py

@@ -0,0 +1,12 @@
+"""LangChain integration for You.com."""
+
+from langchain_youdotcom._utilities import YouSearchAPIWrapper
+from langchain_youdotcom.retrievers import YouRetriever
+from langchain_youdotcom.tools import YouContentsTool, YouSearchTool
+
+__all__ = [
+    "YouContentsTool",
+    "YouRetriever",
+    "YouSearchAPIWrapper",
+    "YouSearchTool",
+]