### Install TickVault Package

Source: https://github.com/keyhankamyar/tickvault/blob/main/README.md

Install the tick-vault package using pip. Alternatively, clone the repository and install from source for development.

```bash
pip install tick-vault
```

```bash
git clone https://github.com/keyhankamyar/TickVault.git
cd TickVault
```

```bash
python -m venv .venv
source .venv/bin/activate

# Or use conda
conda create --prefix .conda python -y
conda activate ./.conda
```

```bash
# Install dependencies
pip install -r requirements.txt

# Or install in development mode
pip install -e .
```

--------------------------------

### Install TickVault

Source: https://context7.com/keyhankamyar/tickvault/llms.txt

Install the library using pip.

```bash
pip install tick-vault
```

--------------------------------

### Read Tick Data for a Specific Date Range

Source: https://github.com/keyhankamyar/tickvault/blob/main/README.md

Use `read_tick_data` to fetch tick data for a given symbol within a specified start and end date. Ensure `datetime` is imported.

```python
from datetime import datetime
df = read_tick_data(
    symbol='EURUSD',
    start=datetime(2024, 1, 1),
    end=datetime(2024, 2, 1)
)
```

--------------------------------

### Read Tick Data with Non-Strict Gap Handling

Source: https://github.com/keyhankamyar/tickvault/blob/main/README.md

Read tick data in non-strict mode to automatically adjust to the available data range. This mode clips the data to the available range, even if it's before the specified start or after the specified end.

```python
# Non-strict mode: clips to available data range
df = read_tick_data(
    symbol='XAUUSD',
    start=datetime(2020, 1, 1),  # May be before first available
    end=datetime(2030, 1, 1),    # May be after last available
    strict=False  # Automatically adjusts to available range
)
```

--------------------------------

### Configure TickVault Using Environment Variables

Source: https://github.com/keyhankamyar/tickvault/blob/main/README.md

Set TickVault configuration options by defining environment variables such as `TICK_VAULT_BASE_DIRECTORY` and `TICK_VAULT_WORKER_PER_PROXY`. Ensure the `os` module is imported.

```python
import os

os.environ['TICK_VAULT_BASE_DIRECTORY'] = './my_tick_data'
os.environ['TICK_VAULT_WORKER_PER_PROXY'] = '15'
```

--------------------------------

### Configure TickVault Download Settings

Source: https://github.com/keyhankamyar/tickvault/blob/main/README.md

Optional: Configure base directory, worker counts, and retry settings for data downloads. These settings affect subsequent download operations.

```python
from tick_vault import download_range, reload_config

# Optional: configure base directory, worker counts, etc.
reload_config(
    base_directory="./tick_vault_data",
    worker_per_proxy=10,                 # default 10
    fetch_max_retry_attempts=3,          # default 3
    fetch_base_retry_delay=1.0,          # default 1.0s
)
```

--------------------------------

### Configure TickVault settings

Source: https://context7.com/keyhankamyar/tickvault/llms.txt

Configure the library using direct function calls or environment variables. Environment variables must be set before calling reload_config() without arguments.

```python
reload_config(
    base_directory='./my_tick_data',
    worker_per_proxy=15,
    fetch_max_retry_attempts=5,
    fetch_base_retry_delay=2.0,
    metadata_update_batch_size=200,
    console_log_level='DEBUG'
)
```

```python
import os
os.environ['TICK_VAULT_BASE_DIRECTORY'] = '/data/ticks'
os.environ['TICK_VAULT_WORKER_PER_PROXY'] = '20'
os.environ['TICK_VAULT_FETCH_MAX_RETRY_ATTEMPTS'] = '5'
os.environ['TICK_VAULT_BASE_LOG_LEVEL'] = 'INFO'
reload_config()  # Picks up environment variables
```

--------------------------------

### Configure TickVault via Environment Variables

Source: https://github.com/keyhankamyar/tickvault/blob/main/README.md

Set TickVault configuration options by exporting environment variables. This is useful for scripting and automated deployments.

