langsearch

适用于 AGI 应用程序的免费网络搜索和语义重新排名 API。当您需要执行 Web 搜索、从 Internet 检索当前信息或通过语义重新排名提高搜索准确性时使用。包括用于构建 RAG（检索增强生成）管道和需要真实环境的 LLM 应用程序的集成示例。需要 LANGSEARCH_API_KEY 凭据。

## 概述（中文）

适用于 AGI 应用程序的免费网络搜索和语义重新排名 API。当您需要执行 Web 搜索、从 Internet 检索当前信息或通过语义重新排名提高搜索准确性时使用。包括用于构建 RAG（检索增强生成）管道和需要真实环境的 LLM 应用程序的集成示例。需要 LANGSEARCH_API_KEY 凭据。

## 原文

# LangSearch

## ⚠️ Security & Credentials

**Required Credentials:**
- `LANGSEARCH_API_KEY` - Your free LangSearch API key (required)

**Security Best Practices:**
1. **Get a free API key** - Sign up at [langsearch.com/api-keys](https://langsearch.com/api-keys)
2. **Protect your API key** - Never commit `.env` files containing `LANGSEARCH_API_KEY` to version control
3. **Use environment variables** - Store the key in `.env` or set via `export LANGSEARCH_API_KEY="..."`
4. **Monitor usage** - Check your API usage on the LangSearch dashboard
5. **Code inspection** - This tool only uses the official LangSearch API. All communication is via HTTPS to `api.langsearch.com`

**Network Access:**
- Only connects to: `https://api.langsearch.com` (official LangSearch API)
- No external data collection or telemetry
- No tracking or logging sent elsewhere

## Overview

LangSearch provides free APIs for web search and semantic reranking. It combines keyword search precision with vector-based semantic matching, making it ideal for integrating current web information into LLM applications and building RAG systems.

## Quick Start

### Prerequisites

1. Get a free API key at https://langsearch.com/api-keys
2. Set your API key as an environment variable: `export LANGSEARCH_API_KEY="your-api-key"`

### Basic Web Search

The simplest way to search the web using LangSearch:

```python
import requests
import json
import os

api_key = os.getenv("LANGSEARCH_API_KEY")
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

query = "latest AI developments 2025"
payload = {
    "query": query,
    "count": 5,
    "summary": True
}

response = requests.post(
    "https://api.langsearch.com/v1/web-search",
    headers=headers,
    json=payload
)

results = response.json()
print(json.dumps(results, indent=2))
```

Or using cURL:

```bash
curl -X POST https://api.langsearch.com/v1/web-search \
  -H "Authorization: Bearer $LANGSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "latest AI developments 2025",
    "count": 5,
    "summary": true
  }'
```

## Web Search API

The web search endpoint retrieves information from billions of web documents using hybrid search (keyword + vector matching) with optional summaries.

### Endpoint
`POST https://api.langsearch.com/v1/web-search`

### Request Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | The search query |
| `count` | integer | No | Number of results to return (default: 10, max: 100) |
| `summary` | boolean | No | Include markdown summaries in results (default: false) |
| `freshness` | string | No | Filter results by freshness (`day`, `week`, `month`, `year`) |

### Response Structure

The API returns an array of search results with:
- `title` - Result title
- `url` - Result URL
- `snippet` - Text excerpt from the page
- `summary` - Markdown formatted summary (if `summary: true` in request)
- `score` - Relevance score

### Example Use Cases

**Current Information Retrieval**
When your LLM needs up-to-date information:

```python
# Search for recent developments
response = requests.post(
    "https://api.langsearch.com/v1/web-search",
    headers=headers,
    json={
        "query": "Python 3.14 release notes",
        "count": 3,
        "summary": True,
        "freshness": "week"
    }
)
```

**Multi-Query Research**
Build context from multiple searches:

```python
queries = [
    "climate change mitigation strategies",
    "renewable energy trends 2025",
    "carbon capture technology"
]

all_results = []
for query in queries:
    response = requests.post(
        "https://api.langsearch.com/v1/web-search",
        headers=headers,
        json={"query": query, "count": 5, "summary": True}
    )
    all_results.extend(response.json())
```

## Semantic Reranking API

Improve search accuracy by reranking results based on semantic relevance to your query.

### Endpoint
`POST https://api.langsearch.com/v1/rerank`

### Request Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | The search query for context |
| `documents` | array | Yes | Array of documents to rerank (each with `title`, `text`, etc.) |
| `model` | string | No | Reranking model (default: `langsearch-rerank-1`) |
| `top_n` | integer | No | Number of top results to return (default: 10) |
| `return_documents` | boolean | No | Include full documents in response (default: false) |

### Example: Reranking Web Search Results

```python
# Get initial search results
search_response = requests.post(
    "https://api.langsearch.com/v1/web-search",
    headers=headers,
    json={"query": "machine learning deployment best practices", "count": 10}
)

search_results = search_response.json()

# Prepare documents for reranking
documents = [
    {"title": r.get("title", ""), "text": r.get("snippet", "")}
    for r in search_results
]

# Rerank for better relevance
rerank_response = requests.post(
    "https://api.langsearch.com/v1/rerank",
    headers=headers,
    json={
        "query": "best practices for deploying ML models in production",
        "documents": documents,
        "top_n": 5
    }
)

reranked = rerank_response.json()
```

## Building RAG Applications

Combine web search with LLM context for better information retrieval and generation:

```python
def rag_query(user_question):
    # Step 1: Search the web for relevant information
    search_response = requests.post(
        "https://api.langsearch.com/v1/web-search",
        headers=headers,
        json={
            "query": user_question,
            "count": 5,
            "summary": True
        }
    )

    search_results = search_response.json()

    # Step 2: Extract summaries and URLs for context
    context = "\n".join([
        f"- {r['title']}: {r.get('summary', r.get('snippet', ''))}"
        for r in search_results
    ])

    # Step 3: Use with your LLM
    # This is where you'd call your LLM with the context
    rag_context = f"""
Based on recent web search results:

{context}

Answer the user's question: {user_question}
"""

    return rag_context, search_results
```

## Error Handling

Common HTTP status codes:

| Status | Meaning | Action |
|--------|---------|--------|
| 200 | Success | Results returned normally |
| 401 | Unauthorized | Check API key is valid and set correctly |
| 429 | Rate limited | Retry with exponential backoff |
| 500 | Server error | Retry the request later |

See `scripts/web_search_example.py` for a complete example with error handling.

## Resources

This skill includes example resource directories that demonstrate how to organize different types of bundled resources:

### scripts/
Executable code (Python/Bash/etc.) that can be run directly to perform specific operations.

**Examples from other skills:**
- PDF skill: `fill_fillable_fields.py`, `extract_form_field_info.py` - utilities for PDF manipulation
- DOCX skill: `document.py`, `utilities.py` - Python modules for document processing

**Appropriate for:** Python scripts, shell scripts, or any executable code that performs automation, data processing, or specific operations.

**Note:** Scripts may be executed without loading into context, but can still be read by Claude for patching or environment adjustments.

### references/
Documentation and reference material intended to be loaded into context to inform Claude's process and thinking.

**Examples from other skills:**
- Product management: `communication.md`, `context_building.md` - detailed workflow guides
- BigQuery: API reference documentation and query examples
- Finance: Schema documentation, company policies

**Appropriate for:** In-depth documentation, API references, d