> Initializing Session...
Veltrix
Autonomous Run • Python • Gemini API
Description
Every post ships through an adversarial pipeline before it goes live: Gemini drafts the topic and caption, then Groq and Cerebras — two independent models — must both sign off before it's trusted. A statistically-adaptive embedding check catches duplicate topics without a hardcoded similarity cutoff, and a self-expiring checkpoint file carries each post across two separate GitHub Actions runners so it can sit for a 30-minute human review window before auto-publishing. Branded slides render through Jinja2 + headless Playwright at full carousel resolution.
Timeline
10 Days
Role
Solo developer
Status
Production
Year
2026
Deployment
2 posts / day (auto)
Core Stack
Python / Playwright
Why I Built It
Understanding the core problems, proposed solutions, and realized product achievements.
Running a growth Instagram account solo means someone has to write, fact-check, design, and publish twice a day, forever — and the one time a hallucinated stat or a shadowban-trigger phrase slips through, reach tanks for weeks.
GitHub Actions cron fires at 18:00 IST — a brand-new, stateless runner boots with zero memory of the last run.
auto_post.py checks pipeline_checkpoint.json first, in case a post from the last run is still sitting in review.
No pending checkpoint found. config.json's WEEKLY_SCHEDULE resolves today's evening slot to CAROUSEL_FLOW; content_generator.py drafts a topic and caption with Gemini.
The topic's embedding is compared against the last 30 days via cosine similarity — adaptive_thresholds() computes today's duplicate cutoff from the mean and standard deviation of recent similarity pairs, not a fixed number.
Similarity lands between the low and high threshold — the ambiguous middle band Vurlo-style fixed cutoffs can't resolve.
is_semantic_duplicate_llm() breaks the tie: not a duplicate. Pipeline proceeds.
verify_text_content() sends the caption to Groq and Cerebras independently — both must return caption_ok AND facts_ok, or the whole caption is rejected.
Both approve. Jinja2 renders the slide templates; Playwright screenshots them at 1080x1350, 2x scale, after waiting on networkidle plus a settle buffer for Google Fonts.
save_checkpoint() base64-encodes the slide images into pipeline_checkpoint.json with status: pending_review and a timestamp. The runner exits — the container is destroyed.
30 minutes later, the next cron tick's load_checkpoint() finds the same checkpoint, sees age_hours >= 0.5, and auto-approves — publishing through the Instagram Graph API and deleting the checkpoint.
Persist state across two runners that never coexist
database.pysave_checkpoint()/load_checkpoint() serialize the topic, caption, and base64-encoded media bytes to a local pipeline_checkpoint.json, since nothing in memory survives a GitHub Actions job ending.
Score duplicates against a moving baseline, not a fixed cutoff
database.pyadaptive_thresholds() derives low/high similarity cutoffs each run from μ + σ and μ + 1.5σ of the recent embedding pairs (capped at 0.78 / 0.88), so the bar shifts with how similar the account's own recent output has actually been.
Never let one model grade its own homework
text_auditor.pyverify_text_content() routes the caption to Groq (llama-3.3-70b-versatile) and Cerebras (gpt-oss-120b) independently — different vendors, different base models — and ANDs their decisions together.
Force a human decision point before anything goes live
auto_post.pyA generated post sits at status: pending_review for a 30-minute window on the dashboard; the next cron tick or a manual --action=approve/reject decides its fate.
Every post clears two independent auditors and a statistically-adaptive duplicate filter before it's even eligible to publish, and the whole two-post day — drafting, auditing, rendering, and shipping — runs for roughly $0.0002 without a manual click when nobody intervenes.
- Inference cost / post
- ~$0.0002
- Independent audits required
- 2 of 2
- Human review window
- 30 min
- Output formats
- 4 (photo/carousel/reel/listicle)
Architecture Pipelines
Visual system flow diagrams representing data pipelines and structured checks.
GitHub Actions cron → auto_post.py
fires at fixed IST slot hours and resolves the day's format (photo/carousel/reel/listicle) from config.json's WEEKLY_SCHEDULE map, keyed by weekday and slot instead of one fixed daily template.
database.py — save_checkpoint() / load_checkpoint()
the only state that survives between two entirely separate ephemeral runners — serializes topic, caption, and base64-encoded media to pipeline_checkpoint.json, self-expiring after 24 hours.
content_generator.py
drafts a topic and caption using Gemini, pulling from a weighted voice pool (Punchy, Listicle, Storytelling, Question-Hook, Stat-Led) so back-to-back posts don't read like the same template.
database.py — cosine_similarity() / adaptive_thresholds()
a three-tier duplicate filter: fast-reject below a statistically adaptive low threshold, fast-flag above a high threshold, and only the ambiguous middle band falls through to an LLM tiebreaker.
text_auditor.py — verify_text_content()
local regex/heuristic pre-checks (emoji density, disclaimer placement, shadowban phrase patterns) reject for free before any API call, then Groq and Cerebras independently audit whatever survives.
listicle_pipeline.py — render_pages()
fills Jinja2 HTML templates with the approved copy, then screenshots them via headless Playwright Chromium at 1080x1350 / 2x device scale, waiting on networkidle plus a fixed settle buffer for web fonts.
instagram_publisher.py / threads_publisher.py
publishes the approved asset set through the Instagram Graph API and cross-posts the same content to Threads, sitting behind the 30-minute review gate rather than firing immediately.
database.py — update_dashboard() → dashboard.html
renders a static control panel showing the pending-review card with Approve/Reject buttons wired to a GitHub workflow_dispatch, plus live per-post API cost telemetry from APITracker.
Features & Capabilities
Key features and built-in components implemented inside the codebase.
- ✓Zero-touch daily publishing — a GitHub Actions cron resolves each day's format from a weekly schedule map instead of posting the same content type every day.
- ✓Adversarial fact-checking before anything ships — every caption is drafted by Gemini, then independently audited by Groq and Cerebras, with both providers required to agree before it's approved.
- ✓Statistically-adaptive duplicate detection — cosine similarity against the account's post history, scored against thresholds recomputed each run from the mean and standard deviation of recent embedding pairs, not one fixed cutoff.
- ✓Free local pre-screening before any API spend — regex and heuristic checks (emoji count, disclaimer placement, banned-phrase patterns) reject risky captions before a single audit call is made.
- ✓State that survives an ephemeral runner dying mid-post — a self-expiring JSON checkpoint carries topic, caption, and base64-encoded media across two separate GitHub Actions invocations.
- ✓Built-in human veto window — every generated post sits for 30 minutes as pending_review on a live dashboard before auto-publishing, with one-click approve/reject wired to a GitHub workflow.
- ✓Headless-render pipeline for branded slides — Jinja2 templates screenshot through Playwright Chromium at 1080x1350, 2x scale, with explicit waits so slides don't ship mid-font-swap.
- ✓Perceptual duplicate guards for media, separate from text — dhash/pHash image comparisons stop the same visual from posting twice, independent of the caption-level embedding check.
- ✓Cross-platform publishing from one pipeline — the same approved asset set republishes to Threads without regenerating any content.
- ✓Per-run cost telemetry — an APITracker tallies Gemini token costs and per-provider fallback usage straight into the dashboard, so spend is visible per post, not just in aggregate.
Solving Complex Bottlenecks
A deep dive into security rule architectures, race conditions, and verification solutions.
auto_post.py runs as a brand-new GitHub Actions job every invocation — no memory, no disk, no in-process variables carry over between the run that drafts a post and the run 30 minutes later that's supposed to publish it.
A GitHub Actions runner is torn down completely when the job ends. Adding a human review window between generation and publish meant handing a fully-generated post — including binary image and video bytes — from one ephemeral container to a container that didn't exist yet.
Base64-encode every binary asset — image bytes, video slide frames — into the checkpoint JSON, not just text fields
auto_post.pyStamp every checkpoint with an ISO timestamp and self-expire it after 24 hours
database.pyCheck checkpoint.status === 'pending_review' before drafting anything new, so a cron tick during the review window can't generate a second, competing post
"Idempotency isn't optional on ephemeral infrastructure — it's the only way a stateless scheduler can approximate a stateful workflow. The checkpoint file is effectively the pipeline's entire call stack, frozen and reloaded by whichever runner picks it up next."
Development Journey
A chronological day-by-day log detailing core milestones and features added.
Core Pipeline & LLM Hooks
content_generator.py drafting flow wired to Gemini; config.json's weekly schedule map and voice pool established.
Dual-Brain Auditor
text_auditor.py built out — local heuristic pre-checks, then independent Groq and Cerebras audit calls, AND-ed together.
Adaptive Duplicate Detection
Embedding cache and adaptive_thresholds() written in database.py, replacing an earlier fixed-cutoff version that kept misfiring.
Playwright + Jinja2 Render Pipeline
listicle_pipeline.py template rendering and headless screenshot capture stood up; chased down the font-loading race in CI.
Checkpoint & Review Gate
save_checkpoint()/load_checkpoint() shipped in database.py; auto_post.py wired to the 30-minute pending_review window and dashboard approve/reject actions.
Publishing & Dashboard
instagram_publisher.py and threads_publisher.py cross-posting wired up; dashboard.html control panel and APITracker cost telemetry finished before enabling the cron.
Operational Metrics
No public-facing site to audit — these are the safeguards that keep an unattended pipeline honest.
Integrates content channels, competitor scrapers, database logs, alerting systems, and deployment APIs
Paid Gemini API invoked ONLY after the free/low-cost Llama audits approve the draft
Audits chain dynamically from Groq ➡️ Cerebras ➡️ OpenRouter ➡️ Raw Gemini to avoid blockages
Fails back from SiliconFlow (Flux/SD3) ➡️ Hugging Face ➡️ Gemini internal image generator
self-expires so a stuck runner never resurrects a stale, half-finished post
embedding similarity ➡️ adaptive threshold band ➡️ LLM tiebreaker for the ambiguous zone
Trade-off Explanations
Concise rationales for technology selections and future roadmaps.
One Provider for Both Drafting and Embeddings
Gemini 2.5 Flash + gemini-embedding-2Gemini writes the initial topic/caption and also generates the embedding vectors used for duplicate detection — keeping the 'creative' half of the pipeline on one low-cost, low-latency provider.
Independent Adversarial Audit, Not a Second Opinion From the Same Vendor
Groq + Cerebrasverify_text_content() requires both providers — running different base models (llama-3.3-70b-versatile, gpt-oss-120b) — to independently approve a caption, so a shared blind spot in one model family can't rubber-stamp a mistake.
Headless Card Generation
Playwright + Jinja2Branded listicle slides are real HTML/CSS templates screenshotted at 1080x1350, 2x scale — layout, typography, and responsive-style rules come for free instead of hand-positioning text on a canvas.
Zero-Infra State for a Scheduler With No Server
Local JSON checkpoint + SQLiteNo process stays alive between runs. pipeline_checkpoint.json and veltrix.db are the entire state layer, both just files the workflow commits back to the repo — no database server to provision or pay for.
Free Scheduler That Doubles as the Approval Queue
GitHub Actions cron + workflow_dispatchThe same GitHub Actions infra that runs the cron also handles the manual approve/reject action for the human review gate, so there's no separate approval service or webhook receiver to host.
"Evaluating scaling adjustments and cache controls shows true engineering maturity."
- ✓Move the checkpoint's binary asset payload out of a committed JSON file and into object storage (Supabase/Cloudinary) — base64-encoding video frames into the checkpoint bloats the repo's history over time.
- ✓Cache Groq/Cerebras audit responses so a topic that gets re-evaluated after a checkpoint recovery doesn't burn two more audit calls for content that's already been reviewed.
- ✓Extend perceptual image-hash duplicate checking to Reel source frames, not just PHOTO/CAROUSEL stills — a remade Reel can currently reuse near-identical frames undetected.
- ✓Replace the fixed 1.5s Playwright settle buffer with an actual document.fonts.ready wait inside the page — it works today, but it's a guess dressed up as a timeout.
Visual Gallery
Scrollable preview tracks showcasing panel responsive structures.
Finished exploring this session?
End the workspace session to release resources and return back to the primary portfolio index.