Metadata-Version: 2.4
Name: llmtraceviewer
Version: 0.2.0
Summary: A tool to view LLM call traces from JSONL log files.
Author-email: Your Name <your.email@example.com>
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi
Requires-Dist: uvicorn
Dynamic: license-file

# llmtraceviewer

A Python package and CLI tool to view LLM call traces from JSONL log files. It starts a local HTTP server for interactive log exploration.

## Usage

```sh
llmtraceviewer <log_filename or directory>
```

- Starts a FastAPI server
- Provides an API endpoint for log data
- You can specify a single log file or a directory containing log files

## Log File Format

The tool expects a JSONL (JSON Lines) log file where each relevant line contains the string `LLMTRACE:` followed by a JSON object. Only lines with `LLMTRACE:` are parsed.

**Each JSON object should have the following structure:**

```
{
  "type": "chat.completion",
  "messages": [
    { "role": "user", "content": "Hello, world!" },
    { "role": "assistant", "content": "Hi!" }
  ],
  "response_format": "text",
  "reasoning_effort": "low",
  "temperature": 0.7,
  "elapsed_time": 1.23,
  "response": "Hi!",
  "finish_reason": "stop",
  "completion_tokens": 10,
  "prompt_tokens": 8,
  "reasoning_tokens": 2,           // optional
  "start_time": 1713268800.0       // optional (Unix timestamp)
}
```

**Example log file:**

```
2024-04-16T12:00:00Z INFO LLMTRACE: {"type": "chat.completion", "messages": [{"role": "user", "content": "Hello, world!"}], "response_format": "text", "reasoning_effort": "low", "temperature": 0.7, "elapsed_time": 1.23, "response": "Hi!", "finish_reason": "stop", "completion_tokens": 10, "prompt_tokens": 8}
2024-04-16T12:00:01Z INFO LLMTRACE: {"type": "chat.completion", "messages": [{"role": "user", "content": "How are you?"}], "response_format": "text", "reasoning_effort": "medium", "temperature": 0.7, "elapsed_time": 1.45, "response": "I'm an AI, so I don't have feelings, but thanks for asking!", "finish_reason": "stop", "completion_tokens": 15, "prompt_tokens": 10, "reasoning_tokens": 3, "start_time": 1713268801.0}
```

- Each line can have arbitrary text before `LLMTRACE:`
- The JSON object after `LLMTRACE:` should contain the LLM call trace fields as shown above

## Requirements
- Python 3.8+
- Node.js (for development)

## Development
- Backend: FastAPI
- Frontend: Next.js (served as static files)
