中文说明

Open-core toolkit for reproducible financial research workflows.

Licensed under Apache License 2.0. v2.0.1 — see RELEASE_NOTES.md.

IndiciumForge standardizes workflow contracts, output artifacts, and extension boundaries. Default examples use synthetic fixtures only. Outputs are for human research review—not order routing or portfolio actions.

IndiciumForge is an open-core toolkit for building reproducible financial research workflows. It helps you:

• Define repeatable research workflow chains (recipes and session stages)
• Write auditable output artifacts (JSON/CSV bundles with schema IDs)
• Check output completeness before deeper review (artifact audit)
• Compare runs against reference outputs when you refactor stages or extensions
• Load private data, factor, and recipe extensions via packs—without forking core contracts

IndiciumForge was extracted from an internal financial research workflow and generalized into an open-core toolkit.

New to the vocabulary? Start with docs/GLOSSARY.md.

• Not live trading, order routing, or portfolio management
• Not a substitute for compliance review or published research opinions
• Not a one-click “signals” product—outputs are workflow evidence for your team to interpret

Requirements: Python 3.10+.

cd <repo-root>
python -m pip install -e packages/indiciumforge-core -e packages/indiciumforge-workflow -e packages/indiciumforge-cli -e ".[dev]"
indiciumforge --help
indiciumforge workflow synthetic-e2e \
  --trade-date 2026-06-23 \
  --artifact-root /tmp/indiciumforge-demo \
  --daily-review-fixture tests/fixtures/market_awareness/theme_sectors_demo.yaml \
  --preopen-review-fixture tests/fixtures/workflow/preopen_buy_point_review_demo.csv
indiciumforge parity run \
  --parity-config tests/fixtures/parity_reference_demo/parity_config_demo.yaml \
  --artifact-root /tmp/indiciumforge-parity-demo

On Windows, use a writable temp directory (for example %TEMP%\indiciumforge-demo).

flowchart TB
  subgraph openCore [IndiciumForge_OpenCore]
    Core[indiciumforge_core]
    Workflow[indiciumforge_workflow]
    CLI[indiciumforge_cli]
  end
  subgraph privateExt [Private_Extensions_Local]
    DataPack[DataProvider_pack]
    FactorPack[FactorDetector_pack]
    RecipePack[Recipe_extension]
  end
  subgraph refOut [Reference_Outputs_ReadOnly]
    RefStore[Saved_reference_artifacts]
  end
  openCore -->|"ports_and_contracts"| privateExt
  openCore -->|"output_comparison"| refOut

flowchart LR
  Fixture[Fixture_or_Provider] --> Recipe[RecipeRunner]
  Recipe --> Artifacts[Artifact_store]
  Artifacts --> Audit[Output_completeness_check]
  Artifacts --> Compare[Reference_compare]
  RefTree[Reference_outputs] --> Compare
  Compare --> Report["match_or_gap_report"]

flowchart TB
  Root[IndiciumForge_repo]
  Root --> CorePkg[packages/indiciumforge_core]
  Root --> WfPkg[packages/indiciumforge_workflow]
  Root --> CliPkg[packages/indiciumforge_cli]
  Root --> Tests[tests]
  Root --> Docs[docs]

Deeper diagrams: docs/SYSTEM_MAP.md, docs/diagrams/context.md.

Full capability matrix: CAPABILITY_REGISTER.md.

In this repository: ports, schemas, demo fixtures, CLI, comparison harness, and author docs.

Operator-local (not in OSS): live data adapters, proprietary factor detectors, production recipe logic, credentials, and local reference trees.

Start here: docs/EXTENSION_AUTHOR_GUIDE.md · examples/private_extension_template/

Planning only (not in v2.0.0): a short public-data smoke workflow using OpenBB as an adapter example—one command, small deterministic artifact tree, no private paths.

Details: docs/OPENBB_PUBLIC_DEMO_PLAN.md

Published on PyPI at v2.0.1:

pip install indiciumforge-cli==2.0.1

Install sibling packages explicitly if needed:

pip install indiciumforge-core==2.0.1 indiciumforge-workflow==2.0.1 indiciumforge-cli==2.0.1

Release procedure: docs/PYPI_RELEASE_CHECKLIST.md, docs/TESTPYPI_RELEASE_RUNBOOK.md.

