{"id":50320653,"url":"https://github.com/glad-labs/poindexter","last_synced_at":"2026-06-03T06:00:41.836Z","repository":{"id":350568569,"uuid":"1206534248","full_name":"Glad-Labs/poindexter","owner":"Glad-Labs","description":"Poindexter — open-source AI content pipeline that researches, writes, reviews, and publishes autonomously. Self-hosted on your machine. Built by Glad Labs LLC.","archived":false,"fork":false,"pushed_at":"2026-05-31T07:42:15.000Z","size":137576,"stargazers_count":1,"open_issues_count":62,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-31T09:22:19.088Z","etag":null,"topics":["ai","ai-content","apache2","automation","blog-engine","content-pipeline","fastapi","grafana","headless-cms","llm","ollama","pgvector","postgresql","self-hosted"],"latest_commit_sha":null,"homepage":"https://www.gladlabs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Glad-Labs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-10T02:25:55.000Z","updated_at":"2026-05-31T07:40:48.000Z","dependencies_parsed_at":null,"dependency_job_id":"a02ef32b-7595-497b-9f6c-0c63a4ecf71e","html_url":"https://github.com/Glad-Labs/poindexter","commit_stats":null,"previous_names":["glad-labs/poindexter"],"tags_count":137,"template":false,"template_full_name":null,"purl":"pkg:github/Glad-Labs/poindexter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Glad-Labs%2Fpoindexter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Glad-Labs%2Fpoindexter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Glad-Labs%2Fpoindexter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Glad-Labs%2Fpoindexter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Glad-Labs","download_url":"https://codeload.github.com/Glad-Labs/poindexter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Glad-Labs%2Fpoindexter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33850627,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-content","apache2","automation","blog-engine","content-pipeline","fastapi","grafana","headless-cms","llm","ollama","pgvector","postgresql","self-hosted"],"created_at":"2026-05-29T03:04:50.855Z","updated_at":"2026-06-03T06:00:41.830Z","avatar_url":"https://github.com/Glad-Labs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Poindexter\n\n**A plug-and-play AI/ML content creation OSS stack.** Your PC is the factory: Poindexter researches, writes, reviews, and publishes — autonomously. Local-first, Ollama-powered, zero API costs. Built by [Glad Labs LLC](https://www.gladlabs.io).\n\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n[![Tests](https://img.shields.io/badge/tests-8%2C400%2B_passing-brightgreen)]()\n[![Status](https://img.shields.io/badge/status-alpha-orange.svg)]()\n[![Built by Glad Labs LLC](https://img.shields.io/badge/built_by-Glad_Labs_LLC-blueviolet.svg)](https://www.gladlabs.io)\n\n## Who this is for\n\nIf you've ever thought _\"I could publish good content at scale if I had a system that didn't just spam mediocre AI text,\"_ — Poindexter is that system.\n\nIt's built for:\n\n- **Solo operators** who want to run a content business from one machine, with their own GPU, without paying per-token API fees\n- **Indie publishers** who need automation but refuse to ship hallucinated text\n- **AI/ML engineers** who want a working content stack to fork, extend, and learn from — every layer is OSS, every layer is swappable\n\nIt is _not_ for: marketing teams who want a one-click web app (use Jasper / Copy.ai), or anyone unwilling to run Docker on their machine.\n\nThe pitch is \"plug and play\": `poindexter setup --auto` takes you from a fresh clone to a healthy local stack in one command — Postgres provisioned, OAuth client minted, migrations run, models pulled, services up. After that, every component is swappable through `app_settings` or plugins.\n\n## What it does\n\nOne engine, eight jobs:\n\n1. **Discovers** trending topics from HackerNews, Dev.to, and your niche feeds\n2. **Researches** each topic with deep web search and source verification\n3. **Writes** long-form posts using local LLMs (Ollama) — or cloud models via the optional LiteLLM provider plugin\n4. **Reviews** every draft with multi-model adversarial QA on 7 quality dimensions\n5. **Validates** against hallucinations — catches fake people, stats, quotes, impossible claims\n6. **Publishes** to any frontend via static JSON export (push-only headless CMS)\n7. **Generates** podcast episodes, AI images, and short text-to-video clips (Wan 2.1 T2V — alpha, opt-in)\n8. **Monitors** itself with Grafana dashboards, auto-heals via brain daemon, alerts on Telegram/Discord\n\nRun it on your machine. Own your data. No cloud lock-in.\n\n**Not a spam cannon.** ~50% of generated drafts are rejected by QA. Multi-model adversarial review, deterministic anti-hallucination validation, and research-backed content. Speed comes from generating more candidates and filtering aggressively — not from lowering the bar.\n\n## Quick start\n\n\u003e **Windows users:** run from Git Bash or WSL. The setup script needs `bash`.\n\n```bash\n# 1. Clone\ngit clone https://github.com/Glad-Labs/poindexter.git\ncd poindexter\n\n# 2. Setup — generates secrets, tests DB, writes ~/.poindexter/bootstrap.toml\npip install -e src/cofounder_agent\npoindexter setup --auto    # spins up local Postgres automatically\n\n# 3. Pull AI models\nollama pull gemma3:27b \u0026\u0026 ollama pull qwen3:8b \u0026\u0026 ollama pull nomic-embed-text\n\n# 4. Start the full stack\nbash scripts/start-stack.sh\n\n# 5. Generate your first post\npoindexter content create \"Why Docker changed everything\" --category technology\n```\n\nThe pipeline runs automatically. Watch progress at `http://localhost:3000` (Grafana).\n\n### Prerequisites\n\n- **Docker Desktop** — [docker.com](https://docker.com)\n- **Ollama** — [ollama.com](https://ollama.com)\n- **Node.js 22+** — [nodejs.org](https://nodejs.org) (for the optional Next.js public site)\n- **GPU** — RTX 3060+ (8 GB VRAM minimum). Works on CPU, just slowly.\n\n### Required models\n\n`poindexter setup --auto` doesn't pull these — Ollama does, but you trigger it. With these three, the full pipeline runs end-to-end on any 8 GB+ GPU:\n\n| Model              | Size   | Role                                                  |\n| ------------------ | ------ | ----------------------------------------------------- |\n| `qwen3:8b`         | 5 GB   | Fast tasks — SEO, image decisions, summaries, routing |\n| `gemma3:27b`       | 16 GB  | QA critic + writer fallback                           |\n| `nomic-embed-text` | 274 MB | Embeddings for semantic search + memory retrieval     |\n\n### Writer model — configurable\n\nThe writer is the one model worth upgrading. Set `pipeline_writer_model` in `app_settings` (or via `poindexter settings set`) to any Ollama model you have. Trade-offs:\n\n```bash\nollama pull qwen3:30b          # 18 GB — best speed/quality balance publicly available\nollama pull qwen3.5:35b        # 23 GB — stronger prose, slower\nollama pull llama3.3:70b       # 42 GB — highest quality, needs 48 GB+ VRAM or CPU offload\nollama pull glm-4.7:9b         # 6 GB — lighter fallback for \u003c16 GB VRAM\n```\n\nGlad Labs production runs a custom RTX 5090 fine-tune (`glm-4.7-5090`, 19 GB) not on the public registry; any of the above work fine.\n\nEvery model routing decision (writer / critic / research / summarizer / embedder) lives in `app_settings` and can be swapped at runtime — no restart, no redeploy.\n\n## Architecture\n\nPoindexter is decomposed by analogy to brain anatomy. Each region is independent and communicates only through PostgreSQL — no inter-service imports.\n\n```\nBrainstem    (brain/)              — standalone daemon, monitors, self-heals\nCerebrum     (src/cofounder_agent/) — FastAPI backend, content pipeline, REST + MCP\nCerebellum                          — anticipation engine + QA registry (learned patterns)\nLimbic       (brain_knowledge)     — knowledge graph, memory retrieval, revenue feedback\nThalamus                           — process composer, routes inputs to the right pipeline\nHypothalamus (settings_service)    — homeostasis: budget, cost guard, runtime config\nSpinal Cord  (PostgreSQL+pgvector) — shared substrate, all components talk through it\n\nAny frontend reads static JSON from CDN — Next.js, Hugo, Astro, or a single HTML file.\n```\n\nThe brainstem can crash and restart without taking down the cerebrum. The cerebrum can be replaced with a different pipeline implementation as long as it writes the same tables. The architecture is designed to be poked at one region at a time.\n\nFull diagram and design rationale in [`docs/architecture/`](docs/architecture/).\n\n## Key features\n\n| Feature                      | Description                                                                                 |\n| ---------------------------- | ------------------------------------------------------------------------------------------- |\n| **Local AI by default**      | Ollama for inference. Your GPU, your data, zero API costs.                                  |\n| **Cloud opt-in**             | LiteLLM provider plugin routes to Anthropic, OpenAI, Groq, OpenRouter — gated by cost guard |\n| **Anti-hallucination**       | 3 independent layers: prompts, multi-model QA, deterministic validator                      |\n| **DB-as-config**             | 800+ settings (60 secret) in PostgreSQL. Change with SQL or REST. No deploys.               |\n| **Langfuse-managed prompts** | Edit prompts in a UI; runtime falls back to YAML defaults if Langfuse is offline            |\n| **LangGraph pipelines**      | `template_runner.py` runs declarative DAGs with checkpointing                               |\n| **Multi-modal output**       | Markdown posts, AI images (SDXL / Flux), podcast audio, text-to-video (Wan 2.1 — alpha)     |\n| **Push-only output**         | Static JSON + RSS + JSON Feed 1.1 to any S3-compatible storage                              |\n| **Multi-site**               | One daemon manages N sites. Each site = config row + storage bucket.                        |\n| **Self-healing**             | Brain daemon monitors all services, restarts failures, alerts via Telegram/Discord          |\n| **Production observability** | Grafana, Prometheus, Loki, Pyroscope (CPU profiling), Sentry/GlitchTip                      |\n| **OAuth 2.1 throughout**     | Every consumer (CLI, MCP, brain, scripts) mints scoped JWTs. No static API keys.            |\n| **8,400+ tests**             | Unit coverage across all services, smoke tests on migrations, link-rot CI                   |\n\n## Stack\n\n- **Backend:** Python 3.13 / FastAPI / asyncpg\n- **LLM (default):** [Ollama](https://ollama.com) — local inference, your GPU\n- **LLM (optional):** [LiteLLM](https://github.com/BerriAI/litellm) provider plugin — Anthropic, OpenAI, Groq, OpenRouter, Bedrock, Vertex (gated by `cost_guard`)\n- **Orchestration:** [LangGraph](https://github.com/langchain-ai/langgraph) (declarative pipelines via `template_runner`)\n- **Prompt management:** [Langfuse](https://langfuse.com) (UI-editable, runtime fallback to YAML)\n- **Embeddings:** `nomic-embed-text` via Ollama → pgvector\n- **Database:** PostgreSQL 16 + pgvector\n- **Auth:** OAuth 2.1 Client Credentials Grant (per-consumer JWTs)\n- **Observability:** Grafana + Prometheus + Loki + [Pyroscope](https://pyroscope.io) + Sentry-compatible (GlitchTip)\n- **Voice (optional):** LiveKit + Whisper (STT) + Kokoro (TTS)\n- **Storage:** any S3-compatible (Cloudflare R2, AWS S3, Backblaze B2, MinIO)\n- **CI/CD:** GitHub Actions\n- **Infrastructure:** Docker Compose (~32 containers including the full observability + voice + image-gen sidecars; a minimal worker-only deploy needs ~8)\n\n## Configuration\n\nEverything tunable lives in the `app_settings` database table — not environment variables. The only file you write to disk is `~/.poindexter/bootstrap.toml`, created by `poindexter setup`. It contains the database URL plus a small number of pre-DB-reachable secrets (Postgres password, OAuth signing key, optional Telegram/Discord operator alerts).\n\nAfter that, every config knob is managed via API, SQL, or the CLI:\n\n```bash\n# View all settings\npoindexter settings list\n\n# Change a setting at runtime\npoindexter settings set auto_publish_threshold 80\n\n# Rotate via REST (with OAuth-issued JWT)\ncurl -X PUT http://localhost:8002/api/settings/auto_publish_threshold \\\n  -H \"Authorization: Bearer $(poindexter auth token)\" \\\n  -d '{\"value\": \"80\"}'\n```\n\nNo restart required for most settings. See [`docs/operations/environment-variables.md`](docs/operations/environment-variables.md).\n\n## Plugins\n\nPoindexter is built on a small extension framework. Eighteen plugin types let you customize the system without touching core code — the most commonly extended ones:\n\n| Type               | Role                                                                                   |\n| ------------------ | -------------------------------------------------------------------------------------- |\n| **Tap**            | Pulls data into the system (RSS, Slack, social feeds, etc.)                            |\n| **Probe**          | Reports state to the brain (health checks, business metrics)                           |\n| **Job**            | Scheduled work (cron-like, lives in the worker)                                        |\n| **Stage**          | A step in the content pipeline (research, draft, QA, etc.)                             |\n| **TopicSource**    | Discovers candidate topics (HackerNews, dev.to, web search, etc.)                      |\n| **LLMProvider**    | Inference backend (Ollama is default; LiteLLM, OpenAI-compat, etc.)                    |\n| **ImageProvider**  | Featured + inline images (SDXL, Flux, Pexels, etc.)                                    |\n| **PublishAdapter** | Where finished posts go (S3-compatible, Discord, custom CMS, etc.)                     |\n| **Module**         | Bundles the above + migrations + routes into a versioned business function (Module v1) |\n\nThe full set also includes Reviewers, Adapters, Packs, AudioGenProviders, VideoProviders, TTSProviders, CaptionProviders, and MediaCompositors. See `plugins/registry.py::ENTRY_POINT_GROUPS` for the canonical list.\n\nEach plugin lives in its own pip package and registers via setuptools `entry_points`.\n\n### Using a plugin\n\n```bash\npip install poindexter-tap-slack\npoindexter settings set plugin.tap.slack '{\"enabled\": true, \"config\": {\"workspace\": \"myteam\"}}'\n```\n\nNext worker restart picks it up. No core code changes.\n\n### Authoring a plugin\n\nA package needs three things — a class implementing the relevant Protocol, an `entry_points` registration, and per-install config docs. Example Tap:\n\n```python\n# my_package/slack_tap.py\nfrom poindexter.plugins import Tap, Document\n\nclass SlackTap:\n    name = \"slack\"\n    interval_seconds = 3600\n\n    async def extract(self, pool, config):\n        async for msg in fetch_slack_messages(config):\n            yield Document(\n                source_id=f\"slack/{msg.ts}\",\n                source_table=\"slack\",\n                text=msg.text,\n                metadata={\"channel\": msg.channel, \"user\": msg.user},\n                writer=\"poindexter-tap-slack\",\n            )\n```\n\n```toml\n# pyproject.toml\n[project.entry-points.\"poindexter.taps\"]\nslack = \"my_package.slack_tap:SlackTap\"\n```\n\nThe shipping samples (`HelloTap`, `DatabaseProbe`, `NoopJob`) live in `src/cofounder_agent/plugins/samples/`. The first real plugin in production is the `LiteLLMProvider` — Glad Labs eats its own dog food. Full design in [`docs/architecture/plugin-architecture.md`](docs/architecture/plugin-architecture.md).\n\n## Project status\n\nPoindexter is in **alpha**. Honest snapshot:\n\n**What works today**\n\n- Full content pipeline end-to-end on the author's daily-driver setup (RTX 5090, 64 GB RAM, Windows 11). Single-operator content business publishing daily.\n- 78 live posts on [gladlabs.io](https://www.gladlabs.io) (222 total drafts, 1,626 pipeline runs).\n- 8,400+ unit tests passing in CI on every push, plus migrations smoke test and link-rot CI.\n- `poindexter setup` takes a fresh clone to a healthy local stack — generates secrets, tests DB, runs migrations, writes bootstrap.toml. No `.env` file required.\n- Live in-place upgrades — schema changes, container renames, env var migrations applied to a running instance with zero data loss and no in-flight task downtime.\n- Multi-model QA scoring with deterministic validators, an LLM critic chain, and a programmatic anti-hallucination layer.\n- Push-only static export to any S3-compatible storage. Frontend is decoupled — Next.js, Hugo, Astro, or a static HTML file.\n- OAuth 2.1 throughout (per-consumer scoped JWTs, no static API keys).\n\n**Known rough edges**\n\n- No managed/hosted Poindexter offering yet. Self-host only.\n- No multi-tenant deployment recipe. One operator, one machine.\n- Native Windows cmd / PowerShell not supported. Use Git Bash or WSL.\n- Database schema is not yet stable across releases. Read the CHANGELOG before upgrading.\n- Plugin framework is real (LiteLLMProvider runs in production), but the community ecosystem is nascent — you may be writing the second-ever third-party plugin.\n- **Text-to-video is alpha.** The Wan 2.1 T2V provider plugin and `wan-server` Docker sidecar exist and pass smoke tests, but it's an opt-in path (not in the default content pipeline) and the inference server needs ~28 GB VRAM headroom on a 32 GB+ card. Track Glad-Labs/poindexter#124 for production-readiness.\n\nIf any of those would block your use case, that's worth knowing before you start. PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING).\n\n## Pricing\n\nThe engine is free and open-source under Apache 2.0. **Pro** is a subscription for operators who want production-grade output without tuning from scratch.\n\n| Tier     | Price                                                 | What you get                                                                                                                                                                 |\n| -------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Free** | $0                                                    | Full pipeline engine, baseline prompts, 1 Grafana dashboard (Pipeline Operations), GitHub issues support                                                                     |\n| **Pro**  | $9/mo or $89/year (save ~17%)\u003cbr\u003e**7-day free trial** | Production-tuned prompts (anti-hallucination, SEO, QA, research), additional Grafana dashboards, prompt updates as Matt tunes them, private VIP Discord, the Poindexter book |\n\nPro exists for the obvious case: you've installed the OSS, you've seen output that's _almost_ there, and you want the version that's actually shipping content on gladlabs.io daily. Pro gives you the months of prompt tuning in a single install.\n\n- **[Start your 7-day Pro trial — $9/mo](https://gladlabs.lemonsqueezy.com/checkout/buy/a5713f22-3c57-47ae-b1ee-5fee3a0b43b9)**\n- [Subscribe annually — $89/year](https://gladlabs.lemonsqueezy.com/checkout/buy/a5713f22-3c57-47ae-b1ee-5fee3a0b43b9)\n- [Compare tiers on gladlabs.io/product](https://www.gladlabs.io/product)\n\n## Documentation\n\nFull technical docs live under [`docs/`](docs/welcome). Recommended path:\n\n- **[Architecture overview](docs/architecture/overview)** — how the regions fit together\n- **[Multi-agent pipeline](docs/architecture/multi-agent-pipeline)** — the content pipeline + cross-model QA\n- **[Database schema](docs/architecture/database-schema)** — every table + migration system\n- **[CLI reference](docs/operations/cli-reference)** — every `poindexter` subcommand\n- **[Plugin authoring](docs/operations/extending-poindexter)** — write Stages, Reviewers, Adapters, Taps, Jobs, Probes\n- **[Local development setup](docs/operations/local-development-setup)** — end-to-end walkthrough\n- **[Troubleshooting](docs/operations/troubleshooting)** — production issues we've hit\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING). Issues and PRs welcome.\n\n## Security \u0026 SBOM\n\n- Report vulnerabilities to **security@gladlabs.io** ([SECURITY.md](SECURITY))\n- Every push to `main` runs gitleaks (secrets), Trivy (CVEs), and syft+grype (SBOM + CVE scan)\n- A CycloneDX-JSON **SBOM** is published as a workflow artifact on every release; enterprise buyers can request one directly\n\n## License\n\n[Apache License 2.0](LICENSE) — Copyright 2025-2026 Glad Labs LLC\n\nRelicensed from AGPL-3.0 to Apache 2.0 on 2026-04-29 — see [CHANGELOG](CHANGELOG.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglad-labs%2Fpoindexter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fglad-labs%2Fpoindexter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglad-labs%2Fpoindexter/lists"}