vaultmind 0.1.0__tar.gz

vaultmind-0.1.0/.env.example

@@ -0,0 +1,9 @@
+# AI Provider Keys — at least one required
+ANTHROPIC_API_KEY=sk-ant-...
+# OPENAI_API_KEY=sk-...
+
+# Optional: GitHub token for higher rate limits
+# GITHUB_TOKEN=ghp_...
+
+# Optional: Ollama runs locally, no key needed
+# OLLAMA_BASE_URL=http://localhost:11434

vaultmind-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Secrets
+.env
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+
+# uv
+uv.lock
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+
+# Logs
+*.log
+
+# Config (user-specific)
+config.yaml
+
+# Markdown files (except README.md)
+PRD.md
+COMPLETE_PROJECT_GUIDE.md
+PHASE3_IMPLEMENTATION_REPORT.md

vaultmind-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Rajya Vardhan Singh
+
+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.

vaultmind-0.1.0/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: vaultmind
+Version: 0.1.0
+Summary: Your personal AI-powered second brain. Feed it anything. Find everything.
+Author-email: Rajya Vardhan Singh <imrajyavardhan12@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,cli,knowledge-management,obsidian,second-brain
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.11
+Requires-Dist: anthropic>=0.52.0
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: structlog>=24.0.0
+Requires-Dist: tenacity>=9.0.0
+Requires-Dist: textual>=0.70.0
+Requires-Dist: trafilatura>=2.0.0
+Requires-Dist: typer>=0.15.0
+Description-Content-Type: text/markdown
+
+# VaultMind
+
+> Your personal AI-powered second brain. Feed it anything. Find everything.
+
+A CLI tool that sits between the internet and your [Obsidian](https://obsidian.md) vault. Give it a URL — an article, GitHub repo, Reddit post, or tweet — and it extracts the content, processes it through AI, and writes a beautifully structured, interlinked Markdown note into your vault.
+
+## Quick Start
+
+```bash
+# Install
+uv pip install -e .
+
+# Configure
+cp .env.example .env              # Add your API keys
+cp config.example.yaml config.yaml  # Set your vault path
+
+# Save your first note
+vm save https://example.com/article
+```
+
+## Commands
+
+### `vm save <url>`
+
+The core command. Processes any supported URL through the full pipeline:
+
+1. **Detects** the source type (article, Reddit, GitHub, tweet)
+2. **Extracts** clean content (strips ads, nav, tracking params)
+3. **Enriches** via AI — summary, key ideas, quotes, counterarguments, tags, rating
+4. **Generates** flashcards and finds related notes already in your vault
+5. **Writes** an atomic Markdown file with YAML frontmatter to the correct vault folder
+
+```bash
+vm save https://github.com/astral-sh/uv
+vm save https://www.reddit.com/r/MachineLearning/comments/abc123/some_post
+vm save https://example.com/blog/great-article
+
+# Options
+vm save <url> --tag cli --tag python   # Add extra tags
+vm save <url> --folder "📚 Sources/AI" # Override folder routing
+vm save <url> --force                  # Re-process even if already saved
+vm save <url> --no-flash               # Skip flashcard generation
+vm save <url> --verbose                # Debug logging to stderr
+```
+
+**Duplicate detection:** If a URL was already saved, VaultMind skips it (use `--force` to re-process). Passing `--tag` on a duplicate merges the new tags into the existing note.
+
+### `vm find [query]`
+
+Search across all saved notes by keyword or fuzzy match. Without a query, shows recent notes.
+
+```bash
+vm find "transformer architecture"
+vm find                              # Show recent notes
+vm find "rust" --limit 10
+```
+
+Scoring weights: exact title match (60), tag match (40), body match (20), plus Jaccard similarity and fuzzy title matching.
+
+### `vm brief`
+
+Generate a weekly digest summarizing what you've saved recently. Uses the **fast** AI tier.
+
+```bash
+vm brief              # Last 7 days
+vm brief --days 14    # Last 14 days
+vm brief --limit 30   # Include up to 30 notes
+```
+
+Output includes themes, highlights, gaps in your reading, and suggested next steps.
+
+### `vm digest <topic>`
+
+Deep synthesis on a specific topic across your entire vault. Uses the **deep** AI tier. Automatically generates a Map of Content (MOC) file when 5+ notes match.
+
+```bash
+vm digest "AI safety"
+vm digest "rust" --no-moc    # Skip MOC generation
+vm digest "design" --limit 20
+```
+
+### `vm reflect`
+
+A weekly thinking mirror — surfaces patterns, belief shifts, tensions, and blind spots in your saves. Uses the **deep** AI tier.
+
+```bash
+vm reflect              # Last 7 days
+vm reflect --days 30    # Last 30 days
+```
+
+### `vm flashcard`
+
+Quiz yourself on flashcards auto-generated from your saved notes. No AI call needed — cards are parsed from the `## 🃏 Flashcards` section already embedded in each note.
+
+```bash
+vm flashcard                    # All cards, shuffled
+vm flashcard --topic "AI"       # Filter by topic
+vm flashcard --limit 10         # Cap at 10 cards
+```
+
+Interactive controls: `space` flip · `n` next · `p` previous · `k` known · `u` unsure · `q` quit
+
+### `vm stats`
+
+Vault health dashboard — total notes, breakdown by type and status, top tags, average rating, flashcard coverage, and MOC candidates.
+
+```bash
+vm stats
+```
+
+### `vm version`
+
+Show the current VaultMind version.
+
+## Supported Sources
+
+| Source | Extractor | What You Get |
+|---|---|---|
+| **Articles / Blogs** | [trafilatura](https://github.com/adbar/trafilatura) | Clean text, author, publication, reading time |
+| **GitHub Repos** | GitHub REST API | Tool Card format — description, stars, language, README summary |
+| **Reddit Posts** | Reddit JSON API | Post + top 5 comments, discussion summary, subreddit as tag |
+| **Twitter / X** | Syndication API + trafilatura fallback | Best-effort extraction (experimental, marked as partial on failure) |
+
+## Configuration
+
+### `config.yaml`
+
+```yaml
+vault_path: "/path/to/your/Obsidian Vault"
+
+folders:
+  inbox: "📥 Inbox"
+  articles: "📚 Sources"
+  tools: "🛠️ Tools"
+  threads: "🐦 Threads"
+  discussions: "💬 Discussions"
+  # ... see config.example.yaml for all options
+
+ai:
+  default_provider: "anthropic"        # anthropic | openai | ollama
+  fallback_chain: ["anthropic", "openai", "ollama"]
+  max_tokens: 2000
+  generate_flashcards: true
+  generate_counterarguments: true
+  providers:
+    anthropic:
+      models:
+        fast: "claude-sonnet-4-20250514"       # Used by: save, brief
+        deep: "claude-opus-4-5"     # Used by: digest, reflect
+    openai:
+      models:
+        fast: "gpt-4.1-mini"
+        deep: "gpt-4.1"
+```
+
+### `.env`
+
+```bash
+# At least one AI provider key is required
+ANTHROPIC_API_KEY=sk-ant-...
+OPENAI_API_KEY=sk-...
+
+# Optional: higher GitHub API rate limits
+GITHUB_TOKEN=ghp_...
+```
+
+## Project Structure
+
+```
+src/vaultmind/
+├── main.py              # CLI entry point (typer)
+├── config.py            # Pydantic settings (config.yaml + .env)
+├── schemas.py           # Pipeline data models
+├── core/
+│   ├── router.py        # URL detection & canonicalization
+│   ├── extractors.py    # Dispatcher to source-specific extractors
+│   ├── scraper.py       # Article extraction (trafilatura)
+│   ├── reddit.py        # Reddit JSON API client
+│   ├── github.py        # GitHub REST API client
+│   ├── twitter.py       # Twitter syndication + fallback
+│   ├── renderers.py     # Source-specific Markdown body renderers
+│   ├── writer.py        # Atomic vault file writer
+│   ├── linker.py        # Related note finder (Jaccard similarity)
+│   ├── vault_index.py   # Vault scanner for Phase 4 commands
+│   ├── search.py        # Keyword & fuzzy search engine
+│   ├── flashcards.py    # Flashcard parser from note bodies
+│   └── moc.py           # Map of Content generator
+├── ai/
+│   ├── pipeline.py      # Content → AIEnrichment flow
+│   ├── prompts.py       # All prompt templates (provider-agnostic)
+│   ├── knowledge.py     # Brief / Digest / Reflect synthesis
+│   ├── json_utils.py    # JSON response cleanup
+│   └── providers/       # Anthropic, OpenAI, Ollama (stub)
+├── commands/            # One file per CLI command
+└── utils/               # Display, hashing, URLs, tags, logging
+```
+
+## Tech Stack
+
+- **CLI:** [Typer](https://typer.tiangolo.com) + [Rich](https://rich.readthedocs.io)
+- **AI:** Anthropic SDK, OpenAI SDK (provider-agnostic via Protocol)
+- **Extraction:** [trafilatura](https://github.com/adbar/trafilatura), [httpx](https://www.python-httpx.org)
+- **Data:** [Pydantic](https://docs.pydantic.dev) models, YAML frontmatter
+- **Resilience:** [tenacity](https://tenacity.readthedocs.io) retries with exponential backoff
+- **Logging:** [structlog](https://www.structlog.org) (JSON to file, human-readable in verbose mode)
+- **Package manager:** [uv](https://github.com/astral-sh/uv)
+
+## Requirements
+
+- Python ≥ 3.11
+- An Anthropic or OpenAI API key
+- An Obsidian vault directory
+
+See [PRD.md](PRD.md) for the full project blueprint.

vaultmind-0.1.0/README.md

@@ -0,0 +1,214 @@
+# VaultMind
+
+> Your personal AI-powered second brain. Feed it anything. Find everything.
+
+A CLI tool that sits between the internet and your [Obsidian](https://obsidian.md) vault. Give it a URL — an article, GitHub repo, Reddit post, or tweet — and it extracts the content, processes it through AI, and writes a beautifully structured, interlinked Markdown note into your vault.
+
+## Quick Start
+
+```bash
+# Install
+uv pip install -e .
+
+# Configure
+cp .env.example .env              # Add your API keys
+cp config.example.yaml config.yaml  # Set your vault path
+
+# Save your first note
+vm save https://example.com/article
+```
+
+## Commands
+
+### `vm save <url>`
+
+The core command. Processes any supported URL through the full pipeline:
+
+1. **Detects** the source type (article, Reddit, GitHub, tweet)
+2. **Extracts** clean content (strips ads, nav, tracking params)
+3. **Enriches** via AI — summary, key ideas, quotes, counterarguments, tags, rating
+4. **Generates** flashcards and finds related notes already in your vault
+5. **Writes** an atomic Markdown file with YAML frontmatter to the correct vault folder
+
+```bash
+vm save https://github.com/astral-sh/uv
+vm save https://www.reddit.com/r/MachineLearning/comments/abc123/some_post
+vm save https://example.com/blog/great-article
+
+# Options
+vm save <url> --tag cli --tag python   # Add extra tags
+vm save <url> --folder "📚 Sources/AI" # Override folder routing
+vm save <url> --force                  # Re-process even if already saved
+vm save <url> --no-flash               # Skip flashcard generation
+vm save <url> --verbose                # Debug logging to stderr
+```
+
+**Duplicate detection:** If a URL was already saved, VaultMind skips it (use `--force` to re-process). Passing `--tag` on a duplicate merges the new tags into the existing note.
+
+### `vm find [query]`
+
+Search across all saved notes by keyword or fuzzy match. Without a query, shows recent notes.
+
+```bash
+vm find "transformer architecture"
+vm find                              # Show recent notes
+vm find "rust" --limit 10
+```
+
+Scoring weights: exact title match (60), tag match (40), body match (20), plus Jaccard similarity and fuzzy title matching.
+
+### `vm brief`
+
+Generate a weekly digest summarizing what you've saved recently. Uses the **fast** AI tier.
+
+```bash
+vm brief              # Last 7 days
+vm brief --days 14    # Last 14 days
+vm brief --limit 30   # Include up to 30 notes
+```
+
+Output includes themes, highlights, gaps in your reading, and suggested next steps.
+
+### `vm digest <topic>`
+
+Deep synthesis on a specific topic across your entire vault. Uses the **deep** AI tier. Automatically generates a Map of Content (MOC) file when 5+ notes match.
+
+```bash
+vm digest "AI safety"
+vm digest "rust" --no-moc    # Skip MOC generation
+vm digest "design" --limit 20
+```
+
+### `vm reflect`
+
+A weekly thinking mirror — surfaces patterns, belief shifts, tensions, and blind spots in your saves. Uses the **deep** AI tier.
+
+```bash
+vm reflect              # Last 7 days
+vm reflect --days 30    # Last 30 days
+```
+
+### `vm flashcard`
+
+Quiz yourself on flashcards auto-generated from your saved notes. No AI call needed — cards are parsed from the `## 🃏 Flashcards` section already embedded in each note.
+
+```bash
+vm flashcard                    # All cards, shuffled
+vm flashcard --topic "AI"       # Filter by topic
+vm flashcard --limit 10         # Cap at 10 cards
+```
+
+Interactive controls: `space` flip · `n` next · `p` previous · `k` known · `u` unsure · `q` quit
+
+### `vm stats`
+
+Vault health dashboard — total notes, breakdown by type and status, top tags, average rating, flashcard coverage, and MOC candidates.
+
+```bash
+vm stats
+```
+
+### `vm version`
+
+Show the current VaultMind version.
+
+## Supported Sources
+
+| Source | Extractor | What You Get |
+|---|---|---|
+| **Articles / Blogs** | [trafilatura](https://github.com/adbar/trafilatura) | Clean text, author, publication, reading time |
+| **GitHub Repos** | GitHub REST API | Tool Card format — description, stars, language, README summary |
+| **Reddit Posts** | Reddit JSON API | Post + top 5 comments, discussion summary, subreddit as tag |
+| **Twitter / X** | Syndication API + trafilatura fallback | Best-effort extraction (experimental, marked as partial on failure) |
+
+## Configuration
+
+### `config.yaml`
+
+```yaml
+vault_path: "/path/to/your/Obsidian Vault"
+
+folders:
+  inbox: "📥 Inbox"
+  articles: "📚 Sources"
+  tools: "🛠️ Tools"
+  threads: "🐦 Threads"
+  discussions: "💬 Discussions"
+  # ... see config.example.yaml for all options
+
+ai:
+  default_provider: "anthropic"        # anthropic | openai | ollama
+  fallback_chain: ["anthropic", "openai", "ollama"]
+  max_tokens: 2000
+  generate_flashcards: true
+  generate_counterarguments: true
+  providers:
+    anthropic:
+      models:
+        fast: "claude-sonnet-4-20250514"       # Used by: save, brief
+        deep: "claude-opus-4-5"     # Used by: digest, reflect
+    openai:
+      models:
+        fast: "gpt-4.1-mini"
+        deep: "gpt-4.1"
+```
+
+### `.env`
+
+```bash
+# At least one AI provider key is required
+ANTHROPIC_API_KEY=sk-ant-...
+OPENAI_API_KEY=sk-...
+
+# Optional: higher GitHub API rate limits
+GITHUB_TOKEN=ghp_...
+```
+
+## Project Structure
+
+```
+src/vaultmind/
+├── main.py              # CLI entry point (typer)
+├── config.py            # Pydantic settings (config.yaml + .env)
+├── schemas.py           # Pipeline data models
+├── core/
+│   ├── router.py        # URL detection & canonicalization
+│   ├── extractors.py    # Dispatcher to source-specific extractors
+│   ├── scraper.py       # Article extraction (trafilatura)
+│   ├── reddit.py        # Reddit JSON API client
+│   ├── github.py        # GitHub REST API client
+│   ├── twitter.py       # Twitter syndication + fallback
+│   ├── renderers.py     # Source-specific Markdown body renderers
+│   ├── writer.py        # Atomic vault file writer
+│   ├── linker.py        # Related note finder (Jaccard similarity)
+│   ├── vault_index.py   # Vault scanner for Phase 4 commands
+│   ├── search.py        # Keyword & fuzzy search engine
+│   ├── flashcards.py    # Flashcard parser from note bodies
+│   └── moc.py           # Map of Content generator
+├── ai/
+│   ├── pipeline.py      # Content → AIEnrichment flow
+│   ├── prompts.py       # All prompt templates (provider-agnostic)
+│   ├── knowledge.py     # Brief / Digest / Reflect synthesis
+│   ├── json_utils.py    # JSON response cleanup
+│   └── providers/       # Anthropic, OpenAI, Ollama (stub)
+├── commands/            # One file per CLI command
+└── utils/               # Display, hashing, URLs, tags, logging
+```
+
+## Tech Stack
+
+- **CLI:** [Typer](https://typer.tiangolo.com) + [Rich](https://rich.readthedocs.io)
+- **AI:** Anthropic SDK, OpenAI SDK (provider-agnostic via Protocol)
+- **Extraction:** [trafilatura](https://github.com/adbar/trafilatura), [httpx](https://www.python-httpx.org)
+- **Data:** [Pydantic](https://docs.pydantic.dev) models, YAML frontmatter
+- **Resilience:** [tenacity](https://tenacity.readthedocs.io) retries with exponential backoff
+- **Logging:** [structlog](https://www.structlog.org) (JSON to file, human-readable in verbose mode)
+- **Package manager:** [uv](https://github.com/astral-sh/uv)
+
+## Requirements
+
+- Python ≥ 3.11
+- An Anthropic or OpenAI API key
+- An Obsidian vault directory
+
+See [PRD.md](PRD.md) for the full project blueprint.

vaultmind-0.1.0/config.example.yaml

@@ -0,0 +1,40 @@
+vault_path: "/Users/rvs/Obsidian Vault"
+
+folders:
+  inbox: "📥 Inbox"
+  articles: "📚 Sources"
+  tools: "🛠️ Tools"
+  threads: "🐦 Threads"
+  discussions: "💬 Discussions"
+  flashcards: "🃏 Flashcards"
+  digests: "📊 Digests"
+  mocs: "🗺️ MOCs"
+  ideas: "💡 Ideas"
+  meta: "⚙️ Meta"
+
+ai:
+  default_provider: "openai"
+  fallback_chain: ["openai", "anthropic", "ollama"]
+  max_tokens: 2000
+  generate_flashcards: true
+  generate_counterarguments: true
+  rating: true
+  providers:
+    anthropic:
+      models:
+        fast: "claude-sonnet-4-20250514"
+        deep: "claude-opus-4-5"
+    openai:
+      models:
+        fast: "gpt-4.1-mini"
+        deep: "gpt-4.1"
+    ollama:
+      base_url: "http://localhost:11434"
+      models:
+        fast: "llama3"
+        deep: "llama3"
+
+preferences:
+  default_status: "processed"
+  open_after_save: false
+  notify_on_save: true

vaultmind-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "vaultmind"
+version = "0.1.0"
+description = "Your personal AI-powered second brain. Feed it anything. Find everything."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Rajya Vardhan Singh", email = "imrajyavardhan12@gmail.com" }]
+keywords = ["obsidian", "second-brain", "ai", "cli", "knowledge-management"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Text Processing :: Markup :: Markdown",
+]
+dependencies = [
+    "typer>=0.15.0",
+    "rich>=13.0.0",
+    "textual>=0.70.0",
+    "httpx>=0.28.0",
+    "trafilatura>=2.0.0",
+    "anthropic>=0.52.0",
+    "openai>=1.0.0",
+    "pydantic>=2.0.0",
+    "pydantic-settings>=2.0.0",
+    "python-dotenv>=1.0.0",
+    "tenacity>=9.0.0",
+    "structlog>=24.0.0",
+    "pyyaml>=6.0.0",
+]
+
+[project.scripts]
+vm = "vaultmind.main:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vaultmind"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

vaultmind-0.1.0/ruff.toml

@@ -0,0 +1,10 @@
+target-version = "py311"
+line-length = 100
+src = ["src"]
+
+[lint]
+select = ["E", "F", "I", "N", "W", "UP", "B", "SIM", "RUF"]
+
+[format]
+quote-style = "double"
+indent-style = "space"

vaultmind-0.1.0/src/vaultmind/__init__.py

@@ -0,0 +1,3 @@
+"""VaultMind — Your personal AI-powered second brain."""
+
+__version__ = "0.1.0"

vaultmind-0.1.0/src/vaultmind/ai/__init__.py

@@ -0,0 +1 @@
+

vaultmind-0.1.0/src/vaultmind/ai/json_utils.py

@@ -0,0 +1,21 @@
+"""Shared JSON response cleanup for AI providers."""
+
+from __future__ import annotations
+
+
+def clean_json_response(response: str) -> str:
+    """Clean fenced/annotated JSON responses into plain JSON text."""
+    cleaned = response.strip()
+
+    if cleaned.startswith("```"):
+        lines = cleaned.splitlines()
+        if lines and lines[0].startswith("```"):
+            lines = lines[1:]
+        if lines and lines[-1].strip().startswith("```"):
+            lines = lines[:-1]
+        cleaned = "\n".join(lines).strip()
+
+    if cleaned.lower().startswith("json"):
+        cleaned = cleaned[4:].strip()
+
+    return cleaned