Metadata-Version: 2.4
Name: declassdb
Version: 0.3.1
Summary: Python client for DeclassDB.com — search declassified CIA, FBI, NSA, NARA, State Dept, and DoD documents.
Project-URL: Homepage, https://declassdb.com
Project-URL: Documentation, https://declassdb.com/docs/api
Project-URL: Repository, https://github.com/Subzero121800/declassdb-python
Project-URL: Issues, https://github.com/Subzero121800/declassdb-python/issues
Project-URL: Changelog, https://github.com/Subzero121800/declassdb-python/blob/main/CHANGELOG.md
Author-email: "Joseph C. McGinty Jr." <joseph@resilientmindai.com>
License-Expression: MIT
License-File: LICENSE
Keywords: api,cia,declassified,documents,fbi,foia,government,intelligence,nara,nsa,osint,research
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.8
Requires-Dist: prompt-toolkit>=3.0.0
Provides-Extra: all
Requires-Dist: httpx>=0.24.0; extra == 'all'
Requires-Dist: prompt-toolkit>=3.0.0; extra == 'all'
Provides-Extra: cli
Requires-Dist: prompt-toolkit>=3.0.0; extra == 'cli'
Provides-Extra: httpx
Requires-Dist: httpx>=0.24.0; extra == 'httpx'
Description-Content-Type: text/markdown

# declassdb

