Metadata-Version: 2.4
Name: langchain-polaris
Version: 0.1.0
Summary: LangChain integration for The Polaris Report — verified news intelligence tools and retriever
Project-URL: Homepage, https://thepolarisreport.com
Project-URL: Documentation, https://thepolarisreport.com/docs
Project-URL: Repository, https://github.com/JohnnyTarrr/polaris-sdks
Author-email: The Polaris Report <dev@thepolarisreport.com>
License-Expression: MIT
Keywords: agents,ai,langchain,news,polaris,retriever,tools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Requires-Dist: langchain-core>=0.1.0
Requires-Dist: polaris-news>=0.2.0
Description-Content-Type: text/markdown

# langchain-polaris

LangChain integration for [The Polaris Report](https://thepolarisreport.com) — verified news intelligence with confidence scores, bias ratings, and source analysis.

## Installation

```bash
pip install langchain-polaris
```

## Quick Start

### Agent with Tools

```python
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_openai_tools_agent
from langchain_core.prompts import ChatPromptTemplate
from langchain_polaris import PolarisSearchTool, PolarisBriefTool, PolarisCompareTool

tools = [
    PolarisSearchTool(api_key="your-api-key"),
    PolarisBriefTool(api_key="your-api-key"),
    PolarisCompareTool(api_key="your-api-key"),
]

prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a news research assistant with access to verified intelligence."),
    ("human", "{input}"),
    ("placeholder", "{agent_scratchpad}"),
])

llm = ChatOpenAI(model="gpt-4o")
agent = create_openai_tools_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools)

result = executor.invoke({"input": "What's happening with AI regulation?"})
print(result["output"])
```

### Retriever for RAG

```python
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnablePassthrough
from langchain_core.output_parsers import StrOutputParser
from langchain_polaris import PolarisRetriever

retriever = PolarisRetriever(
    api_key="your-api-key",
    category="ai_ml",
    min_confidence=0.7,
    limit=5,
)

prompt = ChatPromptTemplate.from_template(
    "Answer based on these verified news briefs:\n\n{context}\n\nQuestion: {question}"
)

chain = (
    {"context": retriever, "question": RunnablePassthrough()}
    | prompt
    | ChatOpenAI(model="gpt-4o")
    | StrOutputParser()
)

print(chain.invoke("What are the latest developments in AI?"))
```

## Tools

| Tool | Description |
|------|-------------|
| `PolarisSearchTool` | Search verified news intelligence across 18 verticals. Supports category filtering and speed tiers (`depth`: fast, standard, deep). |
| `PolarisFeedTool` | Get latest verified news briefs, optionally filtered by category or source domain. |
| `PolarisEntityTool` | Look up entities (companies, people, technologies) mentioned in verified news coverage. |
| `PolarisBriefTool` | Get a specific verified news brief by ID with full analysis, sources, and counter-arguments. |
| `PolarisExtractTool` | Extract clean article content from URLs. Returns structured text with metadata. |
| `PolarisCompareTool` | Compare how different news outlets covered the same story. Shows framing, bias, and what each side emphasizes or omits. |

## Retriever

`PolarisRetriever` implements LangChain's `BaseRetriever` interface, returning `Document` objects with:

- **page_content**: Headline, summary, and body text
- **metadata**: `brief_id`, `confidence`, `bias_score`, `category`, `published_at`, `counter_argument`, `sources`, `entities`

### Retriever Options

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `api_key` | str | required | Polaris API key |
| `category` | str | None | Category filter |
| `min_confidence` | float | None | Minimum confidence score (0-1) |
| `limit` | int | 10 | Max results to return |
| `include_sources` | str | None | Comma-separated source domains to include |
| `exclude_sources` | str | None | Comma-separated source domains to exclude |

## Documentation

Full API docs at [thepolarisreport.com/docs](https://thepolarisreport.com/docs)