cd <repo-root>
python -m pip install -e packages/indiciumforge-core
python -m pip install -e packages/indiciumforge-workflow
python -m pip install -e packages/indiciumforge-cli
python -m pip install -e ".[dev]"

The CLI entry point is indiciumforge (from indiciumforge-cli).

cd <repo-root>
python -m pytest -q
python -m ruff check .

On Windows, if pytest fails with Temp/.pytest_cache permission errors:

python -m pytest -p no:cacheprovider -q --basetemp "$env:TEMP\indiciumforge_pytest\pytest-basetemp-<unique>"

indiciumforge --help
indiciumforge workflow market-gate --trade-date 2026-06-23 --artifact-root <artifact-root>
indiciumforge workflow chain --trade-date 2026-06-23 --artifact-root <artifact-root> \
  --daily-review-fixture tests/fixtures/market_awareness/theme_sectors_demo.yaml \
  --post-close-review-fixture tests/fixtures/workflow/post_close_buy_point_review_demo.csv \
  --preopen-review-fixture tests/fixtures/workflow/preopen_buy_point_review_demo.csv
indiciumforge artifact audit --artifact-root <artifact-root> --trade-date 2026-06-23 --stage-type market_gate
indiciumforge parity run --parity-config tests/fixtures/parity_reference_demo/parity_config_demo.yaml --artifact-root <artifact-root>

artifact audit checks structural completeness (required files, schema IDs, trade_date consistency). Semantic comparison uses the reference-comparison harness.

Expected inputs under --artifact-root:

artifact-root/
  workflows/{YYYYMMDD}/preopen/buy_point_review_internal.csv
  market_awareness/{YYYYMMDD}/daily_review/theme_state_ranking.csv

Outputs: artifact-root/workflows/{YYYYMMDD}/market_gate/ (strict, observation, active_watch, rejected, calibration, summary, state).

Full command walkthrough (chain, factor scan, recipe, provider):

indiciumforge workflow chain \
  --trade-date 2026-06-23 \
  --artifact-root /tmp/indiciumforge-chain \
  --daily-review-fixture tests/fixtures/market_awareness/theme_sectors_demo.yaml \
  --post-close-review-fixture tests/fixtures/workflow/post_close_buy_point_review_demo.csv \
  --preopen-review-fixture tests/fixtures/workflow/preopen_buy_point_review_demo.csv

indiciumforge factor scan \
  --trade-date 2026-05-10 \
  --artifact-root /tmp/indiciumforge-factor \
  --ohlcv-fixture-root tests/fixtures/ohlcv \
  --asset-fixture-list tests/fixtures/factor_scan_assets.yaml \
  --factor-pack tests/fixtures/factor_pack_demo.yaml

indiciumforge workflow chain \
  --trade-date 2026-06-23 \
  --artifact-root /tmp/indiciumforge-recipe \
  --recipe tests/fixtures/workflow/recipe_ashare_daily_v1.yaml \
  --recipe-extension-pack tests/fixtures/recipe_extension_pack_demo.yaml \
  --daily-review-fixture tests/fixtures/market_awareness/theme_sectors_demo.yaml

indiciumforge provider inspect --ohlcv-fixture-root tests/fixtures/ohlcv

The sections below are for operators migrating from a legacy internal workflow or extending the signed v1.0 path. New users can skip this.

Per-release scope: RELEASE_NOTES.md, CAPABILITY_REGISTER.md, docs/V1_0_DEFINITION.md.

Historical migration reconciliation: docs/MIGRATION_ROADMAP.md.

Frozen legacy reference label used by OSS golden fixtures (maintainer context only):

indiciumgrid @ indiciumgrid-golden-v1

Golden export script (requires local frozen reference checkout):

python scripts/export_golden_market_gate.py

Roadmap: docs/AGENT_SKILL_ROADMAP.md.

Markdown draft (not submitted to arXiv): docs/paper/INDICIUMFORGE_ARXIV_DRAFT.md · OUTLINE.md · FIGURES.md

Design-only in v2.0.0: docs/mcp/INDICIUMFORGE_MCP_DESIGN.md, docs/plugin/INDICIUMFORGE_PLUGIN_DESIGN.md, docs/FUTURE_SURFACES.md.