anyscribecli 0.3.1__tar.gz

anyscribecli-0.3.1/.claude/settings.local.json

@@ -0,0 +1,13 @@
+{
+  "permissions": {
+    "allow": [
+      "Read(//Users/rish/thefoundry/**)",
+      "Read(//Users/rish/thefoundry/secondbrain/dev/journal/2026-03-29/**)"
+    ],
+    "additionalDirectories": [
+      "/Users/rish/thefoundry/secondbrain/dev/journal",
+      "/Users/rish/thefoundry/secondbrain",
+      "/Users/rish/thefoundry/secondbrain/dev/journal/2026-03-29"
+    ]
+  }
+}

anyscribecli-0.3.1/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.venv/
+*.egg
+
+# Environment and secrets
+.env
+*.env.local
+
+# Media files (downloaded content)
+*.mp3
+*.mp4
+*.m4a
+*.wav
+*.ogg
+*.flac
+*.webm
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# App runtime (these live in ~/.anyscribecli/)
+sessions/
+tmp/
+logs/

anyscribecli-0.3.1/AGENTS.md

@@ -0,0 +1,82 @@
+# anyscribecli — Agent Directives
+
+## Before Starting Work
+
+1. Read `CLAUDE.md` for architecture and patterns
+2. Read `docs/building/_index.md` for recent project history
+3. If your task touches providers or downloaders, read the relevant living doc
+4. Check `docs/building/journal/` for any recent entries related to your task area
+
+## Memory Layer
+
+`docs/building/journal/` is the project memory. It exists so that agents in future sessions have context about past decisions, bugs, and research.
+
+### Reading memory (before work)
+
+- Scan `docs/building/_index.md` — it's a newest-first table of all entries
+- Read any entries tagged with your task area
+- This prevents re-investigating solved problems or re-debating settled decisions
+
+### Writing memory (after work)
+
+After completing significant work, create a journal entry:
+
+```
+docs/building/journal/YYYY-MM-DD-<descriptive-slug>.md
+```
+
+With frontmatter:
+```yaml
+---
+type: decision|research|troubleshooting|learning
+tags: [relevant, tags]
+tldr: "One-line summary"
+---
+```
+
+Then prepend a row to `docs/building/_index.md`.
+
+## Post-Commit Checklist
+
+**After every significant commit**, follow `docs/building/COMMIT_CHECKLIST.md`. It has per-scenario checklists (new command, new provider, new downloader, version bump) and grep commands to catch stale references. This is mandatory.
+
+## Documentation Requirements
+
+### Developer docs (`docs/building/`)
+- Every PR or significant change MUST include a building doc update
+- If you changed architecture: update `docs/building/architecture.md`
+- If you added/changed a provider: update `docs/building/providers.md`
+- If you added/changed a downloader: update `docs/building/downloaders.md`
+- If you made a non-trivial decision: write a journal entry explaining why
+
+### User docs (`docs/user/`)
+- If you added/changed a user-facing command or flag: update `docs/user/commands.md`
+- If you changed config options: update `docs/user/configuration.md`
+- If you changed the onboarding flow: update `docs/user/getting-started.md`
+- User docs target semi-technical users new to CLI — explain jargon, show examples, include troubleshooting
+- Every user doc has frontmatter: `summary`, `read_when`, `title`
+
+## Quick Context
+
+- CLI entry point: `src/anyscribecli/cli/main.py`
+- Onboarding + provider info: `src/anyscribecli/cli/onboard.py`
+- Config/providers commands: `src/anyscribecli/cli/config_cmd.py`
+- Download command: `src/anyscribecli/cli/download.py`
+- Batch processing: `src/anyscribecli/cli/batch.py`
+- Config loading: `src/anyscribecli/config/settings.py`
+- Path constants: `src/anyscribecli/config/paths.py`
+- Provider ABC + registry: `src/anyscribecli/providers/base.py`, `providers/__init__.py`
+- Downloader ABC + registry: `src/anyscribecli/downloaders/base.py`, `downloaders/registry.py`
+- Core flow: `src/anyscribecli/core/orchestrator.py`
+- Dependency checker: `src/anyscribecli/core/deps.py`
+- Update system: `src/anyscribecli/core/updater.py`
+
+## Key Dependencies
+
+- `beaupy` — arrow-key selectors in onboarding wizard
+- `instaloader` — Instagram auth + post metadata (main dep, not optional)
+- `faster-whisper` — local transcription (optional, only for `local` provider)
+
+## Cross-Platform
+
+All code must work on macOS and Linux. Use `pathlib.Path` everywhere. No platform-specific assumptions.

anyscribecli-0.3.1/BACKLOG.md

