24/7 autonomous AI meme-token signal engine — X/Twitter scan → DexScreener live data → Telegram signals with charts → self-improving local LLM.

🧠 OpenSignalAI — 24/7 AI Meme Token Signal Engine

AI agent jo har 5 min Twitter (X) meme lists + searches + 12 market APIs se fresh meme tokens hunt karta hai, poora trading analysis karke Telegram pe signal report + charts + token cards bhejta hai. Fully self-healing — retry, alerts, health check, auto-recovery ke saath 24/7 chalta hai. Self-improving: har signal ka data finetuned AI model ko seekhata hai (nightly LoRA retrain), model vs engine verdict compare + blend, aur specialist AI agents (Risk Officer, Report Writer).

📚 Docs

| Doc | Kya hai | |-----|---------| | 🌐 Project Website | GitHub Pages landing page — hero, features, live dashboard demo, pipeline, docs | | ARCHITECTURE.md | 🏗️ Poori system ki architecture — jobs, data flow, finetune loop, costs (naye aadmi yahan se shuru karo) | | DEPLOYMENT.md | 🚀 5-minute quickstart — fork → clone → config → live (naye users yahan se shuru karo) | | CONTRIBUTING.md | 🤝 Dev guide — structure, conventions, testing, agent/data-source add karna, PR workflow |

📸 Screenshots

| Web Dashboard | Telegram Report | |---|---| | | (live engine ke saath real screenshots auto-update — Telegram pe report, charts, token cards) |

🎬 Motion-graphics video pipeline bhi hai (Remotion + Hindi voiceover) — har scan ka breaking-news analytics video.

📦 Components

| File | Kaam | |------|------| | meme-signal.sh | Main engine — scan, analysis, scoring, Telegram report, charts, health, alerts, cron-ready | | sources.py | Multi-source discovery — DexScreener profiles/boosts, GeckoTerminal trending, Pump.fun, CoinGecko (+ Birdeye/GMGN/CMC optional keys) | | chart_render.py | DexScreener-style chart PNG renderer (PIL) — price line, 24h high/low, signal entry point, buy/sell badge | | multi-channel-scan.sh | Multi-channel (Telegram/LinkedIn etc.) scan pipeline | | combined-trending.sh | Twitter lists ka combined trending extraction (parallel mode) | | extract-lists.sh / extract-loop.sh | List IDs extraction utilities | | research-scan.sh | Research/deep-dive scanning | | config/mcporter.json | LinkedIn MCP config | | .agent-reach/twitter-lists.yaml | Twitter lists registry (meme/solana/CT lists) | | video/ | 🎬 Motion-graphics video pipeline (Remotion + Edge-TTS + ffmpeg) | | dashboard/ | 🖥️ Web dashboard (Flask) — live signals, charts, latest video, health — http://127.0.0.1:8787 | | deploy.sh | Repo → live deploy (real copies, macOS TCC fix) | | cli/ + package.json | npm CLI (opensignalai) — colorful setup wizard + live terminal dashboard | | launchd/ | LaunchAgent plists — 24/7 scheduling (cron se better) |

⚙️ Setup — One-Line Install

npm (sabse aasan — colorful wizard + live dashboard):

npx opensignalai          # 🦊 interactive wizard — token + API keys prompts
opensignalai dashboard    # 📊 live terminal dashboard (signals, jobs, caches)
opensignalai scan         # 📡 ek scan abhi (Telegram report)

Ya direct installer (koi Node nahi chahiye):

curl -fsSL https://raw.githubusercontent.com/ChiranjibAI/OpenSignalAI/main/install.sh \
  -o /tmp/osi.sh && bash /tmp/osi.sh "<TG_BOT_TOKEN>" "<TG_CHAT_ID>"

Full manual setup: DEPLOYMENT.md

1. Config: .agent-reach/telegram.env.example copy karo telegram.env me (repo me secrets kabhi nahi):

cp .agent-reach/telegram.env.example .agent-reach/telegram.env
# phir apna TG_BOT_TOKEN, TG_CHAT_ID, GROQ_API_KEY daalo

2. Dependencies (kisi bhi OS pe):

   • opencli (browser-based X scraping, optional) — ~/.local/bin
   • Python 3.11+ + PyYAML + Pillow + Flask
   • ffmpeg (charts/video ke liye, optional)

3. Run:

bash meme-signal.sh            # scan + Telegram report
bash meme-signal.sh --print    # scan, sirf print (koi send nahi)
bash meme-signal.sh --test     # Telegram test message
bash meme-signal.sh --daily    # daily dashboard + charts (har coin ka chart + token card)
bash meme-signal.sh --health   # engine health report (API pings + verdict)
bash meme-signal.sh --health --check  # health sirf check (recovery ke bina)

🎬 Video Pipeline (Remotion + Voiceover)

