Metadata-Version: 2.4
Name: gorazd
Version: 0.7.0
Summary: Institutional quantitative execution and physical reality matrix.
Requires-Python: >=3.10
Requires-Dist: numba>=0.59.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: optuna>=3.0.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: polars>=0.20.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyzmq>=25.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.0.0
Requires-Dist: tomli>=2.0.0
Requires-Dist: xgboost>=2.0.0
Description-Content-Type: text/markdown

﻿# GORAZD: Institutional UHFT Execution Matrix

Gorazd is an ultra-high-frequency, zero-allocation quantitative execution engine designed for bare-metal Linux deployments. It physically bypasses the Python Global Interpreter Lock (GIL) and OS-level mutexes to achieve deterministic microsecond execution for Machine Learning models.

## Architectural Supremacy
* **The 4-Core Hydra:** Mechanically hijacks 4 CPU cores (`isolcpus`) for Ingestion, Execution, Risk (Kill-Switch), and Concept Drift monitoring.
* **Page-Aligned Memory:** Eradicates OS page faults by mapping monolithic tensors directly to physical RAM via `mmap`.
* **Lock-Free IPC:** Inter-Process Communication utilizing C11 atomic pointers and 64-byte L1 cache-line padding.
* **Native C-API Inference:** Bypasses Python wrappers entirely, mapping RAM directly to `libxgboost.dll/so` via `ctypes`.
* **Microstructure Physics:** Custom XGBoost objective gradients mathematically constrained by Maker/Taker rebates and Continuous Risk Lagrangians.
* **Avellaneda-Stoikov Routing:** Dynamic Kelly capital exposure scaled by inverse volatility and skewed by real-time inventory risk.

## Environmental Configuration (.env)
Gorazd operates across two distinct deployment realms. You must create a `.env` file in your execution directory.

    # Execution Mode: RETAIL (Free APIs) or BLOOMBERG (B-Pipe)
    data_source="RETAIL"

    # Free API Infrastructure (Used if data_source="RETAIL")
    tiingo_api_key="YOUR_TIINGO_KEY"
    alpaca_api_key="YOUR_ALPACA_KEY"
    alpaca_api_secret="YOUR_ALPACA_SECRET"

    # Risk Constraints
    max_leverage=1.5
    base_capital=250000.0

## The Global CLI Matrix
Gorazd installs directly into your operating system's PATH. You do not need to write scripts to operate the core pipeline.

    gorazd-fetch   # Polls APIs/Bloomberg, calculates scalars, bakes Parquet.
    gorazd-train   # Executes Purged CV and non-linear risk Optimization.
    gorazd-ui      # Ignites the ZeroMQ tactical terminal dashboard.
    gorazd-ignite  # Launches the 4-Core UHFT memory-mapped daemon.

## Top-Level Python API
For quantitative researchers looking to integrate Gorazd into existing frameworks, the `gz` top-level namespace provides brutal, operational brevity.

    import gorazd as gz

    # 1. Synthesize Physical Tensors
    compiler = gz.TensorCompiler(target="SPY")
    compiler.compile(start_date="2016-01-01")

    # 2. Optimize Physics-Aware Matrix
    optimizer = gz.Optimizer()
    optimizer.fit(parquet_file="SPY_institutional_matrix.parquet")

    # 3. Ignite the Multicore Daemon
    engine = gz.Engine(target="SPY", model_file="core.ubj")
    engine.ignite()

## Bare-Metal OS Tuning (Equinix NY4)
Do not run this engine on a standard OS if capital is at risk. You must alter the Linux kernel via GRUB to isolate the physical CPU cores from background OS interruptions.

    # /etc/default/grub
    GRUB_CMDLINE_LINUX_DEFAULT="quiet splash isolcpus=1,2,3,4 nohz_full=1,2,3,4 rcu_nocbs=1,2,3,4"