@@ -0,0 +1,178 @@
+# Backlog
+
+What's built, what's next, and what's on the horizon.
+
+## Versioning
+
+This project uses **Semantic Versioning** (SemVer): `MAJOR.MINOR.PATCH`
+
+- **PATCH** (0.1.0 → 0.1.1): bug fixes, typos, small tweaks
+- **MINOR** (0.1.0 → 0.2.0): new features, new provider, new command — backwards compatible
+- **MAJOR** (0.x → 1.0.0): breaking changes (config format, removed commands, renamed flags)
+
+The `0.x` prefix means pre-stable — breaking changes are allowed between minor versions. `1.0.0` signals stability.
+
+### Version → Release mapping
+
+| Version | Milestone | Status |
+|---------|-----------|--------|
+| 0.1.0 | YouTube + OpenAI MVP | Released 2026-03-26 |
+| 0.2.0 | Full feature build (Instagram, all providers, batch, config, onboarding) | Released 2026-03-26 |
+| 0.3.0 | Download command, media restructure, post-transcription prompts, UX polish | Released 2026-03-27 |
+| 0.3.1 | Documentation accuracy audit — 16 issues fixed across all docs | **Current** |
+| 0.4.0 | Cache/dedup, test suite, error handling | Next |
+| 1.0.0 | Stable: published on PyPI, full test coverage | Future |
+
+### How to bump versions
+
+Version lives in TWO places (must match):
+- `src/anyscribecli/__init__.py`
+- `pyproject.toml`
+
+```bash
+# After changing both files:
+git add -A && git commit -m "Bump version to X.Y.Z"
+git tag vX.Y.Z
+git push && git push --tags
+```
+
+---
+
+## v0.1.0 — YouTube + OpenAI MVP ✅
+
+**Released:** 2026-03-26
+
+Everything needed to transcribe a YouTube video to markdown:
+
+- [x] YouTube download via yt-dlp (optimized audio: 16kHz, mono, 64kbps)
+- [x] OpenAI Whisper transcription (verbose_json, segment timestamps)
+- [x] Audio chunking for files >25MB (18-min chunks)
+- [x] Obsidian vault output with YAML frontmatter
+- [x] Master index (_index.md) + daily processing logs
+- [x] `ascli onboard` — interactive wizard with dependency checking + auto-install
+- [x] `ascli transcribe <url>` — with --provider, --language, --json, --keep-media, --quiet
+- [x] `ascli update` — dual-path updater (git + pip)
+- [x] `ascli doctor` — system health checks
+- [x] `install.sh` — zero-friction installer script
+- [x] CLAUDE.md + AGENTS.md — AI developer instructions
+- [x] Developer memory layer (docs/building/)
+- [x] User documentation (docs/user/) — semi-technical audience
+- [x] MIT license, PyPI-ready metadata
+
+---
+
+## v0.2.0 — Instagram + Config + Providers + Batch + Local ✅
+
+**Released:** 2026-03-26
+
+All features originally planned for v0.2.0–v0.5.0, built in one session:
+
+- [x] Instagram downloader (`downloaders/instagram.py`)
+  - instaloader Python API with session caching (Dropzone bundle pattern)
+  - Auth credentials from config.yaml
+  - Reels and posts supported
+- [x] `ascli config show` — display current settings (supports --json)
+- [x] `ascli config set <key> <value>` — dot-notation for nested keys
+- [x] `ascli config path` — print config file location
+- [x] `ascli providers list` — show available providers with active indicator
+- [x] `ascli providers test <name>` — test a provider's API key
+- [x] OpenRouter provider — audio-via-chat using GPT-4o-audio-preview
+- [x] ElevenLabs provider — Scribe v1 STT API, word-level timestamps
+- [x] Sargam/Sarvam provider — Indic languages, auto-chunks to 30s for REST API limit
+- [x] Local provider — faster-whisper, CPU/GPU, no API key, offline
+- [x] `ascli batch <file>` — batch transcribe URLs from a file
+- [x] Updated user docs for all new commands
+- [x] Per-provider API key management in onboarding wizard
+- [x] Instagram credentials in onboarding wizard
+- [x] `output_format: timestamped` — transcript with `[mm:ss]` timestamps per segment
+- [x] Rich progress bar for batch jobs
+- [x] Batch summary in daily log (each item indexed via orchestrator)
+- [x] Provider comparison docs (`docs/user/providers.md`)
+
+---
+
+## v0.3.0 — Download, Media Restructure, UX Polish ✅
+
+**Released:** 2026-03-27
+
+- [x] `ascli download <url>` — download video or audio only, no transcription
+  - `--video` (default) and `--audio-only` flags
+  - Saves to `~/.anyscribecli/media/video/` or `media/audio/`
+  - Supports --clipboard, --json, interactive prompt
+- [x] Media restructured: moved outside workspace, split into audio/ and video/ by platform/date
+- [x] Instagram password moved from config.yaml to .env (security fix)
+- [x] `prompt_download` config: never/ask/always — post-transcription download offer
+- [x] Onboarding wizard: arrow-key selectors (beaupy), post-transcription download step
+- [x] URL validation: catches zsh glob mangling, interactive prompt fallback, --clipboard
+- [x] instaloader promoted to main dependency (was optional)
+- [x] Post-commit checklist (`docs/building/COMMIT_CHECKLIST.md`)
+- [x] `build-with-rish.md` — reusable build reference for future projects
+
+---
+
+## v0.4.0 — Cache, Dedup, Quality
+
+- [ ] **Duplicate / cache checking** (inspired by AnyScribe web app's FindStamp pattern):
+  - Before transcribing: check if URL was already transcribed (lookup by source URL in _index.md or a cache file)
+  - Before downloading: check if video/audio already exists in media/
+  - If cached, show the existing transcript and ask to re-transcribe or skip
+  - `--force` flag to bypass cache and re-transcribe
+  - Track cache hits/misses for cost awareness
+- [ ] Full test suite (pytest — unit tests for providers, downloaders, vault, config)
+- [ ] Comprehensive error handling and retry logic (network failures, API rate limits)
+- [ ] Suppress instaloader's noisy retry output (redirect to log file)
+- [ ] `ascli logs` command to view recent log files
+
+---
+
+## v1.0.0 — Stable Release
+
+- [ ] PyPI published (`pip install anyscribecli`) — see "Publishing to PyPI" below
+- [ ] GitHub Releases with release notes for each tag
+- [ ] Full test coverage
+- [ ] Stable config format (breaking changes require v2.0.0)
+- [ ] CI/CD pipeline (GitHub Actions: lint, test, build, publish)
+
+### Publishing to PyPI (when ready)
+
+PyPI is the Python package registry — makes `pip install anyscribecli` work globally.
+
+```bash
+# One-time: create account at pypi.org, generate API token
+pip install build twine
+python -m build                    # creates dist/anyscribecli-X.Y.Z.tar.gz + .whl
+twine upload dist/*                # uploads to PyPI (prompts for token)
+```
+
+After publishing, update `install.sh` to use `pip install anyscribecli` instead of `git+https://...`.
+
+### GitHub Releases (when ready)
+
+A GitHub Release attaches release notes and downloadable assets to a git tag.
+It's how users on GitHub discover new versions.
+
+```bash
+# After committing and tagging:
+gh release create v0.3.0 --title "v0.3.0 — Download, Media Restructure, UX Polish" --notes-file RELEASE_NOTES.md
+```
+
+Or create via github.com/rishmadaan/anyscribecli/releases/new.
+
+For now, distribution is via git only:
+```bash
+pip install git+https://github.com/rishmadaan/anyscribecli.git
+```
+
+---
+
+## Icebox (ideas for later, no timeline)
+
+- GUI (web UI via FastAPI + React, or TUI via Textual)
+- Speaker diarization (who said what)
+- AI-generated summaries (TL;DR via LLM after transcription)
+- Chapter/section detection
+- Search across all transcripts (`ascli search <query>`)
+- Export formats beyond markdown (PDF, DOCX, SRT subtitles)
+- Podcast RSS feed ingestion
+- Topic file generation (Foundry-style, when 3+ transcripts share a topic)
+- Cost tracking (Whisper API usage per month)

anyscribecli-0.3.1/CLAUDE.md

@@ -0,0 +1,129 @@
+# anyscribecli — AI Developer Instructions
+
+## What This Is
+
+A Python CLI tool (`ascli`) that downloads video/audio from YouTube/Instagram, transcribes it via API, and outputs structured markdown into an Obsidian vault at `~/.anyscribecli/workspace/`.
+
+## Architecture
+
+```
+src/anyscribecli/
+├── cli/           # Typer commands (main.py, onboard.py, transcribe.py, download.py, batch.py, config_cmd.py)
+├── config/        # Paths + settings (paths.py, settings.py)
+├── downloaders/   # Platform downloaders (base.py, youtube.py, instagram.py, registry.py)
+├── providers/     # Transcription APIs (base.py, openai.py, openrouter.py, elevenlabs.py, sargam.py, local.py)
+├── vault/         # Obsidian vault management (scaffold.py, writer.py, index.py)
+└── core/          # Orchestration + audio + deps + updater (orchestrator.py, audio.py, deps.py, updater.py)
+```
+
+Flow: `CLI command -> orchestrator -> downloader + provider -> vault writer -> index update`
+
+## Key Patterns
+
+- **Providers** implement `TranscriptionProvider` ABC from `providers/base.py` (5 active: openai, elevenlabs, openrouter, sargam, local)
+- **Downloaders** implement `AbstractDownloader` ABC from `downloaders/base.py` (youtube, instagram)
+- **Config** at `~/.anyscribecli/config.yaml` — secrets in `.env` (API keys, Instagram password)
+- **All paths** use `pathlib.Path` via `config/paths.py` — no hardcoded separators
+- **CLI output** human-readable by default, `--json` flag for machine/agent consumption
+- **Interactive prompts** use `beaupy` (arrow-key selectors) for onboarding, `typer.prompt` for text input
+- **URL input** three methods: quoted argument (primary), interactive prompt (fallback), clipboard
+- **Media outside vault** — audio in `~/.anyscribecli/media/audio/`, video in `media/video/`, workspace is pure markdown
+- **Audio params** optimized for Whisper: 16kHz, mono, 64kbps mp3
+- **Chunking** — 18-min segments for Whisper (25MB limit), 30s segments for Sarvam (REST API limit)
+
+## Documentation Ethic
+
+This project maintains TWO documentation layers. Both are mandatory, not optional.
+
+### 1. Developer memory layer (`docs/building/`)
+
+For developers and AI agents working on the codebase.
+
+**When to write a building doc entry:**
+- After completing a significant feature or change
+- After making an architecture decision
+- After debugging a non-trivial issue
+- After researching alternatives and choosing one
+
+**How to write one:**
+1. Create `docs/building/journal/YYYY-MM-DD-<slug>.md` with frontmatter (type, tags, tldr)
+2. Update `docs/building/_index.md` with a new row (newest first)
+3. Update relevant living docs (`architecture.md`, `providers.md`, `downloaders.md`) if the change affects them
+
+**Living docs vs journal entries:**
+- **Living docs** (`architecture.md`, `providers.md`) reflect current state — update in place
+- **Journal entries** preserve historical decisions — append only, never edit old entries
+
+### 2. User documentation (`docs/user/`)
+
+For end users — assume a **semi-technical audience who may be new to CLI tools**. This is critical.
+
+**Files:**
+- `getting-started.md` — 5-minute install-to-first-transcription guide
+- `commands.md` — complete command reference with examples
+- `configuration.md` — all settings explained with context
+- `providers.md` — provider comparison: features, pricing, languages, when to use each
+
+**User doc standards:**
+- Every doc has YAML frontmatter: `summary`, `read_when` (list of when to read this), `title`
+- Lead with the command, explain after — show what to type before explaining why
+- Use `>` blockquotes for tips, warnings, and "new to this?" asides
+- Include copy-paste-ready examples for every command and flag
+- Explain jargon when first used (e.g., "slug", "frontmatter", "editable install")
+- Troubleshooting section with common errors and plain-English fixes
+- Write for someone who can follow instructions but doesn't know CLI conventions
+
+**When to update user docs:**
+- Adding a new command → update `commands.md`, add to overview table
+- Adding a new flag → update the flags table in `commands.md`
+- Changing config options → update `configuration.md`
+- Changing onboarding flow → update `getting-started.md`
+- Adding a new platform/provider → update `providers.md` and relevant sections in other docs
+
+**Never skip user docs.** If you add a feature users interact with, the user docs must be updated in the same commit.
+
+## Adding a New Provider
+
+1. Create `src/anyscribecli/providers/<name>.py` implementing `TranscriptionProvider`
+2. Register it in `providers/__init__.py` PROVIDER_REGISTRY
+3. Add any new env vars to the onboarding wizard
+4. Update `docs/building/providers.md`
+5. Write a journal entry explaining the decision
+
+## Adding a New Downloader
+
+1. Create `src/anyscribecli/downloaders/<name>.py` implementing `AbstractDownloader`
+2. Register it in `downloaders/registry.py` DOWNLOADERS list
+3. Update URL detection regex in `registry.py`
+4. Update `docs/building/downloaders.md`
+
+## Post-Commit Checklist
+
+**After every significant commit**, follow `docs/building/COMMIT_CHECKLIST.md`. It ensures README, user docs, building docs, and version references stay in sync with code. This is mandatory — stale docs are bugs.
+
+## Versioning
+
+SemVer: `MAJOR.MINOR.PATCH`. See `BACKLOG.md` for the full version roadmap.
+
+Version lives in **one place**: `src/anyscribecli/__init__.py`. The `pyproject.toml` also has a version field that must match — update both when bumping.
+
+```bash
+# After changing version in __init__.py AND pyproject.toml:
+git add -A && git commit -m "Bump version to X.Y.Z"
+git tag vX.Y.Z
+```
+
+## Testing
+
+```bash
+pytest                    # run all tests
+ruff check src/           # lint
+ruff format src/          # format
+```
+
+## Do Not
+
+- Import from project root — use `from anyscribecli.x.y import z`
+- Hardcode paths — use `config/paths.py`
+- Skip documentation — every significant change gets a building doc entry
+- Add features beyond what was asked — lean first, expand later

anyscribecli-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rishabh Madaan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.