ENGINEERING_STANDARDS.md

Engineering Standards

Blum must be developed as a serious open-source technical case study. Every shipped increment should be designed for correctness, efficiency, transparency and maintainability.

Non-Negotiable Rules

• Do not ship placeholders as working functionality.
• Do not fabricate data.
• Do not generate synthetic market prices, synthetic news, synthetic sentiment, synthetic backtest results or synthetic AI evidence.
• If a data source fails, report the failure clearly instead of filling the gap with fake values.
• If a feature cannot be fully implemented in the current increment, mark it as unavailable, document the limitation and do not present it as complete.
• Keep code, comments, UI copy and documentation in English.
• Treat every score as research triage, not financial advice or a trading recommendation.

Efficiency Standard

Every implementation should aim for the best practical efficiency available within the current architecture.

Required practices:

• Prefer batch operations over per-row network or database calls.
• Use incremental updates where possible.
• Avoid recomputing indicators, embeddings or model outputs when persisted results are fresh.
• Keep provider calls bounded, retry-aware and observable.
• Keep AI models lazy-loaded and task-specific.
• Cache expensive model or vector operations only when the cache is evidence-preserving and invalidation is clear.
• Avoid blocking frontend rendering on long-running ingestion or model tasks.
• Keep API responses structured, compact and explicit.

Data Integrity Standard

Every stored data row must preserve its source.

Required practices:

• Persist provider names for OHLCV data.
• Persist model names for sentiment, embeddings and AI explanations.
• Persist timestamps for ingestion, scoring and insight generation.
• Distinguish missing data from zero values.
• Distinguish provider failure from no matching data.
• Never silently downgrade from real data to synthetic data.

AI Standard

AI modules must be specialized and evidence-bound.

Required practices:

• Use FinBERT or equivalent financial NLP for financial sentiment when available.
• Keep VADER as a baseline or fallback, not the primary engine when FinBERT is available.
• Use sentence-transformers for semantic retrieval and clustering.
• Use the LLM only for structured explanation from retrieved evidence.
• The LLM must not invent facts, prices, events, forward returns, recommendations or catalysts.
• Store model metadata with each AI output.

Signal Standard

Signals must be explainable and auditable.

Required practices:

• Store factor inputs and normalized score components.
• Version score logic when weights or formulas change.
• Separate signal score, confidence, risk and classification.
• Explain why an asset surfaced.
• Explain what confirms the signal.
• Explain what contradicts the signal.
• Explain what to monitor next.
• Report missing evidence as part of the decision.

UI Standard

The frontend must behave like a financial intelligence platform, not a decorative landing page.

Required practices:

• Prioritize dense but readable information.
• Show what to watch and why.
• Make loading, empty and error states explicit.
• Use charts and tables to support decisions, not decoration.
• Keep dark professional styling, clear hierarchy and responsive layouts.
• Avoid consumer-style visual filler.

Verification Standard

Every meaningful increment should include verification.

Minimum checks:

• Python syntax or unit checks for backend changes.
• Type/build checks for frontend changes when dependencies are available.
• API smoke checks for changed endpoints when runtime is available.
• Documentation update when behavior, architecture or limitations change.
• Clear statement of what was and was not verified.