Futuroptimist 👋

Building open-source tools so anyone can invent, automate & explore.

Hi, I'm Futuroptimist. This repository hosts scripts and metadata for my YouTube channel. If you're looking for the full project details, see INSTRUCTIONS.md. We manage Python dependencies with uv; check the instructions for setup steps. Guidelines for AI tools live in AGENTS.md. The canonical Codex prompt for automated contributions is in docs/prompts/codex/automation.md. The automated tests run via GitHub Actions on each push and pull request and currently reach 100% coverage.

Map of the repo

Navigate in three hops:

1. Setup – Follow INSTRUCTIONS.md for uv environment steps and contributor onboarding.
2. Run – Explore the Makefile targets for day-to-day automation; CLI helpers live in src/.
3. Test – Execute make test (documented in INSTRUCTIONS.md) to run the full pytest suite with coverage.

Category	Path / resource	Notes
Apps	n/a	Entry points live in src/; no standalone services yet.
Packages	src/	Shared Python modules and CLI entry points.
Scripts	scripts/	Operational helpers (e.g., prompt migrations, scans).
Data	data/prompt-docs/	Lightweight reference lists synced with docs.
Docs	docs/	Prompts, playbooks, and supporting guides.
Tests	tests/	Pytest suite mirroring production helpers.
Pipelines	outages/	Incident logs and schema describing stability.
Infra	.github/workflows/	CI for lint, tests, docs, status updates.

Prompt templates stay grouped under docs/prompts/codex/ with an index in docs/README.md. Video narration lives in video_scripts/, and multimedia assets are catalogued via the Makefile targets above.

uv cheat sheet: uv sync installs dependencies from requirements.txt, uv run pytest mirrors make test, and uvx <tool> launches one-off binaries without polluting the virtual environment.

YouTube Transcript MCP Service

tools/youtube_mcp/ packages a transcript fetcher that powers a CLI, FastAPI microservice, and MCP-compatible stdio tool. It normalises captions for retrieval, stores 14-day cached payloads in SQLite, and preserves provenance via timestamped cite URLs.

• HTTP: python -m tools.youtube_mcp --host 127.0.0.1 --port 8765
• CLI: python -m tools.youtube_mcp.cli transcript --url https://youtu.be/VIDEOID
• MCP: python tools/youtube_mcp/mcp_server.py

Example HTTP call:

curl "http://127.0.0.1:8765/transcript?url=https://youtu.be/VIDEOID"

Policy notes: the service only uses youtube_transcript_api and the public oEmbed endpoint, rejecting private/unlisted videos when signals are available. It never scrapes HTML or bypasses authentication walls.

Caching: responses are keyed by video ID, language, and track type with a default 14-day TTL; expired rows are purged automatically when accessed.

Error codes: InvalidArgument, VideoUnavailable, NoCaptionsAvailable, PolicyRejected, RateLimited, and NetworkError map to consistent HTTP responses and MCP error payloads.

Related Projects

Last updated: 2025-12-01 17:03 UTC; checks hourly

Last updated: 2025-11-06 08:02 UTC; checks hourly Status icons: ✅ latest run succeeded, ❌ failed or cancelled, ❓ no completed runs. The unknown state is enforced by tests/test_repo_status.py::test_fetch_repo_status_no_runs_returns_unknown, ensuring repositories without completed workflows render ❓ instead of failing the dashboard.

• ✅ futuroptimist – central hub for reproducible scripts, data pipelines, and tests that turn maker experiments into polished YouTube episodes
• ✅ token.place – secure peer-to-peer generative AI network that lets volunteers share idle compute through ephemeral, encrypted tokens—no sign-ups required (repo)
• ✅ DSPACE @v3 – retro-futurist idle sim where quests teach real-world hobbies with NPC guides; offline-first so your space-base thrives without a signal (repo)
• ✅ flywheel – GitHub template that bundles lint, tests, docs, and release automation with LLM agents so solo builders ship like a team
• ✅ gabriel – privacy-first "guardian angel" LLM that learns your environment and delivers local, actionable security coaching
• ✅ f2clipboard – CLI that parses Codex task pages, grabs failing GitHub logs, and pipes concise reports straight to your clipboard to speed debugging
• ✅ axel – LLM-powered quest tracker that analyzes your repos and curates next steps to keep side projects moving
• ✅ sigma – open-source ESP32 AI pin with push-to-talk voice control, running speech-to-text, LLM, and TTS in a 3D-printed case so commands stay local
• ✅ gitshelves – turns your GitHub contributions into stackable 3D-printable blocks that fit 42 mm Gridfinity baseplates, turning commit history into shelf art
• ✅ wove – open toolkit for learning to knit and crochet while evolving toward robotic looms, bridging CAD workflows with textiles
• ❌ sugarkube – solar-powered k3s platform and cube art installation for Raspberry Pi clusters, making off-grid edge Kubernetes plug-and-play
• ✅ pr-reaper – GitHub workflow that closes your own stale pull requests in bulk with a safe dry-run
• ✅ danielsmith.io – Vite + Three.js playground for an orthographic, keyboard-navigable portfolio scene
• ✅ jobbot3000 – self-hosted job search copilot sharing the same automation scaffold as this repo

Values

We aim for a positive-sum, empathetic community that shares knowledge openly.

---

Licensed under the MIT License.