Trader Risk Audit

Trader Risk Audit is a local-first Python CLI that compares executed trade rows with an explicit risk policy and produces deterministic, source-traceable audit artifacts. It does not place trades, connect to live accounts by default, choose thresholds for a trader, or use an AI model to decide whether a rule was broken.

This software is an engineering and record-review tool, not investment, financial, legal, tax, or trading advice. A flagged row is evidence that the configured deterministic rule matched the provided data; it is not a claim about strategy quality, causation, expected returns, or what anyone should do.

Maturity

Status: alpha, local CLI and evidence project.

• The deterministic core has a 263-test extracted-history baseline.
• Synthetic and public-data rehearsal packs demonstrate artifact shape and traceability; they are not customer, production, PMF, or performance evidence.
• No hosted service, production SLO, audited financial calculation, regulatory certification, or real-user metric is claimed.
• Read-only exchange code is fixture-tested. The repository does not perform a credentialed live exchange import in its default or CI paths.
• Private inputs must remain outside git and require an operator-approved local handling process.

Five-minute path

Requirements: Python 3.12 on a POSIX/Linux environment.

python3.12 -m venv .venv
.venv/bin/pip install .

.venv/bin/trader-risk-audit audit \
  --trades examples/synthetic_quickstart/trades.csv \
  --policy examples/synthetic_quickstart/policy.yaml \
  --output-dir /tmp/trader-risk-audit-quickstart

Inspect the generated evidence:

sed -n '1,120p' /tmp/trader-risk-audit-quickstart/report.md
.venv/bin/python -m json.tool /tmp/trader-risk-audit-quickstart/violations.json
.venv/bin/python -m json.tool /tmp/trader-risk-audit-quickstart/manifest.json

Export sanitized observations for a separately configured eval harness:

.venv/bin/trader-risk-audit eval-export \
  --run-dir /tmp/trader-risk-audit-quickstart \
  --case-id synthetic-quickstart-v1 \
  --output /tmp/trader-risk-audit-quickstart/eval-evidence.json

Expected artifact shapes and a trace preview are committed in examples/synthetic_quickstart. The sample is fully synthetic and represents no person, account, broker, or recommendation.

Inputs

The minimal trade CSV fields are:

timestamp,symbol,side,quantity,price,fees,account_id

Policies are explicit YAML documents. Supported deterministic rule types are:

• max_daily_loss;
• max_drawdown;
• cooldown_after_loss;
• max_position_size;
• forbidden_assets;
• max_leverage, only when explicit leverage data is available.

Missing fields and unsupported policy semantics must be reported as limitations or rejected; the tool must not silently infer leverage, balance, intent, trader identity, or a suitable threshold.

The repository also retains soft, medium, and hard starter-policy fixtures for internal validation. They are examples, not recommended settings: review and customize every threshold for the supplied policy contract. See docs/STARTER_POLICY_PROFILES_RU.md.

Outputs and traceability

An audit run writes:

• normalized_trades.json — canonical input rows with stable row IDs;
• violations.json — rule observations with source row IDs;
• attribution_summary.json — reconciled P&L buckets;
• report.md — human-readable deterministic report;
• telegram_packet.txt — local delivery-format preview;
• manifest.json — artifact SHA-256 records and a stable content hash.

The manifest detects artifact drift when verified by the code, but local hashes do not make files immutable or authenticate a publisher.

Eval boundary

eval-export verifies an actual audit manifest and exports sanitized observations, checks, metrics, and trace samples. It deliberately applies no ground truth or thresholds and does not bundle Eval Ground Truth Lab. A separate harness owns the dataset, expected outcomes, comparison policy, and pass/fail decision. See docs/EVAL_ADAPTER_BOUNDARY.md.

Data and privacy limits

• Prefer synthetic examples for development and review.
• Never commit API keys, exchange credentials, private exports, names, contact details, balances, account identifiers, or paid-pilot notes.
• Public-chain and regulator datasets can still carry source terms, privacy, transformation, attribution, and interpretation constraints.
• Public or on-chain availability does not prove ownership, trader identity, intent, realized P&L, or consent to profile a person.
• Generated reports can be wrong when source rows, timezone, fees, policy mapping, account scope, or unsupported fields are wrong.

Authored code, documentation, and synthetic fixtures are Apache-2.0. Externally sourced demo rows remain subject to their original source terms and are not relicensed by this repository. See docs/LICENSE_AND_DATA_REVIEW.md.

Data exclusion: Dune-derived demo rows were purged from every ref in the public history candidate because current Dune terms do not establish repository redistribution rights. Do not reintroduce those rows without written permission and a new source/license review.

Verification

.venv/bin/python -m pytest tests -q --tb=short
.venv/bin/ruff check trader_risk_audit tests
.venv/bin/ruff format --check trader_risk_audit tests
.venv/bin/python -m pip wheel --no-deps . -w /tmp/trader-risk-audit-wheel

CI uses no broker, exchange, Telegram, or other external credentials.

The v0.2.0 publication-candidate receipt records the exact standalone and separate Eval integration boundaries in docs/RELEASE_EVIDENCE_V0.2.0.md. Its PASS is synthetic contract-compatibility evidence, not a user, production, or financial performance claim.

Project map

• docs/ARCHITECTURE.md — deterministic workflow and boundaries.
• docs/CLI.md — supported public CLI paths.
• docs/EVIDENCE_INDEX.md — proof and rehearsal artifacts.
• docs/RELEASE_EVIDENCE_V0.2.0.md — exact release and Eval receipts.
• docs/KNOWN_LIMITS.md — concise operational/data limits.
• demo — synthetic and externally sourced rehearsal packs with provenance.
• SECURITY.md — vulnerability and sensitive-data handling.
• CONTRIBUTING.md — contribution and provenance requirements.

Historical phase notes remain for development provenance. They are not a current roadmap, production-status statement, or claim that blocked private validation has occurred.

License

Apache License 2.0. See LICENSE and the data carve-outs in docs/LICENSE_AND_DATA_REVIEW.md.