Replicating Jev X Sentiment Analysis for personal intraday use

Research date: 10 October 2026. Repository reviewed: brainstormity/Jev-X-Sentiment-Analysis, pinned to commit 7247424bb7f863d011323689692941dc58699eea.

This guide describes running the existing app on your own computer for one user. It is a crypto research terminal, with manual trade execution. It does not cover equities, broker integration, automated orders, or a publicly hosted service. The practical replication route is to reuse the Python app and its supplied browser interface.

Evidence labels: “Verified” means directly supported by the reviewed source or a stated local check. “Inference” means a conclusion drawn from that evidence. “Recommendation” means a proposed operating practice or modification, not an existing feature. “Unverified” marks something this review could not establish. Citations point to primary sources, with repository links pinned to the reviewed commit.

1. What the app does

Verified: You enter a crypto symbol and request analysis. The interface combines a market summary, keyword-based social statistics, a six-action decision distribution, sentiment and squeeze indicators, entry/stop/target levels, and an explorer containing up to 100 returned tweets. It includes a copy-ticket button and links to exchanges. The slider actually accepts every multiple of 50 from 50 to 1,000, although the README lists only five sample sizes. Analysis starts on a click or Enter; there is no automatic analysis on page load or periodic refresh. Interface, browser controller, analysis endpoint.

Intraday relevance — inference: This can help compare the current social narrative with price momentum and derivatives positioning before a discretionary trade. It is an on-demand snapshot, not a streaming execution terminal. Its default market inputs use 24-hour measures and one-hour candles, so the supplied strategy is not specifically tuned for minute-by-minute entries. Market service.

The action options are Strong Buy, Buy, Hold, Take Profit, Sell, and Strong Sell. Four typed questions assess action, social mood, squeeze/bounce risk, and catalyst significance. TypeSafe’s documentation describes Jev as returning structured judgments from supplied state; that is different from independently verifying the news in a tweet. Decision service, TypeSafe introduction.

2. Architecture and main components

Verified architecture:

Browser: Jinja-rendered HTML + local CSS + plain JavaScript
    | POST /api/v1/analyze {symbol, sample_size}
FastAPI / Uvicorn
    | concurrently
    +-- CCXT --> Kraken spot + Kraken Futures
    +-- HTTPX --> TwitterAPI.io --> local SQLite + tweet cache
    | then
Python statistics --> representative tweets + market state
    |
TypeSafe SDK --> Jev evaluation, or rule-based fallback
    |
JSON --> decision card, statistics, tweet explorer

Component	Role and important implementation detail
app/main.py	Serves /, /static, /health; mounts the API under /api; configures CORS. Source
app/api/v1/analyze.py	Validates symbols and sample counts; orchestrates services; exposes /api/v1/analyze, /api/v1/market/{symbol}, and settings endpoints. Source
app/core/config.py	Reads environment variables and a root .env using Pydantic Settings. Source
app/services/market_service.py	Hardcodes Kraken spot SYMBOL/USD, 48 one-hour candles and RSI-14, plus Kraken Futures SYMBOL/USD:USD. Market cache lasts 60 seconds. Source
app/services/twitter_service.py	Searches English posts, excludes retweets, requires at least two likes, paginates newest-first, stops on a stored ID, and fills from history. Source
app/core/database.py	Creates app/data/market_intel.db automatically; stores tweets and orders history by tweet timestamp. This is not root data/market_intel.db as implied by the README. Source
app/services/stats_service.py	Counts fear/greed keywords, author diversity and engagement; selects up to 25 highly engaged plus 25 newest posts, deduplicated. Source
app/services/typesafe_service.py	Calls AsyncTypeSafeClient.system_one; converts answers into a card using Python formulas and templated rationale. Source
Templates, CSS, JavaScript	Single browser interface; no Node/npm build. Google Fonts are fetched externally. Candle data exists in the API, but the reviewed interface does not render a candle chart. Template, controller

Inference: One Uvicorn process and SQLite are a reasonable simple layout for a single local user. Multiple workers would have separate in-memory caches and could repeat paid requests; this guide therefore uses one worker. Cache implementation, orchestration.

3. Prerequisites and environment

1. Install Git and Python 3.12, including pip and virtual-environment support. This follows the repository’s Python 3.12-or-higher recommendation and matches the Python 3.12.3 environment used in this review. Newer Python versions were not tested. Repository setup.
2. Use a modern browser and a writable local folder. SQLite comes through Python’s standard library; no separate database server is needed. Database imports.
3. For real social data, obtain your own TwitterAPI.io key and sufficient account credits. It is a third-party provider, not X’s official API. Provider pricing.
4. For Jev evaluation, obtain your own TypeSafe API key through its console, as described in the official quick start. Verify your account’s model access and billing there.
5. Allow outbound HTTPS to the two providers and Kraken endpoints. No exchange trading key, wallet, or broker password is used by the reviewed market service. Market, Twitter, TypeSafe.

