Metadata-Version: 2.4
Name: lightreel
Version: 0.1.0
Summary: Tiny client + CLI for the Lightreel API (api.lightreel.ai). Ask Lightreel questions from your code or terminal.
License: MIT
Project-URL: Homepage, https://lightreel.ai
Keywords: lightreel,tiktok,instagram,ugc,creators,api,cli
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# lightreel

The API to answer any social media questions.

Tiny client + CLI for the [Lightreel](https://lightreel.ai) API. Ask Lightreel questions from your code or terminal.

Ask about TikTok and Instagram, find trends, creators, and more.

Zero dependencies (standard library only). Works as an import **and** as a CLI.

## Install

```bash
pip install lightreel
# or run the CLI without installing:
pipx run lightreel "find me the top fitness hooks this week"
```

## Use it in code

```python
from lightreel import Lightreel

client = Lightreel(api_key="lr_live_xxx")  # or set LIGHTREEL_API_KEY

# Plain question
res = client.chat(question="find me the top fitness hooks this week")
print(res["answer"])           # prose string
print(res["conversationId"])

# Continue the conversation
client.chat(question="give me 5 more", conversation_id=res["conversationId"])

# Structured output (max 5 fields) — "answer" comes back as a dict
out = client.chat(
    question="find me the top fitness hooks this week",
    response_fields={
        "hooks":   {"type": "array",  "description": "the hook lines"},
        "summary": {"type": "string", "description": "one-paragraph recap"},
    },
)
print(out["answer"]["hooks"])

# History
client.list_chats()
client.get_chat(res["conversationId"])
```

Requests default to a **20-minute timeout** because `/v1/chat` runs the agent live and can take a few minutes. Override with `Lightreel(timeout=seconds)`.

## Use it in the terminal

```bash
export LIGHTREEL_API_KEY=lr_live_xxx

lightreel "find me the top fitness hooks this week"
lightreel "give me 5 more" -c <conversationId>
lightreel "top fitness hooks" -f "hooks:array:the hook lines" -f "summary:string:one-paragraph recap"
lightreel list
lightreel get <conversationId>
```

| Flag | Meaning |
|---|---|
| `-k, --key` | API key (or `LIGHTREEL_API_KEY`) |
| `-c, --conversation` | continue an existing conversation |
| `-f, --field name:type:description` | request structured output (repeatable, max 5; type = `string`\|`array`) |
| `--json` | print the raw JSON response |

## Errors

Non-2xx responses raise `LightreelError` with `.status` and `.type`.
