Lumiere

User guide

A plain-language guide for using the setup review workflow, voice mentor, visual TA sidekick, position-sizing calculator, and screen-read workflow.

Purpose

Lumiere helps active traders review a stock that is already moving before the order ticket. It combines market-data checks, recent news, a price/volume chart, deterministic pattern overlays, voice mentoring, position sizing, optional screen analysis, and strict-gated paper-plan review. When connected locally to IBKR Paper TWS, it can bring broker-aligned market context into that review.

The app is a research, education, controlled paper-trading, and owner-only live-experiment tool. It does not provide financial advice or guarantee profitability. Live trading is disabled by default.

Basic workflow

Enter a stock ticker in Symbol.
Keep or adjust the scanner thresholds.
Click Analyze.
Review the classification, metrics, criteria, chart, news, and reasoning.
Use Lumiere to review detected patterns, ask voice questions, and draw overlays.
If the stock is still interesting, use Position sizing + R target to model risk.
Build a paper trade plan, then preview a strict-gated paper bracket order.
If needed, upload or capture a broker/chart screen and run Analyze screen.

Scanner fields

Symbol: The stock ticker to analyze, such as NVDA, AAPL, or TSLA.
Change %: The minimum daily percentage change required to pass the daily-change rule. A value of 10 means the stock must be up or down at least 10% today to pass this check.
Move %: The minimum meaningful movement required. The app uses the largest of daily percent change, day range, and intraday chart movement.
Volume X: The minimum relative volume required compared with average volume. A value of 2 means today’s volume must be at least 2x the stock’s average volume.
Direction: Choose Both for large moves either way, Gainers for upside movers, or Losers for downside movers.
Analyze: Runs the market-data, chart, average-volume, and news checks.

Data sources

The app can use IBKR local data, Polygon cloud data when configured, or public Yahoo fallback data. IBKR Paper TWS integration is local-only by design: it brings broker-aligned market context into Lumiere while keeping broker credentials and execution outside Lumiere's V1 connector.

Source badge: Shows whether Lumiere is using IBKR local realtime, IBKR local delayed, Polygon cloud, Yahoo fallback, or stale/offline data. Lumiere must not trade on stale or fallback data.
IBKR local lane: Click this lane to inspect the broker-aligned data stack. TWS socket means Paper TWS is listening on port 7497. Worker means the isolated local Python service is reachable. Handshake means the worker completed the IBKR API handshake. Market data means the worker returned quote, chart, and daily bars. If any step is missing, Lumiere keeps using Polygon or Yahoo fallback.
Paper TWS settings: Use port 7497, enable socket clients, allow localhost connections only, and keep Read-Only API on for quote/chart analysis. If TWS asks whether to accept the API connection, approve the local worker connection.
IBKR worker: Install the Python dependency with python3 -m pip install -r tools/ibkr-worker/requirements.txt, then start the worker with npm run ibkr-worker. Start the app separately with npm start.
Delayed vs realtime: IBKR_MARKET_DATA_TYPE=delayed is the default because it works without live market-data subscriptions where delayed data is allowed. Use realtime only when the IBKR account has the required market-data permissions.
Paper-order gates: The app can still build strict paper trade plans and bracket previews. Actual Paper TWS order transmission remains outside the read-only V1 connector.
Authority modes: Coach cannot trade. Confirmed requires exact confirmation. Armed session requires an owner-armed time window. Autonomous is disabled until explicit admin unlock gates are active.

Reading the result

Classification: The overall filter label. Qualifies means the ticker passed the strongest set of checks. Watchlist or Research only means it deserves investigation but needs more confirmation. Reject means it failed too many checks for the current thresholds.
Price: The latest price returned by the app’s data source.
Daily change: How much the stock is up or down today.
Relative volume: Current volume compared with average volume. For example, 2.3x means volume is 2.3 times normal volume.
Criteria: The four rule checks: material news/report, daily price change, significant movement, and relative volume.
Price action: The recent intraday chart and volume bars.
Lumiere: The voice mentor, deterministic pattern list, visual overlays, pattern lesson, paper trade plan, and IBKR-style bracket preview workflow.
Background research: The raw returned headlines, publishers, times, and links. Treat this as the source/evidence list.
Reasoning: The app’s plain-English conclusion, catalyst interpretation, and suggested next checks.
Catalyst interpretation: A quick synthesis inside the Reasoning area. It does not repeat the full headline list. It summarizes whether the news looks like a strong company-specific catalyst, weak context, or mixed evidence. Use Background research to inspect the source headlines and links.

Lumiere

Start voice: Checks microphone permission, then starts an OpenAI Realtime voice session through a server-minted ephemeral key. If microphone access is blocked, enable it for Codex or ChatGPT in System Settings -> Privacy & Security -> Microphone, fully restart the app, reload Lumiere, and try again.
Detected patterns: Lists deterministic pattern candidates such as bull flag, bear flag, breakout/retest, support bounce, resistance rejection, VWAP reclaim/reject, gap-and-go, and trend continuation.
Teach this pattern: Compares the current chart with ideal and failed examples, including evidence, invalidation, and failure risks.
Build plan: Creates a risk-defined paper trade plan with entry trigger, stop, targets, R multiple, conflicts, and invalidation.
Preview paper bracket: Builds a strict-gated IBKR-style paper bracket draft. Blocked previews explain the reason.
Submit paper: Blocked in read-only worker mode until order routing is implemented inside the isolated worker.

Position sizing + R target

This section models risk after a stock is interesting enough to size. It separates capital from risk.

Side: Long for an upside trade or Short for a downside trade.
Risk $: The amount you are willing to lose if the stop is hit.
Entry: The planned entry price. Use current price fills this with the latest app price.
Stop: The price where the trade idea is invalidated. Long stops should be below entry; short stops should be above entry.
R target: The orange reward multiple. If risk per share is $3.00 and R target is 2.5, the target is $7.50 away from entry.
Max capital: Optional cap on buying power or position value.
Target price: The calculated target based on entry, stop, and R multiple.
Shares: The final share count after risk budget and optional capital cap.
Capital used: The total position value: shares x entry price. This is not the amount at risk.
Actual risk: The estimated loss if the stop is hit: shares x distance from entry to stop.
Target P&L: The planned reward at the calculated target price.
Stop distance: How far the stop is from entry, shown in dollars and percent.

Screen read

Use the screen-read panel to capture, upload, or paste a chart or broker screenshot, then click Analyze screen.

The screen read can help describe visible price action, chart direction, volume bars, support/resistance clues, and conflicts between the screen and the app’s market-data analysis. It should not be used as the only basis for a trade.

Review checklist

The catalyst is real and current.
The move is large enough for the selected strategy.
Volume is unusually high.
The chart is liquid enough to trade.
The spread is acceptable.
The stop level is clear.
The position size matches the intended dollar risk.
The capital used fits the account rules.
The target offers enough reward for the risk.

Common mistakes

Do not confuse Capital used with Actual risk.
Do not treat Qualifies as an automatic trade.
Do not ignore data warnings.
Do not enter a stop that does not match the trade side.