API Reference – VeritaScribe

# API Reference

# 1 API Reference

This reference covers VeritaScribe’s programmatic interfaces, data models, and internal APIs for developers and advanced users.

## 1.1 Command Line Interface

### 1.1.1 Core Commands

#### 1.1.1.1 `analyze`

Perform comprehensive thesis analysis.

    uv run python -m veritascribe analyze [OPTIONS] PDF_PATH

Arguments: - `PDF_PATH` (required): Path to the PDF thesis file

Options: - `--output, -o TEXT`: Output directory for reports - `--citation-style, -c TEXT`: Expected citation style (APA, MLA, Chicago, IEEE, Harvard) - `--quick, -q`: Perform quick analysis (first 10 blocks only) - `--no-viz`: Skip generating visualization charts - `--annotate`: Generate an annotated PDF with highlighted errors - `--verbose, -v`: Enable verbose logging

Exit Codes: - `0`: Success - `1`: Error (file not found, analysis failed, etc.)

#### 1.1.1.2 `quick`

Fast analysis of document subset.

    uv run python -m veritascribe quick [OPTIONS] PDF_PATH

Arguments: - `PDF_PATH` (required): Path to the PDF thesis file

Options: - `--blocks, -b INTEGER`: Number of text blocks to analyze (default: 5)

#### 1.1.1.3 `demo`

Create and analyze sample document.

    uv run python -m veritascribe demo

No arguments or options. Creates `demo_thesis.pdf` in current directory.

#### 1.1.1.4 `config`

Display current configuration.

    uv run python -m veritascribe config

Outputs configuration table and API key status.

#### 1.1.1.5 `providers`

List available LLM providers and models.

    uv run python -m veritascribe providers

#### 1.1.1.6 `optimize-prompts`

Fine-tune analysis prompts using a few-shot learning dataset.

    uv run python -m veritascribe optimize-prompts

#### 1.1.1.7 `test`

Run system diagnostics.

    uv run python -m veritascribe test

Tests configuration loading, PDF processing, and LLM connectivity.

## 1.2 Python API

### 1.2.1 Configuration Management

#### 1.2.1.1 `veritascribe.config.VeritaScribeSettings`

Main configuration class using Pydantic Settings.

    from veritascribe.config import VeritaScribeSettings

    settings = VeritaScribeSettings(
        openai_api_key="your-key-here",
        default_model="gpt-4",
        max_tokens=2000,
        temperature=0.1
    )

Key Fields:

Field | Type | Default | Description
--- | --- | --- | ---
`llm_provider` | `str` | `"openai"` | LLM provider (openai, openrouter, anthropic, custom)
`openai_api_key` | `Optional[str]` | `None` | OpenAI API key
`openrouter_api_key` | `Optional[str]` | `None` | OpenRouter API key
`anthropic_api_key` | `Optional[str]` | `None` | Anthropic API key
`default_model` | `str` | `"gpt-4"` | LLM model name
`max_tokens` | `int` | `2000` | Max tokens per request
`temperature` | `float` | `0.1` | LLM temperature

### 1.2.2 Data Models

All data models use Pydantic for validation and serialization.

#### 1.2.2.1 `veritascribe.data_models.ThesisAnalysisReport`

Complete analysis report containing all results.

Key Fields: - `document_name: str` - `analysis_timestamp: datetime` - `total_pages: int` - `total_words: int` - `total_text_blocks: int` - `analysis_results: List[AnalysisResult]` - `total_processing_time_seconds: float` - `token_usage: Optional[Dict[str, int]]` - `estimated_cost: Optional[float]`

This API reference covers the main interfaces. For implementation details, see the Architecture Guide.

##### Source Code

    ---
    title: "API Reference"
    ---

    # API Reference

    This reference covers VeritaScribe's programmatic interfaces, data models, and internal APIs for developers and advanced users.

    ## Command Line Interface

    ### Core Commands

    #### `analyze`

    Perform comprehensive thesis analysis.

    ```bash
    uv run python -m veritascribe analyze [OPTIONS] PDF_PATH
    ```

    **Arguments:**
    - `PDF_PATH` (required): Path to the PDF thesis file

    **Options:**
    - `--output, -o TEXT`: Output directory for reports
    - `--citation-style, -c TEXT`: Expected citation style (APA, MLA, Chicago, IEEE, Harvard)
    - `--quick, -q`: Perform quick analysis (first 10 blocks only)
    - `--no-viz`: Skip generating visualization charts
    - `--annotate`: Generate an annotated PDF with highlighted errors
    - `--verbose, -v`: Enable verbose logging

    **Exit Codes:**
    - `0`: Success
    - `1`: Error (file not found, analysis failed, etc.)

    #### `quick`

    Fast analysis of document subset.

    ```bash
    uv run python -m veritascribe quick [OPTIONS] PDF_PATH
    ```

    **Arguments:**
    - `PDF_PATH` (required): Path to the PDF thesis file

    **Options:**
    - `--blocks, -b INTEGER`: Number of text blocks to analyze (default: 5)

    #### `demo`

    Create and analyze sample document.

    ```bash
    uv run python -m veritascribe demo
    ```

    No arguments or options. Creates `demo_thesis.pdf` in current directory.

    #### `config`

    Display current configuration.

    ```bash
    uv run python -m veritascribe config
    ```

    Outputs configuration table and API key status.

    #### `providers`

    List available LLM providers and models.

    ```bash
    uv run python -m veritascribe providers
    ```

    #### `optimize-prompts`

    Fine-tune analysis prompts using a few-shot learning dataset.

    ```bash
    uv run python -m veritascribe optimize-prompts
    ```

    #### `test`

    Run system diagnostics.

    ```bash
    uv run python -m veritascribe test
    ```

    Tests configuration loading, PDF processing, and LLM connectivity.

    ## Python API

    ### Configuration Management

    #### `veritascribe.config.VeritaScribeSettings`

    Main configuration class using Pydantic Settings.

    ```python
    from veritascribe.config import VeritaScribeSettings

    settings = VeritaScribeSettings(
        openai_api_key="your-key-here",
        default_model="gpt-4",
        max_tokens=2000,
        temperature=0.1
    )
    ```

    **Key Fields:**

    | Field | Type | Default | Description |
    |-------|------|---------|-------------|
    | `llm_provider` | `str` | `"openai"` | LLM provider (openai, openrouter, anthropic, custom) |
    | `openai_api_key` | `Optional[str]` | `None` | OpenAI API key |
    | `openrouter_api_key` | `Optional[str]` | `None` | OpenRouter API key |
    | `anthropic_api_key` | `Optional[str]` | `None` | Anthropic API key |
    | `default_model` | `str` | `"gpt-4"` | LLM model name |
    | `max_tokens` | `int` | `2000` | Max tokens per request |
    | `temperature` | `float` | `0.1` | LLM temperature |

    ### Data Models

    All data models use Pydantic for validation and serialization.

    #### `veritascribe.data_models.ThesisAnalysisReport`

    Complete analysis report containing all results.

    **Key Fields:**
    - `document_name: str`
    - `analysis_timestamp: datetime`
    - `total_pages: int`
    - `total_words: int`
    - `total_text_blocks: int`
    - `analysis_results: List[AnalysisResult]`
    - `total_processing_time_seconds: float`
    - `token_usage: Optional[Dict[str, int]]`
    - `estimated_cost: Optional[float]`

    ---

    *This API reference covers the main interfaces. For implementation details, see the [Architecture Guide](architecture.qmd).*