Python client for [DeclassDB.com](https://declassdb.com) — search declassified government documents from CIA, FBI, NSA, NARA, State Department, DoD, and NSArchive.

## Install

```bash
pip install declassdb
```

For faster HTTP (optional):

```bash
pip install declassdb[httpx]
```

## Quick Start

```python
from declassdb import DeclassDB

db = DeclassDB(api_key="dk_live_...")

# Search across all sources
results = db.search("MKUltra")
for doc in results:
    print(doc.title, doc.date)
```

## API Key

Get your API key at [declassdb.com/account#api-access](https://declassdb.com/account#api-access).

You can pass it directly or set it as an environment variable:

```bash
export DECLASSDB_API_KEY=dk_live_...
```

```python
# Reads from DECLASSDB_API_KEY automatically
db = DeclassDB()
```

## Usage

### Search All Sources

```python
results = db.search("Star Gate", limit=10)
print(f"Found {results.total} documents")

for doc in results:
    print(f"[{doc.source}] {doc.title} ({doc.date})")
    print(f"  {doc.url}")
```

### Search Specific Sources

```python
# Single source
results = db.search("uranium", source="cia")

# Multiple sources
results = db.search("uranium", source="cia,nsa")

# Convenience methods
results = db.search_cia("OXCART A-12")
results = db.search_fbi("Hoover")
results = db.search_nsa("SIGINT")
results = db.search_nara("Manhattan Project")
results = db.search_state("Cuba missile crisis")
```

### Pagination

```python
# Page through results
page1 = db.search("Vietnam", limit=20, page=1)
page2 = db.search("Vietnam", limit=20, page=2)
```

### Get Counts Only

```python
counts = db.counts("nuclear testing")
print(counts)
# {'cia': 342, 'fbi': 12, 'state': 89, 'nsa': 7, 'nara': 4521, ...}
```

### Export to PDF

```python
# Save search results as PDF
db.export_pdf("OXCART", source="cia", limit=10, output_path="oxcart_results.pdf")

# Or get raw bytes
pdf_bytes = db.export_pdf("OXCART", source="cia")
```

### Check API Key Status

```python
info = db.key_info()
print(f"Tier: {info.tier}")
print(f"Monthly quota: {info.quota}")
```

### Work with Results

```python
results = db.search("Bay of Pigs", source="cia", limit=5)

# Iterate
for doc in results:
    print(doc.title)

# Index
first = results[0]

# Length
print(f"{len(results)} results returned")

# Raw dict
raw = results.to_dict()
```

### Document Properties

Each `Document` object has:

```python
doc.doc_id      # Unique document identifier
doc.title       # Document title
doc.url         # URL to view the document
doc.pdf_url     # Direct PDF URL (when available)
doc.date        # Document date (YYYY-MM-DD)
doc.collection  # Collection name
doc.snippet     # Text snippet / description
doc.pages       # Page count (when available)
doc.source      # Source agency (cia, fbi, etc.)
```

## Command-Line Interface

The package installs a `declassdb` command (also `python -m declassdb`). It
works both as a scriptable one-shot tool and as an interactive research REPL.

For the richest REPL (tab completion + persistent history), install the extra:

```bash
pip install declassdb[cli]     # adds prompt_toolkit
pip install declassdb[all]     # httpx + prompt_toolkit
```

### One-shot commands

```bash
declassdb search "MKUltra" --source cia --limit 5
declassdb search "MKUltra" --json | jq '.results[].title'
declassdb info
declassdb export "OXCART" --format pdf -o results.pdf
declassdb export "OXCART" --format bibtex -o oxcart.bib
declassdb login                # save your API key to ~/.declassdb/config.toml
declassdb upgrade              # Paddle checkout to upgrade your tier
```

Output is colorized for a terminal and automatically stripped of ANSI codes
when piped. `NO_COLOR` is honored.

### Interactive REPL

Run `declassdb` with no arguments to drop into the session:

```
declassdb> cia Star Gate
declassdb> next
declassdb> open 1
declassdb> cite 2 --format ris
declassdb> save 3 cold-war
declassdb> foia 1
declassdb> counts "uranium enrichment"
declassdb> collections
```

After a search you reference results by number — no re-querying or
copy-pasting IDs. Collections persist to `~/.declassdb/collections.json`
across sessions.

**REPL commands**

| Group | Commands |
|-------|----------|
| Search & browse | `search`, `cia`/`fbi`/`nsa`/`nara`/`state`, `next`, `prev`, `counts` |
| Document actions | `open`, `analyze`, `text`, `entities`, `foia`, `cite` |
| Collections | `save`, `collections`, `collection`, `export-collection` |
| Session | `info`, `history`, `upgrade`, `config`, `help`, `quit` |

`cite` (BibTeX/RIS), `foia` (request letter), and collections are built
fully client-side from document metadata. `analyze`, `entities`, and full
OCR `text` are powered by the DeclassDB web app and are not exposed through
the public API yet — those commands say so and link to the document.

### Config

Stored at `~/.declassdb/config.toml`:

```toml
[auth]
api_key = "dk_live_..."

[defaults]
limit = 20
source = ""
format = "text"

[display]
color = true
page_size = 20
```

Change values from the REPL: `config set defaults.limit 50`.

## Error Handling

```python
from declassdb import DeclassDB, AuthenticationError, RateLimitError, DeclassDBError

db = DeclassDB(api_key="dk_live_...")

try:
    results = db.search("test query")
except AuthenticationError:
    print("Bad API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except DeclassDBError as e:
    print(f"API error ({e.status_code}): {e}")
```

## Tiers

| Feature | Pro | Researcher |
|---------|-----|------------|
| API calls | 1,000/month | 10,000/month + webhooks |
| Sources | CIA, FBI, State, NSA, NARA | All + full-text CREST PDF search |
| Export | JSON, text, PDF | + BibTeX, RIS citation export |
| Price | $50/yr (founder rate) | $100/yr (founder rate) |

Get your key: [declassdb.com](https://declassdb.com)

## Requirements

- Python 3.8+
- No required dependencies (uses stdlib `urllib`)
- Optional: `httpx` for faster HTTP

## License

MIT

## Links

- **Website:** [declassdb.com](https://declassdb.com)
- **API Docs:** [declassdb.com/docs/api](https://declassdb.com/docs/api)
- **Published by:** ResilientMind AI LLC (SDVOSB)
