Tabber

An OSINT CLI tool that determines the most likely current or recent physical location of a public figure by aggregating data from multiple sources and reasoning over them with an LLM.

How It Works

1. Disambiguation — The input name is resolved to a structured person profile via LLM.
2. Feedback loop (up to N iterations):
   • The LLM generates targeted search hints based on the profile and any prior data.
   • All configured gatherers run in parallel to collect raw data.
   • The LLM evaluates whether there is sufficient location signal; exits early if so, or refines and repeats.
3. Location analysis — All gathered data is synthesised by a final LLM call into a location result with confidence and reasoning.
4. Results are displayed in a Rich terminal panel with colour-coded confidence and automatically cached to SQLite for instant recall on repeat lookups.

Installation

git clone https://github.com/itsnotqwerty/tabber.git
cd tabber
python -m venv .venv
source .venv/bin/activate
pip install -e .

To also enable the REST API server:

pip install -e ".[server]"

Configuration

Configuration is stored in ~/.tabber/config.json and managed via the config subcommand.

tabber config set <key> <value>
tabber config show

Configuration Keys

At minimum, set your API key for the chosen provider:

# OpenAI (default)
tabber config set openai_api_key sk-...

# Anthropic
tabber config set llm_provider anthropic
tabber config set anthropic_api_key sk-ant-...

Usage

tabber lookup "Elon Musk"
tabber "Elon Musk"        # shorthand

Options

The output panel shows the inferred location, confidence (green ≥70%, yellow ≥40%, red <40%), reasoning, and sources. Results marked (cached) were served from the local database without making any LLM or network calls.

Caching

Every completed lookup is stored in a local SQLite database (~/.tabber/results.db). On subsequent lookups for the same name, the cached result is returned immediately if it was created within the last cache_ttl_hours hours (default: 24).

~/.tabber/
├── config.json     # configuration
└── results.db      # SQLite result cache

Cache behaviour

• CLI — cache is checked automatically before running the pipeline. Use --no-cache to force a fresh run (the new result is still stored).
• API — same logic: set "no_cache": true in the request body to bypass the cache.
• TTL — configure how long results stay valid: tabber config set cache_ttl_hours 48
• Invalidation — delete cached results for a name via the API (DELETE /results/{name}) or by removing the database file.

REST API Server

Start the server with:

tabber server

Server options

The server uses FastAPI and requires the [server] extra (pip install -e ".[server]"). Interactive API docs are available at http://localhost:8000/docs once the server is running.

Endpoints

Request / response examples

POST /lookup

// request
{ "name": "Taylor Swift" }

// response
{
  "query_name": "Taylor Swift",
  "canon_name": "Taylor Swift",
  "cached": false,
  "timestamp": "2026-03-22T14:00:00+00:00",
  "result": {
    "location": "Nashville, Tennessee, USA",
    "confidence": 0.82,
    "reasoning": "Multiple recent news sources confirm a studio session in Nashville.",
    "sources": ["news", "wikipedia"]
  }
}

GET /results?limit=5

[
  {
    "id": 3,
    "query_name": "Taylor Swift",
    "canon_name": "Taylor Swift",
    "location": "Nashville, Tennessee, USA",
    "confidence": 0.82,
    "reasoning": "...",
    "sources": ["news", "wikipedia"],
    "timestamp": "2026-03-22T14:00:00+00:00"
  }
]

DELETE /results/Taylor%20Swift

{ "deleted": 1, "name": "Taylor Swift" }

Error responses

Data Sources (Gatherers)

Gatherers that lack the required credentials are skipped automatically. The tool works with only the unauthenticated gatherers (News, Wikipedia, Events), but more sources improve accuracy.

LLM

Tabber supports two providers, configured via llm_provider:

Both providers are accessed via the OpenAI-compatible SDK.

All LLM calls use Pydantic structured outputs via the response_format parameter so responses are parsed and validated automatically:

• OpenAI — uses client.beta.chat.completions.parse(response_format=Model), which returns a validated Pydantic instance directly.
• Anthropic — passes the model's JSON schema via response_format={"type": "json_schema", ...} and validates the response with Model.model_validate_json().

Data Models (models.py)

Testing

The test suite lives in tests/ and uses pytest. All LLM and external HTTP calls are mocked so tests run offline without API keys.

# Install dev dependencies (pytest + httpx for API tests)
pip install -e ".[dev]"

# Run the full suite
pytest

# Run with verbose output
pytest -v

# Run a specific file
pytest tests/test_llm.py

Test coverage by file