```bash
export TICK_VAULT_BASE_DIRECTORY=/data/ticks
export TICK_VAULT_WORKER_PER_PROXY=15
export TICK_VAULT_FETCH_MAX_RETRY_ATTEMPTS=5
```

--------------------------------

### Configure TickVault via .env File

Source: https://github.com/keyhankamyar/tickvault/blob/main/README.md

Manage TickVault settings by defining them in a .env file. This approach is convenient for local development and project-specific configurations.

```env
# .env
TICK_VAULT_BASE_DIRECTORY=/data/ticks
TICK_VAULT_WORKER_PER_PROXY=15
TICK_VAULT_FETCH_MAX_RETRY_ATTEMPTS=5
TICK_VAULT_BASE_LOG_LEVEL=INFO
```

--------------------------------

### Interact with TickVault Metadata Database

Source: https://github.com/keyhankamyar/tickvault/blob/main/README.md

Use the MetadataDB class to query and manage tick data information. This includes finding the first and last available data chunks, identifying pending downloads, and checking for data gaps.

```python
from tick_vault.metadata import MetadataDB

with MetadataDB() as db:
    # Find what's available
    first = db.first_chunk('XAUUSD')
    last = db.last_chunk('XAUUSD')
    print(f"Data range: {first.time} to {last.time}")
    
    # Find chunks that haven't been downloaded yet
    pending = db.find_not_attempted_chunks(
        symbol='EURUSD',
        start=datetime(2024, 1, 1),
        end=datetime(2024, 2, 1)
    )
    print(f"Pending downloads: {len(pending)}")
    
    # Verify data continuity
    try:
        db.check_for_gaps(
            symbol='XAUUSD',
            start=datetime(2024, 1, 1),
            end=datetime(2024, 2, 1)
        )
        print("✓ No gaps found")
    except RuntimeError as e:
        print(f"✗ Gaps detected: {e}")
```

--------------------------------

### Reload Configuration

Source: https://context7.com/keyhankamyar/tickvault/llms.txt

Update global settings using reload_config. Settings are validated via Pydantic.

```python
from tick_vault import reload_config
```

--------------------------------

### Download Incremental Updates

Source: https://github.com/keyhankamyar/tickvault/blob/main/README.md

Fetch recent data to update your existing dataset. Specify the symbol and a date range covering the period you need to update, such as the last week.

```python
from datetime import datetime, UTC

# Download only the last week
await download_range(
    symbol='EURUSD',
    start=datetime(2024, 3, 25),
    end=datetime.now(tz=UTC)
)
```

--------------------------------

### Fetch Data with Retry Logic

Source: https://context7.com/keyhankamyar/tickvault/llms.txt

Fetches data from a URL with automatic retry for transient errors like rate limiting and network issues. Fatal errors are raised immediately. Requires an httpx.AsyncClient.

```python
import asyncio
from httpx import AsyncClient
from tick_vault.fetcher import fetch_with_retry, ForbiddenError

async def main():
    async with AsyncClient(timeout=30.0) as client:
        url = "https://datafeed.dukascopy.com/datafeed/XAUUSD/2024/02/01/12h_ticks.bi5"

        try:
            # Fetch with automatic retry on transient errors
            data = await fetch_with_retry(client, url)

            if data:
                print(f"Downloaded {len(data)} bytes")
                # Output: Downloaded 45678 bytes
            else:
                print("No data available (404)")
                # Output: No data available (404)

        except ForbiddenError as e:
            # Access denied - possible IP ban
            print(f"Access forbidden: {e}")

        except RuntimeError as e:
            # Max retries exceeded or unexpected error
            print(f"Download failed: {e}")

asyncio.run(main())
```

--------------------------------

### Manage metadata with MetadataDB

Source: https://context7.com/keyhankamyar/tickvault/llms.txt

Use MetadataDB to track download status, identify gaps, and query available data chunks. The class acts as a context manager for connection handling.

