TradeGuard OSS

Install

pip install tradeguard-oss

TradeGuard OSS is an open-source toolkit for validating trading journals, checking risk hygiene, and computing reproducible performance and journal-integrity diagnostics from closed trades.

Status: active early development (v0.14.0). The project is intended for research, education, journaling, and system-quality checks. It is not financial advice and it does not place trades.

Why TradeGuard?

Trading journals often contain missing stop losses, inconsistent direction labels, invalid timestamps, duplicate records, incomplete position sizing, or performance statistics that cannot be reproduced. TradeGuard turns those checks into dependency-light, testable rules and deterministic reports.

Current capabilities

• Versioned CSV journal schema and row-level diagnostics
• Long/short PnL, initial risk, and R-multiple calculation
• Win rate, net PnL, expectancy, gross profit/loss, profit factor, breakeven count, best/worst trade, and closed-trade maximum drawdown
• Stop-loss and data-quality validation
• Deterministic SHA-256 journal fingerprints
• Versioned tradeguard.trial-ledger.v1 evidence bundles with explicit run IDs, deterministic evidence fingerprints, parent-chain linkage, and tamper verification
• Versioned tradeguard.evidence-bundle.v1 offline certification with deterministic PASS/FAIL integrity checks, bundle fingerprints, and CI-friendly verification
• Deterministic journal reconciliation with exact source-artifact fingerprints, order-independent semantic audit fingerprints, duplicate-aware deltas, field-level drift evidence, and tamper-verifiable reconciliation envelopes
• Exact duplicate-trade detection and blocking integrity diagnostics
• Entry-notional portfolio exposure by normalized symbol and side
• Gross/net notional exposure and configurable portfolio, symbol, and trade notional limits
• Stop-based historical risk budgets with explicit incomplete-data diagnostics
• Deterministic segmented analytics by symbol and side
• Optional deterministic closed-at grouping by calendar day or month
• Explicit mapped CSV imports with deterministic field-level diagnostics and read-only dry-run preview
• Source-structure integrity checks for duplicate CSV headers and unexpected extra row values
• Explicit reusable CSV import profiles with fail-closed CLI selection and deterministic profile introspection
• Exact source-artifact SHA-256 provenance bound into reports and Trial Ledger evidence
• Fail-closed certification CLI gate: only valid PASS bundles exit successfully
• Stable additive tradeguard.report.v1 contract with explicit compatibility rules and executable consumer-contract tests
• Human-readable or versioned JSON CLI output
• Deterministic JSON report export
• Automated tests across Python 3.10–3.13 plus distribution wheel smoke-install validation

Install for development

git clone https://github.com/hesam1111111111/tradeguard-oss.git
cd tradeguard-oss
python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
pip install -e .[dev]
pytest -q

CSV format

Required columns:

symbol,side,entry,exit

Optional columns:

stop_loss,quantity,opened_at,closed_at

Example:

symbol,side,entry,exit,stop_loss,quantity,opened_at,closed_at
BTCUSDT,long,60000,61500,59000,0.1,2026-01-01T10:00:00,2026-01-01T13:00:00
ETHUSDT,short,3200,3100,3260,1.0,2026-01-02T09:00:00,2026-01-02T12:00:00

CLI

Native TradeGuard CSV:

tradeguard examples/sample_journal.csv
tradeguard examples/sample_journal.csv --json
tradeguard examples/sample_journal.csv --output report.json

Explicit mapped import from a differently named CSV:

tradeguard examples/mapped_journal.csv \
  --map symbol=Ticker \
  --map side=Direction \
  --map entry=OpenPrice \
  --map exit=ClosePrice \
  --map stop_loss=Stop \
  --map quantity=Size \
  --json

Explicit reusable profile from the CLI:

tradeguard export.csv --import-profile generic_ticket_export --json
tradeguard export.csv --import-profile generic_ticket_export --import-preview --json

A named profile must be selected explicitly. --import-profile and --map are mutually exclusive, and unknown profile names fail closed. Profile-based reports preserve both the selected profile name and resolved mapping in import provenance; Trial Ledger evidence also records the selected profile.

