GemmaStudio

GemmaStudio is a Meta-safe local content studio for preparing social media publication packages without automating Instagram or Threads.

It helps a creator generate, review, edit, export, and manually publish content while keeping platform-risky actions outside the application.

Preview

Instagram Preview	Threads Preview

Telegram & Workflow	Editor & Assets

Why This Exists

Meta platforms can be strict about automated posting, browser automation, cookies, and fake user behavior. GemmaStudio deliberately avoids those paths. It automates content preparation, not publication.

Safety Boundaries

GemmaStudio does not implement:

• Instagram or Threads auto-posting.
• Meta publishing API calls.
• Browser automation for posting.
• Cookie or session storage.
• Hidden background publishing jobs.
• Real access tokens or API secrets.

Allowed actions:

• Copy generated text to clipboard.
• Open official Instagram and Threads URLs.
• Attach and download local image assets.
• Mark a draft as posted manually after the user publishes outside the app.

Features

• Create deterministic draft packages by topic and content type.
• Edit Telegram text, Threads text, Instagram caption, hashtags, alt text, and hooks.
• Attach, preview, download, and delete local image assets.
• Track manual posting status for Instagram and Threads.
• Track revision decisions with a timestamped Decision Log.
• Use the Asset Manager to review all local images across all drafts.
• View production stats and trends on the Local Analytics dashboard.
• Filter drafts by status, content type, and keyword.
• Seed repeatable demo drafts for quick walkthroughs.
• Export a draft as a safe local zip package.
• Optionally generate content through an env-configured LLM provider.
• Tune LLM prompts with tone, length, audience, and language controls.
• Run local draft quality checks before manual publishing.
• Persist local data with atomic JSON writes.
• Run entirely on the Python standard library.

Quick Start

python app.py

Open:

http://127.0.0.1:8765

Run tests:

python -m unittest discover

No pip install step is required for the MVP.

Optional LLM Generation

Deterministic generation is the default and requires no API keys:

GEMMASTUDIO_GENERATOR=deterministic

To enable LLM generation, configure environment variables or a local ignored .env file:

GEMMASTUDIO_GENERATOR=llm
LLM_PROVIDER=openai
LLM_API_KEY=
LLM_MODEL=
LLM_TIMEOUT_SECONDS=30

Supported provider presets:

• openai -> https://api.openai.com/v1/chat/completions
• groq -> https://api.groq.com/openai/v1/chat/completions
• openrouter -> https://openrouter.ai/api/v1/chat/completions
• custom -> use LLM_API_URL

For a custom endpoint, set:

LLM_PROVIDER=custom
LLM_API_URL=

The endpoint should accept a chat-style JSON request compatible with studio/llm_provider.py.

LLM output is validated before a draft is saved. If the provider fails, returns invalid JSON, or omits required fields, GemmaStudio redirects back to the dashboard with an error and does not create an empty draft.

The create and regenerate forms include prompt controls for tone, length, audience, and language. These controls are stored with each draft and sent to the LLM provider during generation.

For Groq, prefer llama-3.3-70b-versatile over llama-3.1-8b-instant when content quality matters. The 8B model is fast, but it is more likely to produce generic captions from short topics.

Quality Checks

Draft detail pages include a local Check Quality action. It checks for empty package fields, long Threads or Instagram text, weak alt text, too few or duplicated hashtags, missing # prefixes, and missing or duplicated hooks.

This is a local readiness check, not a Meta policy or publishing API check.

Test your LLM configuration without saving a draft:

python scripts/llm_smoke.py --topic "AI video editing tools" --content-type ai_tool

The command prints validated JSON on success and exits with code 1 on provider/configuration failure. It accepts the same prompt controls as the UI:

python scripts/llm_smoke.py --topic "AI video editing tools" --content-type ai_tool --tone direct --length short --audience creators --language russian

PowerShell example:

$env:LLM_PROVIDER="groq"
$env:LLM_API_KEY="..."
$env:LLM_MODEL="llama-3.1-8b-instant"
python scripts/llm_smoke.py --topic "AI video editing tools" --content-type ai_tool

Demo Flow

1. Start the app with python app.py.
2. Open http://127.0.0.1:8765.
3. Click Load Demo Drafts.
4. Search for demo.
5. Open AI Reels Script Assistant.
6. Copy one platform text block.
7. Mark Instagram or Threads as posted manually.
8. Generate an export package.
9. Download the zip and inspect the text files plus metadata.json.

A scripted walkthrough is available in docs/DEMO_SCRIPT.md.

Architecture

app.py                  Local HTTP server and route orchestration
studio/models.py        Draft model and statuses
studio/storage.py       Atomic local JSON persistence
studio/generator.py     Deterministic package generation
studio/generation_options.py Prompt control normalization
studio/quality.py       Local package readiness checks
studio/rendering.py     HTML rendering
studio/assets.py        Local image asset path safety
studio/multipart.py     Python 3.13 safe multipart form parser
studio/exporter.py      Safe zip export generation
studio/draft_filters.py Dashboard search and summaries
studio/demo.py          Idempotent demo draft seeding
static/                 CSS and clipboard JavaScript
tests/                  Standard-library unittest coverage

More detail is in ARCHITECTURE.md.

Documentation

• PRODUCT.md - product contract and MVP acceptance criteria.
• SECURITY.md - platform safety boundary.
• ARCHITECTURE.md - system structure and layers.
• ROADMAP.md - milestone direction.
• CHANGELOG.md - release history.
• docs/CASE_STUDY.md - portfolio case study.

Local State

The following are local runtime artifacts and are intentionally ignored by git:

• data/*.json
• outputs/images/*
• exports/*.zip
• *.log
• __pycache__/

Current Status

GemmaStudio is a local MVP. It is suitable for a portfolio demo, local workflow testing, and continued iteration on generation quality, analytics, and presentation. It is not a hosted multi-user service.