```python
from datetime import datetime
from tick_vault.metadata import MetadataDB

# Use as context manager for automatic connection handling
with MetadataDB() as db:
    # Find the data range available for a symbol
    first = db.first_chunk('XAUUSD')
    last = db.last_chunk('XAUUSD')
    if first and last:
        print(f"Data range: {first.time} to {last.time}")
    # Output: Data range: 2024-01-01 00:00:00+00:00 to 2024-03-15 23:00:00+00:00

    # Find chunks that haven't been downloaded yet (for resuming)
    pending = db.find_not_attempted_chunks(
        symbol='EURUSD',
        start=datetime(2024, 1, 1),
        end=datetime(2024, 2, 1)
    )
    print(f"Pending downloads: {len(pending)} chunks")
    # Output: Pending downloads: 48 chunks

    # Verify data continuity before reading
    try:
        db.check_for_gaps(
            symbol='XAUUSD',
            start=datetime(2024, 1, 1),
            end=datetime(2024, 2, 1)
        )
        print("No gaps found - data is complete")
    except RuntimeError as e:
        print(f"Gaps detected: {e}")
    # Output: No gaps found - data is complete

    # Get all available chunks in a time range
    chunks = db.get_available_chunks(
        symbol='XAUUSD',
        start=datetime(2024, 1, 1),
        end=datetime(2024, 1, 2)
    )
    print(f"Available chunks: {len(chunks)}")
    # Output: Available chunks: 24
```

--------------------------------

### PIPET_SIZE_REGISTRY

Source: https://context7.com/keyhankamyar/tickvault/llms.txt

Registry of price scaling factors (pipet sizes) for supported trading symbols, used to convert raw integer prices to floating-point values.

```APIDOC
## PIPET_SIZE_REGISTRY

### Description
A dictionary mapping trading symbols to their respective price scaling factors (pipet sizes). This is used to normalize raw integer tick data into correct floating-point price representations.

### Data Structure
- **Key** (str) - The trading symbol (e.g., 'XAUUSD').
- **Value** (float) - The scaling factor (e.g., 0.001).
```

--------------------------------

### Access PIPET_SIZE_REGISTRY

Source: https://context7.com/keyhankamyar/tickvault/llms.txt

Accesses the PIPET_SIZE_REGISTRY to view or check registered price scaling factors for trading symbols. For custom symbols, provide pipet_scale manually.

```python
from tick_vault.constants import PIPET_SIZE_REGISTRY

# View all registered symbols and their pipet scales
print(PIPET_SIZE_REGISTRY)
# Output: {
#     'EURUSD': 1e-05,   # Forex majors: 5 decimal places
#     'AUDUSD': 1e-05,
#     'GBPUSD': 1e-05,
#     'NZDUSD': 1e-05,
#     'USDCAD': 1e-05,
#     'USDCHF': 1e-05,
#     'USDJPY': 0.001,   # JPY pairs: 3 decimal places
#     'XAUUSD': 0.001,   # Gold: 3 decimal places
#     'XAGUSD': 0.001,   # Silver: 3 decimal places
#     'ETHUSD': 0.1,     # Crypto: 1 decimal place
#     'BTCUSD': 0.1,
# }

# Check if a symbol is registered
if 'XAUUSD' in PIPET_SIZE_REGISTRY:
    scale = PIPET_SIZE_REGISTRY['XAUUSD']
    print(f"XAUUSD pipet scale: {scale}")
    # Output: XAUUSD pipet scale: 0.001

# For custom symbols, provide pipet_scale manually to read_tick_data()
```

--------------------------------

### fetch_with_retry

Source: https://context7.com/keyhankamyar/tickvault/llms.txt

Fetches data from a URL with automatic retry logic for transient failures, including exponential backoff for rate limits and network errors.

```APIDOC
## fetch_with_retry

### Description
Fetches data from a URL with automatic retry logic for transient failures. Implements exponential backoff for rate limiting (429) and transient network errors (500, 502, 503, 504, timeouts). Fatal errors (401, 403, 451) are raised immediately.

### Parameters
#### Request Body
- **client** (AsyncClient) - Required - The httpx AsyncClient instance used for the request.
- **url** (str) - Required - The target URL to fetch data from.
```

--------------------------------

### download_range