Unverified: No account credentials were supplied, so paid API authentication, account restrictions, actual billing and live Jev output were not tested. You can preview the interface without keys, but simulated posts and rule-based decisions must not be confused with live analysis.

4. Installation and configuration, step by step

These commands are for your own new working copy. They describe creating its configuration; this report assignment did not create an .env file.

Step 1 — Download the reviewed version

Run in a terminal in the folder where you want the app:

git clone https://github.com/brainstormity/Jev-X-Sentiment-Analysis.git
cd Jev-X-Sentiment-Analysis
git checkout 7247424bb7f863d011323689692941dc58699eea

The checkout pins the code reviewed here. Fetching a later main may change behavior. Preserve LICENSE when copying or distributing the code; the repository uses MIT licensing. License.

Step 2 — Create an isolated Python environment

macOS/Linux:

python3.12 --version
python3.12 -m venv venv
source venv/bin/activate
python -m pip install -r requirements.txt
python -m pip check

Windows Command Prompt:

py -3.12 --version
py -3.12 -m venv venv
venv\Scripts\activate.bat
python -m pip install -r requirements.txt
python -m pip check

If your Python 3.12 executable has a different name, use that executable for the first two commands. If Linux reports that venv is missing, install your distribution’s Python 3.12 virtual-environment package first.

Verified: Dependencies include FastAPI, Uvicorn, CCXT, HTTPX, Jinja2, Pydantic Settings, TypeSafe SDK and pytest. They use minimum versions, not an exact lock file. Requirements. Recommendation: After successfully checking your installation, save the resolved versions:

python -m pip freeze > requirements.personal.lock.txt

On a later rebuild, install that file instead of resolving new versions. This captures package versions, not the external services or changing AI model. It is not an offline bundle.

Step 3 — Set your keys and application options

Using a text editor, create .env in the repository root, alongside requirements.txt. Insert the following, replacing the two angle-bracketed descriptions with your own real keys; do not leave those descriptions in the file:

TYPESAFE_API_KEY=<your actual TypeSafe key>
TWITTER_API_KEY=<your actual TwitterAPI.io key>
CACHE_TTL_SECONDS=600
REQUEST_TIMEOUT=20
ALLOWED_ORIGINS=http://localhost:8000,http://127.0.0.1:8000

Keep this file private and outside version control and shared screenshots. Environment variables already set in your terminal can override .env values; remove an obsolete shell value if changing the file has no effect. Restart the server after editing configuration. Settings loader, Pydantic Settings documentation.

Alternatively, the settings modal accepts keys and writes them to the root .env. It updates service keys immediately, but does not clear cached tweets. Its validation allows only 8–128 characters consisting of letters, digits, underscore, hyphen or dot; a valid vendor key outside that format would need direct configuration. Empty modal fields do not remove saved keys. Settings endpoint, controller.

Recommendation: Configure keys before the first analysis. If you have already used no-key demo mode, stop the server, move app/data/market_intel.db to a separate backup name, configure real keys, and restart. The code saves simulated posts in the same database as real posts and can later refill a live query from that history. Merely adding a key does not clean it. Moving the database loses the old cache savings but leaves a recoverable backup. Tweet ingestion, database.

Step 4 — Start a local-only server

From the repository root with the virtual environment active:

python -m uvicorn app.main:app --host 127.0.0.1 --port 8000

Open http://127.0.0.1:8000. Keep the terminal running. Use Ctrl+C to stop it. --reload is optional for development and unnecessary for daily operation.

Verified: App settings named HOST and PORT are not wired into a server launcher in the reviewed files. Use the command-line options above to choose the actual listening address and port. DEFAULT_EXCHANGE=binance also does not change the hardcoded Kraken clients. Configuration, entry point, market service.

Recommendation: Keep the explicit loopback bind. Analysis endpoints have no login or rate limit, and ADMIN_TOKEN protects only settings changes from nonlocal clients. CORS is not general authentication. A reverse proxy connecting locally could also satisfy the settings endpoint’s localhost check. Public hosting needs additional access controls and is outside this replication guide. API security logic.

Step 5 — Check startup and real-data status

