StratHUB
From PDF methodology to a verifiable strategy specification.
Flows and contracts reviewed in source. Document, embedding and validation stages are distinct; no measured quality, profit or latency result is published.
Problem and objective
StratHUB explores how trading methodologies described in documents can become explicit, verifiable rules. PDFs can mix explanations, charts and entry, exit and risk criteria; that information needs structure before another system can consume it.
The project connects document processing, applied AI and financial-systems engineering. Its output is a Strategy Spec: a declarative JSON representation linked to source material, validated and consistently identified across services.
Architecture: three runtimes, one contract
The monorepo separates a Next.js/TypeScript interface, Python/FastAPI API and workers, and a Rust executor. The shared strategy-spec package centralizes the JSON Schema and TypeScript, Python and Rust implementations, allowing each layer to use the same contract without depending on another language’s internal objects.
Supabase supports authentication, persistence and storage; PostgreSQL/pgvector holds data and embeddings. Redis and Arq support asynchronous processing. Docker Compose and service Dockerfiles organize local development and packaging.
Ingestion: from upload to source pages
The API organizes jobs, PDF registration, upload confirmation and processing submission. A worker reads files from storage, extracts content and tracks document status. Extraction, embeddings and model calls run outside the primary request because they can take time.
Extraction uses PyMuPDF. Pages with little native text can use Tesseract OCR when available. Processing retains source-page information, OCR confidence and flags pages with little text. Charts and images do not automatically become reliable rules simply because they are inside a PDF.
Chunking and embeddings: context with provenance
Text is split page by page into overlapping word windows, preserving document and page identifiers. Embeddings are generated in batches and stored with text, model, dimensions and provenance. The worker can store embeddings and generate the specification concurrently.
In the reviewed implementation, the compiler sends a bounded set of chunks directly to the LLM. Stored vectors provide a foundation for retrieval, but this flow alone does not demonstrate semantic search integrated into a complete RAG pipeline. Data preparation and retrieval actually used are distinct.
The LLM as compiler, not executor
The orchestrator integrates models through OpenRouter and requests JSON Schema structured output. Context includes the contract, available documents and page-referenced excerpts. User-provided material is treated in the prompt as untrusted data, separate from system instructions.
Responses undergo parsing, structural validation, semantic checks and document-reference validation. Validation errors feed the next repair attempt within a bounded sequence of configured models. The intended output is a constrained JSON DSL; model-generated Python is not executed.
Strategy Spec and cross-language reproducibility
The specification describes strategy elements allowed by the contract rather than arbitrary logic. Semantic validation complements the schema: well-formed JSON can still contain inconsistent rules. Relevant decimal fields use strings to reduce ambiguity between runtimes.
The spec_hash uses SHA-256 over a canonical representation excluding the hash field itself. Implementations sort keys, preserve array order and normalize serialization. Fixtures and tests check contract identity across TypeScript, Python and Rust. The hash identifies the artifact; it does not prove strategy quality or profitability.
Paper execution, events and risk controls
Rust code includes a paper-validation path that consumes market data over WebSocket and uses virtual execution. Components include a simulated broker, order intents, fills, persisted state and an outbox tracking execution. Decimal arithmetic, risk limits, reconnect throttling and clock-skew monitoring form part of that foundation.
The API ingests event batches and updates heartbeats. A scorecard returns pass/fail reasons using criteria such as trade count, duration, drawdown, slippage and execution errors. Validation records include idempotency, concurrency limits, budget and TTL logic. These are code components, not evidence of a completed real financial validation.
Interface and responsibility boundaries
The interface includes login, a hub, job creation and review/validation pages. Next.js route handlers mediate Python-service calls, keeping infrastructure credentials server-side. Migrations organize documents, strategies, embeddings and runs, with user-scoped access policies.
Some surfaces remain under construction. The human-review page is a scaffold for a fuller stage, not a finished approval workflow. Likewise, validation provisioning metadata does not establish that external machines have actually been created and operated.
Tests, contracts and continuous integration
The repository contains ingestion, job, structural/semantic validation, event and scorecard tests, plus shared-contract fixtures. API tests mock external dependencies in specific scenarios, verifying rules without consuming paid services; this does not replace a real integrated run.
CI defines Rust, Python and Node checks including formatting, static analysis, tests and interface build/typecheck. Secret scanning and destructive-migration review are also defined. This review examined suite and workflow contents without claiming unmeasured coverage or execution results.
Current state and next steps
The reviewed code goes beyond the scaffold described in the root README: it contains ingestion, structured generation, contracts and parts of paper validation. However, backtest dispatch remains a placeholder and live mode is guarded pending additional controls. This review does not establish real-capital operation or validated financial returns.
Next steps are completing human review, integrating and validating the backtest interpreter, demonstrating the end-to-end flow and reviewing controls before real operation. The project demonstrates integration of documents, typed contracts, asynchronous processing and inspectable execution infrastructure.