Har scan se banger vertical video — breaking-news intro + animated token analytics cards + verdict + outro, Hindi voiceover (Edge-TTS) ke saath. 1080x1920 (reels/TikTok ready).

cd video
bash render_video.sh            # live data -> video (koi send nahi)
bash render_video.sh --send     # + Telegram sendVideo
bash render_video.sh --demo     # existing data.json se (fetch skip)

| File | Kaam | |------|------| | video/src/Root.tsx + scenes/ | Remotion compositions (BreakingNews, TokenCard, Outro) — animated, dark theme | | video/make_video_data.py | Live signal-state + DexScreener -> src/data.json (price/MC/liq/vol/buy-sell/chartPoints) | | video/tts.py | Edge-TTS Hindi voiceover (hi-IN-SwaraNeural) — scene durations audio ke hisaab se auto-set | | video/render_video.sh | End-to-end: data -> TTS -> Remotion render (retry+random port) -> ffmpeg voiceover mix -> Telegram |

Dependencies: npx remotion (node_modules in repo), edge-tts (pip), ffmpeg.

🔬 30-min scaling plan (segment render + concat)

Remotion 30 min (~54000 frames) ek saath render karna memory-heavy hai. Segment approach (scalable, resume-friendly):

1. Token scenes alag-alag render karo (1 token = 1 video segment ~30s)
   npx remotion render src/index.ts TokenScene out/seg_1.mp4 --props='{"token":0}'
2. Intro + Outro alag render (60s total)
3. ffmpeg concat: intro.mp4 + seg_1.mp4 + ... + seg_N.mp4 + outro.mp4
   (same codec/CRF/dimensions — concat demuxer se lossless join)
4. Voiceover already per-scene hai (out/tts/scene_N.mp3) — concat ke baad mix
5. Render failures pe sirf wo segment retry (pura video nahi)

Ye system 5 tokens ≈ 3 min me render karta hai; 100 tokens ≈ 50 min segments me (Mac mini pe background render + Telegram share).

🖥️ Dashboard (Web)

Jo Telegram pe jaata hai wahi web pe — live signals + charts + latest video + engine health. LaunchAgent se 24/7 chalta hai (dashboard khud restart hota hai).

cd dashboard && bash run.sh     # start (ya LaunchAgent se auto)
# → http://127.0.0.1:8787  (har 60s auto-refresh)
# LAN/phone: http://192.168.1.2:8787  (same WiFi)

Token auth: LaunchAgent me DASH_TOKEN set hai — phone pe pehli baar http://<MAC-IP>:8787/?token=<DASH_TOKEN> kholo (session cookie save hota hai), fir bina token bhi chalega. Token /tmp/meme_signal/dash_token.txt me saved. DASH_TOKEN empty ho to auth off (sirf trusted LAN pe).

🔔 Push Notifications (Web Push)

Dashboard me "🔔 Enable Alerts" — naya signal aate hi phone pe notification (Web Push API, VAPID keys, free — koi server nahi chahiye).

cd dashboard
python3.11 push.py key    # VAPID keys generate (pehli baar auto)
python3.11 push.py test   # test notification (subscribed device pe)

| Cheez | Detail | |-------|--------| | static/sw.js | Service worker — push event → notification, click → dashboard | | push.py | VAPID keys + subscription store (~/.meme-signal/vapid.json, push_subs.json) + send | | Monitor thread | Har 30s signal-memory.json check — naya signal → sabko push (🚨 NAYA SIGNAL: $TOKEN) | | Endpoints | /api/push/vapid · /api/push/subscribe · /api/push/test · /api/push/status |

Note: Push sirf real browser me kaam karta hai (phone Chrome/Safari, desktop Chrome). Embedded/headless browsers me "push service not available" milega — code nahi, browser ki limit.

🌐 HTTPS Tunnel (phone push ke liye zaroori)

Web Push HTTPS maangta hai (localhost chhod kar). Phone pe LAN http://192.168.1.2 se push FAIL hoga — isliye cloudflared quick tunnel:

brew install cloudflared
# LaunchAgent: com.memeagent.tunnel (cloudflared tunnel --url http://127.0.0.1:8787)
# URL: grep trycloudflare /tmp/meme_signal/tunnel.log

Phone pe: https://<tunnel-url>/?token=<DASH_TOKEN> → 🔔 Enable Alerts → Allow. Subscribe hote hi turant "✅ Alerts ENABLED" push aata hai (auto-confirm).

| File | Kaam | |------|------| | dashboard/app.py | Flask app — pages + JSON APIs (/api/overview, /chart/<tok>.png, /video/latest.mp4) | | dashboard/data.py | Data layer — signal-state, DexScreener live, history, health (cron.log parse), charts | | dashboard/static/ | Dark UI (token cards, badges, video player, health panel) | | com.memeagent.dashboard.plist | LaunchAgent — KeepAlive, boot pe auto-start |