Source: https://context7.com/keyhankamyar/tickvault/llms.txt

Downloads tick data for a specific symbol within a defined date range using concurrent workers and automatic resume capabilities.

```APIDOC
## download_range

### Description
Downloads tick data for a symbol within a date range using concurrent workers. The orchestrator manages the download pipeline, tracks progress via SQLite, and handles retries.

### Parameters
#### Request Body
- **symbol** (string) - Required - The financial symbol to download (e.g., 'XAUUSD').
- **start** (datetime) - Required - The start date of the range.
- **end** (datetime) - Required - The end date of the range.
- **proxies** (list) - Optional - A list of proxy URLs for concurrent downloads.

### Request Example
await download_range(symbol='XAUUSD', start=datetime(2024, 1, 1), end=datetime(2024, 2, 1))
```

--------------------------------

### Download Tick Data

Source: https://context7.com/keyhankamyar/tickvault/llms.txt

Use download_range to fetch tick data concurrently. Configure settings with reload_config before initiating downloads.

```python
import asyncio
from datetime import datetime, UTC
from tick_vault import download_range, reload_config

# Configure settings before downloading
reload_config(
    base_directory="./tick_vault_data",
    worker_per_proxy=10,
    fetch_max_retry_attempts=3,
    fetch_base_retry_delay=1.0,
)

async def main():
    # Download one month of gold (XAU/USD) tick data
    await download_range(
        symbol='XAUUSD',
        start=datetime(2024, 1, 1),
        end=datetime(2024, 2, 1)
    )
    # Output: Progress bar showing download status
    # Files saved to: ./tick_vault_data/downloads/XAUUSD/2024/00/01/00h_ticks.bi5, etc.

    # Download with multiple proxies for faster speeds
    await download_range(
        symbol='EURUSD',
        start=datetime(2024, 1, 1),
        end=datetime(2024, 3, 1),
        proxies=[
            'http://proxy1.example.com:8080',
            'http://proxy2.example.com:8080'
        ]
    )

    # Resume interrupted downloads - automatically skips already-downloaded chunks
    await download_range(
        symbol='XAUUSD',
        start=datetime(2020, 1, 1),
        end=datetime(2024, 1, 1)
    )
    # Re-running the same range only attempts hours not yet recorded in metadata.db

asyncio.run(main())
```

--------------------------------

### Read Tick Data with Strict Validation and Progress Bar

Source: https://github.com/keyhankamyar/tickvault/blob/main/README.md

Fetch tick data with `strict=True` to verify the requested range is fully present, raising an error on gaps. `show_progress=True` displays a tqdm progress bar during decoding.

```python
df = read_tick_data(
    symbol="XAUUSD",
    strict=True,         # verify requested range is fully present (raises on gaps)
    show_progress=True,  # tqdm while decoding hourly chunks
)

print(df.head())
print(f"Total ticks: {len(df)}")
print(f"Time range: {df['time'].min()} to {df['time'].max()}")
# columns: time, ask, bid, ask_volume, bid_volume
```

--------------------------------

### Manage tick data with TickChunk

Source: https://context7.com/keyhankamyar/tickvault/llms.txt

TickChunk handles URL generation, filesystem paths, and I/O operations for raw tick data files.

```python
from datetime import datetime, UTC
from tick_vault.chunk import TickChunk

# Create a chunk for a specific hour
chunk = TickChunk(
    symbol='XAUUSD',
    time=datetime(2024, 3, 2, 12, 0, 0, tzinfo=UTC)
)

# Get the Dukascopy datafeed URL
print(chunk.url)
# Output: https://datafeed.dukascopy.com/datafeed/XAUUSD/2024/02/02/12h_ticks.bi5
# Note: Month is 0-indexed (02 = March)

# Get the local filesystem path
print(chunk.path())
# Output: tick_vault_data/downloads/XAUUSD/2024/02/02/12h_ticks.bi5

# Save raw data to disk
raw_data = b'\x00\x01\x02...'  # Compressed .bi5 data
chunk.save(raw_data)
# Creates: tick_vault_data/downloads/XAUUSD/2024/02/02/12h_ticks.bi5

# Load data from disk
loaded_data = chunk.load()
print(f"Loaded {len(loaded_data)} bytes")
# Output: Loaded 45678 bytes
```

