Metadata-Version: 2.5
Name: llama-index-tools-truth-bear-gauge
Version: 0.1.0
Summary: LlamaIndex tools for Truth Bear GAUGE official-source signal data
Project-URL: Homepage, https://github.com/CHANGCHINFU/llama-index-tools-truth-bear-gauge
Project-URL: Repository, https://github.com/CHANGCHINFU/llama-index-tools-truth-bear-gauge
Author: TruthBear
License-Expression: MIT
License-File: LICENSE
Requires-Python: <4.0,>=3.10
Requires-Dist: llama-index-core<0.15,>=0.13.0
Description-Content-Type: text/markdown

# llama-index-tools-truth-bear-gauge

LlamaIndex tool spec 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 llama-index-tools-truth-bear-gauge
```

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

## Tools

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

## Quick start

```python
from llama_index.tools.truth_bear_gauge import TruthBearGaugeToolSpec

spec = TruthBearGaugeToolSpec()
tools = spec.to_tool_list()

# Use directly
print(spec.coverage_check(signal_id="hydrology.river-level"))
print(spec.catalog_lookup(signal_id="hydrology.river-level"))
```

## With an agent

```python
from llama_index.core.agent import ReActAgent
from llama_index.tools.truth_bear_gauge import TruthBearGaugeToolSpec

tools = TruthBearGaugeToolSpec().to_tool_list()
agent = ReActAgent.from_tools(tools, llm=your_llm, verbose=True)
agent.chat("Is the hydrology.river-level signal line on schedule?")
```

## Design notes

- **Standard library only** — no dependency beyond `llama-index-core`.
- **No money moves here.** `record_request` 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` returns an error.
- **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.