⏰ Scheduling — cross-platform (har OS pe 24/7)

macOS pe LaunchAgents (TCC-safe, auto-restart); Linux/Ubuntu pe systemd user service (no root, reboot-safe); Windows pe native — windows/install_windows.ps1 (PowerShell, Task Scheduler auto-start, no Git Bash); Termux pe nohup daemon — sab ek hi job set chalate hain (scheduler.py, launchd/*.plist ke mirror):

bash deploy.sh   # repo edit ke baad — live files update (1 command)

# macOS:
#   com.memeagent.scan       → har 5 min scan (BUY/CAUTION only)
#   com.memeagent.daily      → 7 PM daily dashboard + charts
#   com.memeagent.health     → 9 AM health report
#   com.memeagent.dashboard  → dashboard server (KeepAlive)

# Linux / Termux / Windows (install.sh auto-lagata hai):
bash scheduler.sh status     # daemon chalu hai?
bash scheduler.sh start      # nohup daemon (PID file)
bash scheduler.sh stop
bash scheduler.sh once scan  # ek job abhi chalao

Deploy flow: repo me edit karo → bash deploy.sh → live update.

🏠 Single Source of Truth (Deployment Layout)

Ye repo hi source of truth hai. Live system symlinks se yahi chalata hai (cron Desktop ko TCC block karta hai, isliye symlinks home dir me):

~/Desktop/meme-agent/          ← REPO (source of truth, yahi edit karo)
    meme-signal.sh             ← git-tracked
    chart_render.py            ← git-tracked
    .agent-reach/twitter-lists.yaml   ← git-tracked
    .agent-reach/telegram.env.example ← template (secrets nahi)

~/.meme-signal/                ← LIVE (cron yahan se chalta hai — symlinks)
    meme-signal.sh        -> ~/Desktop/meme-agent/meme-signal.sh
    chart_render.py       -> ~/Desktop/meme-agent/chart_render.py
    .agent-reach/twitter-lists.yaml -> ~/Desktop/meme-agent/.../twitter-lists.yaml
    .agent-reach/telegram.env      ← REAL secrets (gitignored, yahan hi)
    .agent-reach/signal-*.json     ← runtime state (gitignored)

Kaam kaise: repo me edit karo → commit → push. Symlink ki wajah se live system turant naya code chalata hai. telegram.env sirf live folder me hai (kabhi repo me nahi).

🕐 Scheduling (24/7) — LaunchAgent (cron ki jagah)

cp launchd/*.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.memeagent.scan.plist    # har 15 min
launchctl load ~/Library/LaunchAgents/com.memeagent.daily.plist   # 7 PM
launchctl load ~/Library/LaunchAgents/com.memeagent.health.plist  # 9 AM
launchctl load ~/Library/LaunchAgents/com.memeagent.dashboard.plist  # dashboard

🛡️ Security

• telegram.env (bot token + API keys) gitignored — kabhi commit mat karo
• Runtime state (signal-state.json, signal-memory.json, caches) gitignored — auto regenerate
• Scoped tokens use karo, repo private rakho

🔧 Data Sources

Discovery (hunting — sources.py):

• X/Twitter: opencli browser (cookie-based) — lists + searches
• DexScreener (free): token-profiles + token-boosts — naye/boosted tokens
• GeckoTerminal (free): trending pools — solana/base/eth/bsc/arb
• Pump.fun: GMGN Trenches (dedicated, GMGN_API_KEY) + PumpPortal mirror + bonding-curve (…pump address) detection
• CoinGecko (free): trending coins
• Birdeye (optional BIRDEYE_API_KEY): trending + new listings (token_trending + v2/tokens/new_listing)
• GMGN (optional GMGN_API_KEY): OpenAPI trending (openapi.gmgn.ai/v1/market/rank, X-APIKEY header, IPv4-only) — key: gmgn.ai/ai
• CoinMarketCap (optional CMC_API_KEY): trending coins
• Photon: koi public API nahi hai (browser terminal) — isliye integrated nahi; uska data DexScreener/GeckoTerminal se cover hota hai

Market data (live):

• DexScreener: live price/MC/liquidity/volume/txns — all chains, exact token-address lookup (symbol collision-free)
• GeckoTerminal: 24h OHLCV candles (solana/base/eth/bsc/arb)
• RugCheck (rugcheck.xyz/about): solana tokens — score/risks/creator/holders (tool Solana + Fogo chains support karta hai; engine me abhi Solana wired hai)
• Groq (LLM): bull/bear/final deep analysis (free key)
• Telegram Bot API: reports/charts/alerts

Har source independent try hota hai — ek fail ho to baaki chalte hain. X session expire ho jaye tab bhi API sources se signals milte hain.

⚠️ Disclaimer

Meme coins high risk — ye signals sirf research hain, apna research zaroor karo.