Metadata-Version: 2.5
Name: langchain-truthbear
Version: 0.1.0
Summary: LangChain tools for Truth Bear GAUGE official-source signal data
Project-URL: Homepage, https://github.com/CHANGCHINFU/langchain-truthbear
Project-URL: Repository, https://github.com/CHANGCHINFU/langchain-truthbear
Author: TruthBear
License-Expression: MIT
License-File: LICENSE
Requires-Python: <3.15,>=3.10
Requires-Dist: langchain-core<2.0.0,>=1.4.7
Description-Content-Type: text/markdown

# langchain-truthbear

LangChain tools for [Truth Bear GAUGE](https://api.truthbear.co), a pay-per-call source of
official-record signals (US federal agencies and named registries).

## Installation

```bash
pip install langchain-truthbear
```

No API key, no account, no signup for the two free tools.

## Tools

| Tool | Cost | Purpose |
| ---- | ---- | ------- |
| `GaugeCoverage` | free | Does a signal line exist, how many objects, how fresh, is the source agency on schedule |
| `GaugeCatalog` | free | Which entity ids are valid for a signal line — filter by `signal_id` or `industry` (one required) |
| `GaugeRecord` | paid (x402) | Requests one official record; returns the HTTP 402 payment challenge untouched |

## Quick start

```python
from langchain_truthbear import GaugeCoverage, GaugeCatalog

# Check a signal line
coverage = GaugeCoverage()
print(coverage.invoke({"signal_id": "hydrology.river-level"}))

# Find valid entities
catalog = GaugeCatalog()
print(catalog.invoke({"signal_id": "hydrology.river-level"}))
```

## With an agent

```python
from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain_truthbear import GaugeCoverage, GaugeCatalog

tools = [GaugeCoverage(), GaugeCatalog()]
# ... set up your agent with these tools
```

## Design notes

- **Standard library only** — no dependency beyond `langchain-core`.
- **No money moves here.** `GaugeRecord` returns the x402 challenge untouched; settling it is the
  caller's own wallet's job.
- **The catalog filter is required.** The unfiltered response is ~1.5 MB — too large for an agent's
  context — so a call with neither `signal_id` nor `industry` is rejected.
- **A miss is not an error.** An unknown `signal_id` returns `{"found": false}` rather than raising.
- Every paid record ships a canonical sha256 `record_hash` that can be recomputed offline.