1. Visit http://127.0.0.1:8000/health. Expect status: healthy and both configured flags true when keys are present. Those flags show presence, not successful authentication. Health endpoint.
2. Enter BTC, select 100 tweets, and click Analyze Asset. The browser’s developer tools → Network → /api/v1/analyze → Response lets you inspect the JSON without installing another tool.
3. Confirm market.is_fallback is false, is_twitter_mock is false and is_typesafe_mock is false. Check social_stats.sample_size and tweet timestamp_epoch values. A nonmock Twitter flag alone does not prove a successful fresh fetch: errors can return old database rows or an empty sample with that flag false. Compare the market price with your exchange and check the server logs. API response, tweet error handling.
4. When market.has_perpetuals is false or funding/open interest is null, treat derivatives as unavailable. Spot data can still be real. Market service.
5. Run python -m pytest -v as an additional smoke check, preferably in a separate demo copy with keys absent. Tests create a database and may contact Kraken; with keys present they can call paid providers. Passing tests does not establish live data quality. Pipeline tests, dedup tests.

Verified UI limitation: The top connection badges are driven by key presence. The controller does not render the Twitter/TypeSafe mock flags. Market fallback is handled more visibly: the UI shows a warning, suppresses unavailable prices and trade levels, and blocks copying the ticket. Nevertheless, the backend still calculates a decision from synthetic market data. Template, controller, decision service.

Troubleshooting

Symptom	What to check
No module named ...	Activate the project virtual environment and rerun python -m pip install -r requirements.txt; use python -m uvicorn so the same interpreter starts the app.
Browser cannot connect	Keep the server terminal open, read startup errors, and use the port specified in the launch command. If 8000 is occupied, use another port and update origin settings.
UI opens but prices are unavailable	Inspect market.is_fallback and server logs; check outbound access and whether the symbol has a Kraken USD market. The fallback is not a usable substitute quote. Source
Configured badges but simulated decision or no posts	Inspect response mock flags and logs; verify real keys, account credits and access. Restart after editing configuration. Health, services, decision
Repeated old posts after adding a key	Restart to clear memory cache; isolate the database created in demo mode as described above. Source
Fewer tweets than requested	Check actual sample size, provider errors and the pagination cap; do not assume the slider value was fulfilled. Source
Permission error involving SQLite	The process must be able to create and write app/data/market_intel.db. Run from a folder owned by your user. Source

5. Daily operation for one trader

Recommended routine, based on the verified on-demand behavior:

1. Before your session, open the project folder, activate venv, and run the same Uvicorn command. Open the local browser address and verify provider status using the checks above.
2. Start with an exchange-supported symbol, such as BTC. Support depends on Kraken’s USD spot markets and separate futures coverage; arbitrary valid symbols may produce fallback data. Use 50 or 100 tweets for an initial pulse, increasing the requested sample when you need more narrative context. This is a workflow suggestion, not evidence that those counts predict returns. Market, analysis.
3. Read price, 24-hour change, RSI and available funding/open interest together. Inspect actual sample count, author diversity and the displayed posts. Verify important catalyst claims independently before treating them as news.
4. Review the action and levels alongside your own execution venue’s chart, spread, fees and position plan. The app has no knowledge of your holdings or whether you already have profit to take. Exchange links and the copy button help manual execution; they do not submit orders. Decision inputs, browser actions.
5. To refresh, click Analyze again. The market may be up to 60 seconds cached; tweets are cached for 600 seconds by default for the same symbol and sample count. Refreshing the browser does not bypass server caches. Changing sample count creates a different tweet-cache key and may incur extra calls. Each analysis still evaluates Jev when a TypeSafe key is configured. Cache, Twitter, orchestration.
6. Record your own timestamp, data mode, decision and outcome if you want a trading journal. The existing database stores tweets, not an analysis or trade history. At session end, stop the server; backing up app/data/market_intel.db preserves tweet history. Database schema.

Costs and freshness

Verified current provider claim: TwitterAPI.io advertises $0.15 per 1,000 returned tweets, with a $0.00015 minimum per API call. At that base rate, 100 returned tweets cost about $0.015 before other charges or discounts. This is provider pricing checked on the research date, not a billing test. Pricing.

Inference from code: Paid pages may contain posts beyond the requested count, and already-known posts still arrive in a paid response before early stopping. Thus, cost cannot be calculated reliably from the displayed sample count alone. Cached tweets can save social fetches, but there is no whole-analysis cache: the README’s zero-cost repeated-search statement is too broad when TypeSafe is called again. Its TypeSafe cost estimate was not independently verified. Check actual usage in both dashboards. Twitter paging, analysis orchestration, README claim.

6. Customization options

These are optional; keep the original copy working before changing code.