Mappings are explicit by design. TradeGuard does not guess aliases or infer ambiguous columns. The report adds an import provenance section with source/imported/rejected row counts, the exact mapping, completeness, and source-indexed diagnostics. If mapped import is incomplete, metrics/risk/segments are suppressed rather than computed from a partial dataset.

Reconcile a canonical journal against another export or migration result:

tradeguard baseline.csv --reconcile-with migrated.csv --json
tradeguard baseline.csv --reconcile-with migrated.csv --output reconciliation.json --fail-on-drift

Reconciliation is deterministic and offline. Row order does not matter, duplicate multiplicity is preserved, and uniquely identifiable changed trades report field-level differences. The --fail-on-drift switch exits with status 1 when differences are found, making the command usable as a CI or migration integrity gate. Saved reconciliation JSON also carries a deterministic envelope fingerprint and can be independently checked with tradeguard --verify-reconciliation reconciliation.json; verification fails closed if the envelope or recorded source provenance is altered. Reconciliation uses a separate tradeguard.reconciliation.v1 machine-readable envelope and does not modify the existing analytics report contract.

Add deterministic temporal analytics based on the recorded closed_at value:

tradeguard examples/sample_journal.csv --group-closed-by day --json
tradeguard examples/sample_journal.csv --group-closed-by month --output report.json

The report retains the tradeguard.report.v1 envelope and includes source, metrics, validation issues, journal fingerprint, structured integrity diagnostics, risk analysis, segmented analytics, and optional import provenance. Metrics are skipped when blocking validation, duplicate-record errors, or incomplete mapped import make analysis unsafe.

The stable machine-readable contract and compatibility rules are documented in docs/report-contract-v1.md.

Python API

from tradeguard import (
    RiskLimits,
    Trade,
    aggregate_exposure,
    analyze_by_closed_period,
    analyze_trades,
    check_risk_limits,
    import_mapped_csv,
    journal_fingerprint,
    reconcile_journals,
    reconciliation_fingerprint,
    validate_trades,
)

trades = [Trade("BTCUSDT", "long", entry=60000, exit=61500, stop_loss=59000, quantity=0.1)]
print(validate_trades(trades))
print(journal_fingerprint(trades))
print(analyze_trades(trades))
print(analyze_by_closed_period(trades, "month"))
print(aggregate_exposure(trades))
print(check_risk_limits(trades, RiskLimits(max_gross_notional=10000)))

candidate = [Trade("BTCUSDT", "long", entry=60000, exit=61400, stop_loss=59000, quantity=0.1)]
audit = reconcile_journals(trades, candidate)
print(audit.clean, audit.mismatches)
print(reconciliation_fingerprint(trades))

mapped = import_mapped_csv(
    "examples/mapped_journal.csv",
    {"symbol": "Ticker", "side": "Direction", "entry": "OpenPrice", "exit": "ClosePrice"},
)
print(mapped.imported_rows, mapped.rejected_rows)

Exposure semantics

aggregate_exposure and notional risk limits use absolute entry * quantity values from the supplied journal. They describe historical entry-notional concentration; they are not live positions, mark-to-market exposure, margin usage, or broker account state.

Temporal semantics

Temporal grouping uses the recorded closed_at value exactly as supplied. TradeGuard does not guess or convert timezones; callers combining timestamps from different zones should normalize them before calendar grouping.

Development policy

Behavioral changes should arrive through scoped branches and pull requests with regression tests. CI runs the test suite across supported Python versions before changes are merged. Public examples must be synthetic or privacy-safe.

Roadmap

Near-term work includes community-validated offline adapter profiles, deeper source-data integrity edge cases, and downstream consumer feedback backed by reproducible synthetic fixtures. Live brokerage connectivity and order execution are outside the current core scope.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md, follow the CODE_OF_CONDUCT.md, open an issue for material changes, and include tests for behavioral changes.

Repository-maintainer review criteria and evidence are tracked in docs/oss-application-readiness.md.

Security and privacy

TradeGuard does not require API keys for its core journal analytics. Do not commit broker credentials, exchange keys, private trade exports, or personal financial data. See SECURITY.md.

License

MIT. See LICENSE.