--------------------------------

### Resumable Download of Tick Data

Source: https://github.com/keyhankamyar/tickvault/blob/main/README.md

To resume an interrupted download, simply re-run the download command with the same parameters. TickVault will automatically detect and skip already downloaded data.

```python
# Simply run the same command again
await download_range(
    symbol='XAUUSD',
    start=datetime(2020, 1, 1),  # Large historical range
    end=datetime(2024, 1, 1)
)

# TickVault will skip already-downloaded chunks and resume where it left off
```

--------------------------------

### Reload Configuration Programmatically

Source: https://github.com/keyhankamyar/tickvault/blob/main/README.md

Customize TickVault settings like `base_directory`, `worker_per_proxy`, and `fetch_max_retry_attempts` by calling `reload_config` with desired parameters. Ensure `reload_config` is imported.

```python
from tick_vault import reload_config

# Customize settings programmatically
reload_config(
    base_directory='./my_tick_data',
    worker_per_proxy=15,
    fetch_max_retry_attempts=5
)
```

--------------------------------

### reload_config

Source: https://context7.com/keyhankamyar/tickvault/llms.txt

Updates the global configuration settings for the TickVault library.

```APIDOC
## reload_config

### Description
Reloads the global configuration with new settings. Settings are validated using Pydantic models.

### Parameters
#### Request Body
- **base_directory** (string) - Optional - Path to store downloaded data.
- **worker_per_proxy** (int) - Optional - Number of concurrent workers per proxy.
- **fetch_max_retry_attempts** (int) - Optional - Maximum number of retries for failed downloads.
- **fetch_base_retry_delay** (float) - Optional - Base delay in seconds for retry logic.
```

--------------------------------

### Read Tick Data with Custom Pipet Scale

Source: https://github.com/keyhankamyar/tickvault/blob/main/README.md

Use this to read tick data for custom symbols by providing a specific pipet scale factor. Ensure the symbol and date range are correctly specified.

```python
df = read_tick_data(
    symbol='CUSTOM_PAIR',
    start=datetime(2024, 1, 1),
    end=datetime(2024, 2, 1),
    pipet_scale=0.01  # Custom scaling factor
)
```

--------------------------------

### Download Historical Tick Data

Source: https://github.com/keyhankamyar/tickvault/blob/main/README.md

Download tick data for a specified symbol and date range. The download is resumable and can utilize multiple proxies for faster speeds.

```python
from datetime import datetime
from tick_vault import download_range, reload_config

# Optional: configure base directory, worker counts, etc.
reload_config(
    base_directory="./tick_vault_data",
    worker_per_proxy=10,                 # default 10
    fetch_max_retry_attempts=3,          # default 3
    fetch_base_retry_delay=1.0,          # default 1.0s
)

# Download one month of gold (XAU/USD) tick data
await download_range(
    symbol='XAUUSD',
    start=datetime(2024, 1, 1),
    end=datetime(2024, 2, 1)
)

# Download with multiple proxies for faster speeds
await download_range(
    symbol='EURUSD',
    start=datetime(2024, 1, 1),
    end=datetime.now(),
    proxies=[
        'http://proxy1.example.com:8080',
        'http://proxy2.example.com:8080'
    ]
)
```

--------------------------------

### Read Tick Data with Strict Gap Detection

Source: https://github.com/keyhankamyar/tickvault/blob/main/README.md

Read tick data in strict mode to ensure data completeness. If any gaps are detected, an error will be raised. This is the default behavior.

```python
# Strict mode (default): raises error if data is incomplete
df = read_tick_data(
    symbol='XAUUSD',
    start=datetime(2024, 1, 1),
    end=datetime(2024, 2, 1),
    strict=True  # Ensures no gaps in data
)
```

--------------------------------

### Decode tick data chunks

Source: https://context7.com/keyhankamyar/tickvault/llms.txt