Change	Where and how	Effect or caution
Social freshness	Set CACHE_TTL_SECONDS in .env, then restart.	Lower values refresh more often but cost more. This does not limit the age of stored tweets or change the hardcoded 60-second market cache. configuration, tweets, market
Market timeframe	Edit fetch_ohlcv(... timeframe="1h", limit=48) in market_service.py.	An intraday timeframe changes RSI meaning; use a supported exchange interval and recheck strategy behavior. There is no timeframe control in the UI. Source
Query/asset names	Edit _build_query and its symbol-name mapping in twitter_service.py.	Can improve ambiguous symbols or broaden language coverage. If changing query meaning, separate/reset stored history and cache to avoid mixing samples. Source
Sentiment vocabulary	Edit FEAR_KEYWORDS, GREED_KEYWORDS and thresholds in stats_service.py.	Current matching is simple token intersection; punctuation, negation and sarcasm can distort scores. Source
Decision behavior	Edit typed questions, fallback rules, or level multipliers in typesafe_service.py.	These are strategy changes; verify with recorded examples before using them. No built-in backtester exists in the reviewed app. Source
Look and quick symbols	Edit index.html, style.css, and app.js.	Change colors, symbol chips, labels or links without a frontend build. Correct USD/USDT labels if your execution venue differs. Template, controller
Port	Change --port in the launch command and allowed origin URLs if needed.	Keep --host 127.0.0.1 for personal local use. Entry point, configuration

Recommended additions, not existing features: Show response data-mode flags, tweet age ranges and requested-versus-actual count prominently; reject analysis on synthetic market data; add a maximum social-data age and a journal. These address gaps visible in the present response and persistence logic. Analysis, Twitter, database.

7. Limitations, discrepancies and open questions

Verified limitations and their implications

• Synthetic fallback can look plausible. Kraken errors return fixed sample prices and artificial candles. Missing Twitter keys generate posts; missing/failed TypeSafe calls use deterministic rules with preset confidence values. Never use those results as live market evidence. Market, Twitter, decision.
• Large samples are not guaranteed. Social paging is capped at 35 calls. The provider documents up to 20 results per page. Inference: A fresh 1,000-post request can therefore retrieve at most about 700 under that documented page size, before filtering or other failures, unless existing history fills the rest. The API does not expose the service’s yield_deficit or paging diagnostics in its final response; inspect actual sample count. Tweet service, analysis response, provider endpoint.
• No guaranteed intraday social window. Queries have no start/end time restriction, and old stored posts can fill the sample. Stopping at the first known ID assumes older results are already covered, which need not hold after a previously shallow fetch. Stored engagement counts are not updated because inserts ignore existing IDs. Twitter, database.
• README metric claims exceed implementation. Statistics calculate (likes + 2 × retweets) / sample_count, not engagement per minute. Author diversity is a ratio, not a verified bot detector. Open interest is a single snapshot estimate, not an open-interest delta. Statistics, market service, README.
• Trade levels are fixed formulas. For Buy/Strong Buy, entry is 99.5–100.2% of price, stop is 96.2%, and targets are 104.5% and 108.5%; Sell variants mirror directional percentage rules. They are not derived from chart support, volatility, liquidity, account balance or position size. Two-decimal rounding is also unsuitable for sufficiently small-priced assets. Decision builder.
• Confidence is not a proven win rate. The code normalizes action values and manufactures a remainder distribution if insufficient probabilities exist; fallback values are hand-set. No trading performance calibration was established in this review. A displayed 80% does not establish an 80% chance of a profitable trade. Decision builder.
• Market labels and derivatives need care. Data is Kraken USD, while the UI and copied ticket label assets USDT and some exchange links use USDT. Funding is multiplied by 100 without displaying an interval. Open interest is read from the exchange-specific payload and multiplied by spot price; its units and interpretation were not independently validated for every contract. Market, controller.
• Persistence is imperfect across assets. Tweet ID alone is the SQLite primary key, although records also carry a symbol. Inference: A post mentioning multiple assets can be stored for only one symbol and omitted from another symbol’s later history. No automatic history retention cleanup appears in the database implementation. Schema.
• External dependencies remain. Live operation needs internet and paid-service availability. Google Fonts may fail offline. Exact dependency versions, exchange support and the SDK’s default jev-latest model can change; locking Python packages cannot freeze live behavior. Requirements, template, TypeSafe quick start.

Unanswered questions for a real deployment

Your own provider accounts must establish current TypeSafe price, quotas, model entitlement and key validity. Live testing must establish Kraken availability from your location, supported contracts, funding interval and open-interest units. Neither repository text nor the local checks establishes trading profitability, reliable catalyst verification, or suitability for a particular risk plan. These unknowns do not block reproducing the interface, but they remain before relying on its output during a session.

8. What this review checked

Source files were downloaded from the pinned commit into disposable scratch space and read directly, including all Python services, API/config/database files, frontend files, requirements and tests. The installation and test outcomes below are author-run checks, not independent certification. No real API credentials were used. See verification notes for the recorded environment, outcomes and scope.

The guide deliberately corrects README descriptions where source behavior differs. Provider documentation was checked for current search pagination, public pricing and TypeSafe usage. No historical backtest, funded trade, authenticated provider request or full browser automation was performed.