Skip to content

README.md

Latest commit

 

History

History
206 lines (164 loc) · 8.26 KB

README.md

File metadata and controls

206 lines (164 loc) · 8.26 KB

Clear

Clear is a local-first portfolio, analytics, and OSINT platform with shared CLI, API, and web surfaces. It combines client/account data, deterministic financial calculations, global tracker feeds, news/intel summaries, and an immersive globe foundation that is now gated by the repo's standards plan.

Quick Start

git clone git@github.com:denv3rr/clear.git --depth 1
cd clear
python clearctl.py start
python clearctl.py stop

What It Does

  • Stores client, account, holding, and lot data in SQLite, with JSON kept for import/export.
  • Exposes the same analytics through the CLI, FastAPI routes, and the web UI.
  • Runs OSINT workflows for trackers, news, and regional intel.
  • Supports reports and exports with shared view-models and provenance metadata.
  • Builds toward a globe-first presentation layer, but only behind the active standards gate.

Standards And Current Status

Clear now treats standards compliance as a delivery gate, not a cleanup task.

Stack

  • Core runtime: Python, FastAPI, SQLAlchemy, Pandas, NumPy, Rich
  • Web app: React, TypeScript, Vite, Tailwind
  • Visualization: Three.js, React Three Fiber, MapLibre, Leaflet fallback, Plotly, Recharts
  • Testing: pytest, Playwright

Configuration

Copy .env.example to .env. The most common variables are below.

Variable Purpose
CLEAR_WEB_API_KEY Enables API key auth for the web/API stack.
FINNHUB_API_KEY Optional market symbol and quote lookups.
OPENSKY_CLIENT_ID OpenSky OAuth client id for flight feeds.
OPENSKY_CLIENT_SECRET OpenSky OAuth client secret for flight feeds.
SHIPPING_DATA_URL Optional vessel/shipping feed endpoint.
CLEAR_INCLUDE_COMMERCIAL Include commercial flights when set to 1.
CLEAR_INCLUDE_PRIVATE Include private flights when set to 1.

Notes:

  • OpenSky is the only flight feed path right now.
  • When CLEAR_WEB_API_KEY is set, the launcher forwards it to the web UI as VITE_API_KEY for local auth.
  • Additional tracker/feed flags and OSINT notes live in docs/osint.md.

Common Commands

python clearctl.py start
python clearctl.py status
python clearctl.py stop
python clearctl.py web
python clearctl.py cli
python clearctl.py doctor

Testing

python -m pytest
cd web
npx playwright test

Browser-test policy:

  • Positive-path browser tests must use the real local stack or captured real fixtures with provenance.
  • Demo/mock/synthetic positive-path browser data is not allowed.

Data Sources

Source Purpose
Finnhub Optional symbol/quote lookups
Yahoo Finance Historical pricing and macro snapshots
OpenSky Flight tracking
Open-Meteo Weather context for intel/reporting
GDELT Conflict/news signal input
RSS feeds Cached headlines for market and OSINT workflows

Methods Snapshot

The core deterministic formulas are implemented in modules/client_mgr/calculations.py.

Metric Formula used in code Notes Source
Annualization factor A = seconds_per_year / mean(delta_t) or 252 fallback Uses timestamp spacing when available. calculations.py
Mean annual return mean(r) * A Used in core and risk metrics. calculations.py
Annualized volatility std(r, ddof=1) * sqrt(A) Sample standard deviation. Investor.gov Sharpe ratio overview
Sharpe ratio ((mean(r) - r_f / A) / std(r)) * sqrt(A) Lightweight summary paths may use r_f = 0. Investor.gov Sharpe ratio overview
Beta cov(r_p, r_m) / var(r_m) Uses aligned return series. Sharpe 1964 CAPM paper
Max drawdown min((V_t - peak(V_t)) / peak(V_t)) Computed from cumulative returns. calculations.py
Historical VaR / CVaR quantile(r, 1-q) and mean(r <= VaR_q) Empirical tail metrics. Investor.gov VaR bulletin
EWMA volatility var_t = lambda * var_{t-1} + (1-lambda) * r_t^2 lambda defaults to 0.94. 1996 RiskMetrics Technical Document

Additional deterministic methods in the same module include Black-Scholes, Shannon entropy, permutation entropy, Hurst exponent, FFT spectrum, CUSUM change points, motif similarity, and CAPM-derived metrics. Their validation lives in the Python test suite rather than in the README.

Docs

Doc Purpose
docs/README.md Full docs index
docs/agent_git_standards.md Branch, commit, merge, push, and sensitive-file rules for agents
docs/us_gov_standards.md Mandatory standards baseline
docs/standards_remediation_plan.md Active standards gate and phase plan
docs/visual_modernization_plan.md Globe-first UX roadmap
docs/osint.md OSINT workspace and feed notes
docs/assistant_usage.md Assistant usage across CLI/API/web
docs/launchers.md Startup and shutdown behavior

Sources

Standards And Governance

Methods And Risk References

Data And Feeds

Current Default News Sources

Disclaimer

This project is for informational and operational analysis use. It does not provide financial, legal, or tax advice, and no content here should be treated as an offer to buy or sell securities.