Convert compressed LZMA tick data into structured NumPy arrays using decode_chunk.

```python
from datetime import datetime, UTC
from tick_vault.chunk import TickChunk
from tick_vault.decoder import decode_chunk

# Create and load a chunk
chunk = TickChunk(symbol='XAUUSD', time=datetime(2024, 3, 1, 12, tzinfo=UTC))

# Decode using registered pipet scale
array = decode_chunk(chunk)
print(array.dtype)
# Output: [('time', '<M8[ms]'), ('ask', '<f8'), ('bid', '<f8'),
#          ('ask_volume', '<i8'), ('bid_volume', '<i8')]

print(array[:3])
# Output: [(numpy.datetime64('2024-03-01T12:00:00.123'), 2062.345, 2062.123, 1500000, 2000000),
```

--------------------------------

### Read and Analyze Tick Data

Source: https://github.com/keyhankamyar/tickvault/blob/main/README.md

Read tick data for a given symbol. The data is decoded on-demand and returned as a pandas DataFrame, ready for analysis.

```python
from tick_vault import read_tick_data

# Read all available data for a symbol
df = read_tick_data(symbol='XAUUSD')
```

--------------------------------

### read_tick_data

Source: https://context7.com/keyhankamyar/tickvault/llms.txt

Reads and decodes compressed tick data from local storage into a pandas DataFrame.

```APIDOC
## read_tick_data

### Description
Reads and decodes tick data for a symbol within a time range, returning a pandas DataFrame. It verifies data continuity and handles decompression.

### Parameters
#### Request Body
- **symbol** (string) - Required - The symbol to read.
- **start** (datetime) - Optional - Start date for the data range.
- **end** (datetime) - Optional - End date for the data range.
- **strict** (boolean) - Optional - If True, raises an error if data gaps are detected.
- **show_progress** (boolean) - Optional - If True, displays a progress bar.
- **pipet_scale** (float) - Optional - Custom scaling factor for price conversion.

### Response
#### Success Response (200)
- **DataFrame** (pandas.DataFrame) - A DataFrame containing columns: time, ask, bid, ask_volume, bid_volume.
```

--------------------------------

### Read Tick Data

Source: https://context7.com/keyhankamyar/tickvault/llms.txt

Decode and retrieve tick data into a pandas DataFrame. Supports strict mode for gap detection and custom pipet scaling.

```python
from datetime import datetime
from tick_vault import read_tick_data

# Read all available data for a symbol
df = read_tick_data(symbol='XAUUSD')
print(df.head())
# Output:
#                          time       ask       bid  ask_volume  bid_volume
# 0     2024-01-01 00:00:00.123  2062.345  2062.123     1500000     2000000
# 1     2024-01-01 00:00:00.456  2062.346  2062.124     1200000     1800000
# ...

# Read specific date range
df = read_tick_data(
    symbol='EURUSD',
    start=datetime(2024, 1, 1),
    end=datetime(2024, 2, 1)
)
print(f"Total ticks: {len(df)}")
print(f"Time range: {df['time'].min()} to {df['time'].max()}")
# Output: Total ticks: 45000000
#         Time range: 2024-01-01 00:00:00 to 2024-01-31 23:59:59

# Strict mode (default): raises error if data is incomplete
df = read_tick_data(
    symbol='XAUUSD',
    start=datetime(2024, 1, 1),
    end=datetime(2024, 2, 1),
    strict=True,         # Ensures no gaps in data
    show_progress=True   # Shows tqdm progress bar while decoding
)

# Non-strict mode: clips to available data range
df = read_tick_data(
    symbol='XAUUSD',
    start=datetime(2020, 1, 1),  # May be before first available
    end=datetime(2030, 1, 1),    # May be after last available
    strict=False  # Automatically adjusts to available range
)

# Custom pipet scale for non-standard symbols
df = read_tick_data(
    symbol='CUSTOM_PAIR',
    start=datetime(2024, 1, 1),
    end=datetime(2024, 2, 1),
    pipet_scale=0.01  # Custom scaling factor for price conversion
)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.