beyin 0.2.0__tar.gz

beyin-0.2.0/.github/ISSUE_TEMPLATE/pack-submission.yml

@@ -0,0 +1,48 @@
+name: Submit a Pack
+description: Request a new pack to be added to the beyin registry
+title: "[Pack] "
+labels: ["pack-submission"]
+body:
+  - type: input
+    id: name
+    attributes:
+      label: Pack name
+      placeholder: e.g. My Favorite Tech Podcast, Best Cooking Blog, AI Research Papers
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      placeholder: What is this pack about? Who is it for?
+    validations:
+      required: true
+
+  - type: textarea
+    id: sources
+    attributes:
+      label: Sources
+      description: YouTube video URLs or blog/article URLs — one per line
+      placeholder: |
+        https://youtube.com/watch?v=...
+        https://example.com/blog/post
+    validations:
+      required: true
+
+  - type: input
+    id: tags
+    attributes:
+      label: Tags
+      description: Comma-separated
+      placeholder: e.g. ai, podcast, science
+    validations:
+      required: false
+
+  - type: input
+    id: author
+    attributes:
+      label: Your username
+      placeholder: e.g. @username
+    validations:
+      required: false

beyin-0.2.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,7 @@
+## What does this PR do?
+
+## Why?
+
+## Testing
+- [ ] Tests pass (`uv run pytest`)
+- [ ] Tested manually

beyin-0.2.0/.github/workflows/python-publish.yml

@@ -0,0 +1,54 @@
+name: Publish Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build release distributions
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+
+      - name: Upload release distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/project/beyin/
+
+    steps:
+      - name: Download release distributions
+        uses: actions/download-artifact@v5
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

beyin-0.2.0/.gitignore

@@ -0,0 +1,22 @@
+
+.claude/
+# Python
+__pycache__/
+.pytest_cache/
+.uv-cache/
+*.py[cod]
+*.pyo
+.venv/
+*.egg-info/
+dist/
+build/
+
+# macOS
+.DS_Store
+
+# packs data
+chroma/
+
+
+# Env
+.env

beyin-0.2.0/.python-version

@@ -0,0 +1 @@
+3.11

beyin-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,95 @@
+# Contributing to beyin
+
+## Adding a pack to the registry
+
+Submitting a pack is simple: open a [Pack Submission issue](../../issues/new?template=pack-submission.yml), paste the sources, add a short description, and submit it. No fork or code required.
+
+If the pack is a good fit, it will be added to the registry.
+
+Maintainers can refer to [REGISTRY-FORMAT.md](REGISTRY-FORMAT.md) for the final pack file structure, versioning, and registry metadata format.
+
+### What makes a good pack
+
+- Focused on a clear topic or creator
+- Sources are public and unlikely to disappear
+- Description tells users what they'll be able to ask about
+- Tags help people discover it
+
+### What to prepare
+
+- A clear pack name
+- A short description
+- Public source URLs
+- A few tags if relevant
+
+### Test locally before submitting
+
+The easiest way is through an AI agent with beyin's MCP server — just say "add this pack, build it, and ask it a test question" and it handles everything.
+
+Or via terminal:
+
+```bash
+beyin add ./packs/your-pack-id.yaml
+beyin build your-pack-id
+beyin query your-pack-id "test question"
+```
+
+---
+
+## Contributing code
+
+1. Fork the repo
+2. Create a branch
+3. Make your changes and run tests: `uv run pytest`
+4. Open a PR — the template will guide you
+
+For larger changes, open an issue first to discuss the approach.
+
+---
+
+## Policy
+
+Packs in this repository contain only source manifests and metadata. beyin does not host third-party content, and all retrieval, transcription, indexing, and embedding happen locally on the user's own machine.
+
+### Allowed
+
+- Public YouTube videos and playlists
+- Public articles, websites, and RSS feeds
+- Metadata such as descriptions, tags, and contributor info
+
+### Not allowed
+
+- Full copied article text or transcripts without permission
+- Uploaded audio or video files you do not own
+- Paywalled, private, login-protected, or restricted content
+- Credentials, tokens, cookies, or session data
+- User-built embeddings or vector indexes inside packs
+
+References are fine. Hosted copies of third-party content are not.
+
+### By submitting
+
+- You confirm the sources are public or otherwise permitted to reference
+- You are not copying content you do not have permission to share
+- The information is accurate to the best of your knowledge
+
+### We may remove packs that
+
+- Spread malware or harmful material
+- Impersonate creators or brands
+- Use misleading descriptions
+- Reference illegal content
+- Primarily reproduce or mirror third-party content
+
+### Preferred sources
+
+- publicly accessible sources
+- first-party documentation
+- open-source content
+- Creative Commons or other openly licensed material
+
+### Removal requests
+
+If you are a creator or rights holder and believe a pack references your content in a way that causes harm, contact us. We may review, edit, or remove the pack as appropriate.
+
+Maintainers may reject or remove packs at their discretion.

beyin-0.2.0/PKG-INFO

@@ -0,0 +1,414 @@
+Metadata-Version: 2.4
+Name: beyin
+Version: 0.2.0
+Summary: Build local, queryable packs from videos, articles, podcasts, and files for MCP and local LLM use.
+Requires-Python: >=3.11
+Requires-Dist: chromadb>=1.5.5
+Requires-Dist: faster-whisper>=1.0
+Requires-Dist: feedparser>=6.0
+Requires-Dist: inquirerpy>=0.3.4
+Requires-Dist: mcp>=1.12.4
+Requires-Dist: mlx-whisper>=0.4; sys_platform == 'darwin'
+Requires-Dist: nltk>=3.8
+Requires-Dist: openai>=2.26.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: send2trash>=1.8
+Requires-Dist: sentence-transformers>=5.2.3
+Requires-Dist: tiktoken>=0.7
+Requires-Dist: trafilatura>=2.0.0
+Requires-Dist: typer>=0.24.1
+Requires-Dist: yt-dlp>=2025.11.12
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# beyin
+
+**Build local, queryable packs from text extracted from videos, articles, podcasts, and local files. Query them through MCP with your AI agent, or use a local model to explore them directly.**
+
+[![PyPI](https://img.shields.io/pypi/v/beyin?style=for-the-badge)](https://pypi.org/project/beyin/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/downloads/)
+[![MCP](https://img.shields.io/badge/MCP-compatible-6f42c1?style=for-the-badge)](https://modelcontextprotocol.io)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
+
+</div>
+
+## What is beyin?
+
+beyin is a local-first tool for turning useful information into queryable knowledge packs.
+
+Useful information shows up everywhere, but it rarely stays usable.
+
+You come across valuable information worth keeping, but it remains tied to the format where you found it. A video contains insights you want to reference later. An article has details you may want to use again. A saved post, note, or file can hold something important long after you first saw it.
+
+beyin was built to turn that scattered information into something structured, local, and queryable through your AI agent, so the useful parts stay accessible whenever you need them.
+
+## ✨ Features
+
+- 🎯 Multi-query expansion — generates query variants for better retrieval
+- 📦 Local-first — everything stays on your machine, nothing sent externally
+- 🔗 MCP compatible — works with Claude Code, Codex, Cursor, Windsurf, Zed and more
+- 🌍 50+ languages — multilingual embedding model out of the box
+- 🎬 Rich source support — YouTube, podcasts, PDFs, articles, local files
+- 🤖 Ollama support — use fully offline with a local model
+- ⚡ No dashboard — manage everything by just talking to your agent
+
+
+## **How it works**
+
+The easiest way to use beyin is through MCP with the AI agent you already use.
+
+1. Build a pack from your sources
+2. Connect beyin to your agent through MCP
+3. Ask questions naturally — your agent handles retrieval from your packs automatically
+
+Once connected, you do not need to run commands or manage packs manually in the terminal. You can ask your agent to:
+
+- create, build, update and manage packs
+- add new sources to a pack by providing URLs or local files
+- check your local packs and their status
+- check available packs in the pack hub
+- retrieve relevant results in response to your questions
+
+You can also query packs directly with a local model, no external API or agent needed. See [Query with a Local Model](#query-with-a-local-model).
+
+#### Supported Sources
+
+| Type | Examples |
+|------|----------|
+| Web articles | Any public URL |
+| YouTube | Videos and playlists |
+| Podcasts | RSS feed URLs |
+| Local text | `.txt`, `.md`, `.rst`, `.html` |
+| Local documents | `.pdf`, `.docx`, `.pptx`, `.epub`, `.xlsx`, `.csv` (optional deps) |
+| Local audio | `.mp3`, `.m4a`, `.wav` |
+| Local video | `.mp4`, `.mov`, `.mkv`, `.webm` |
+
+> beyin is built for local processing on your own machine. Use it with content you are allowed to process, preferably public, permitted sources or material you own or have rights to use. Avoid copied, paywalled, private, restricted, or illegally shared content.
+
+---
+
+## Quick Start
+
+### Step 1: Install
+
+```bash
+pip install beyin
+```
+
+Verify your setup:
+
+```bash
+beyin check-deps
+```
+
+**Only needed for video and audio sources. Skip if you only use articles and local text:**
+
+**yt-dlp** (any OS):
+```bash
+pip install yt-dlp
+```
+
+**ffmpeg:**
+```bash
+# macOS with Homebrew
+brew install ffmpeg
+
+# Linux
+sudo apt install ffmpeg
+
+# Windows
+winget install ffmpeg
+```
+
+No Homebrew on macOS or winget not working? Download directly from [ffmpeg.org/download.html](https://ffmpeg.org/download.html).
+
+---
+
+### Step 2: Connect to your agent
+
+You only need to do this once.
+
+#### Claude Code
+
+```bash
+claude mcp add beyin -- beyin mcp-server
+```
+
+No config file editing needed, and **no need to keep a terminal open**. Claude Code launches and manages the server process automatically. Restart Claude Code and `beyin` will appear in your MCP tools.
+
+To make it available across all your projects:
+
+```bash
+claude mcp add --scope user beyin -- beyin mcp-server
+```
+
+#### Codex (OpenAI)
+
+```bash
+codex mcp add beyin -- beyin mcp-server
+```
+
+#### Cursor
+
+Open or create `~/.cursor/mcp.json` and add:
+
+```json
+{
+  "beyin": {
+    "command": "beyin",
+    "args": ["mcp-server"]
+  }
+}
+```
+
+Or go to Command Palette → **"View: Open MCP Settings"**.
+
+#### Windsurf
+
+Open or create `~/.codeium/windsurf/mcp_config.json` and add:
+
+```json
+{
+  "mcpServers": {
+    "beyin": {
+      "command": "beyin",
+      "args": ["mcp-server"]
+    }
+  }
+}
+```
+
+Or go to Command Palette → **"MCP: Add Server"**.
+
+#### Zed
+
+In `~/.config/zed/settings.json`:
+
+```json
+{
+  "context_servers": {
+    "beyin": {
+      "source": "custom",
+      "command": "beyin",
+      "args": ["mcp-server"]
+    }
+  }
+}
+```
+
+#### Google Antigravity
+
+Go to **Manage MCP Servers** → **View raw config** and add:
+
+```json
+{
+  "mcpServers": {
+    "beyin": {
+      "command": "beyin",
+      "args": ["mcp-server"]
+    }
+  }
+}
+```
+
+#### Any other MCP-compatible agent
+
+The command is `beyin mcp-server`. It runs a stdio MCP server, compatible with any agent that supports the MCP protocol.
+
+---
+
+## Example Usage with MCP
+
+Once beyin is connected through MCP, you can talk to your agent naturally. You do not need to memorize commands or even say "beyin" every time. Just ask for what you want, and your agent can handle the pack workflow behind the scenes.
+
+> Some prompts that mention local files or folders, such as your Documents or Downloads folder, may require your AI agent to have read access to those locations first.
+
+| What you want | What to say |
+|---------------|-------------|
+| Check your packs | `List my beyin packs and show me their status.` |
+| Ask about a pack | `What's in my "mobile-marketing" pack? Show me the sources too.` |
+| Ask a question about a pack | `Any useful info about onboarding screens in my "mobile-marketing" pack?` |
+| Build a new pack | `Create a new pack called "ai-helper-tools" and add this URL I found: https://.... Then build the pack.` |
+| Add a source to an existing pack | `I have a useful PDF about how to automate my app builds. It's in my Documents folder. Add it to the "ai-helper-tools" pack and rebuild it.` |
+| Remove a source from a pack | `Show me the sources in "mobile-marketing", then remove source 2 from that pack.` |
+| Manage the response | `Ask the "ai-helper-tools" pack what I should do about designing a new landing page. Include sources in the response and any timestamps if they exist.` |
+| Remove a pack | `Remove that pack about mobile marketing stuff.` |
+
+---
+
+## MCP Tools Reference
+
+These are the tools beyin exposes to your agent. Your agent uses them automatically. You do not need to call them yourself.
+
+| Tool | What it does |
+|------|-------------|
+| `packs` | List all installed packs |
+| `status` | Show details and readiness for a pack |
+| `retrieve` | Return relevant results for a query |
+| `add` | Add a pack from a path, URL, or YAML |
+| `add_sources` | Append new sources to a pack and rebuild |
+| `remove_sources` | Remove one or more sources from a pack |
+| `build` | Build or update a pack |
+| `remove` | Remove an installed pack |
+
+---
+
+## All Commands
+
+| Command | What it does |
+|---------|-------------|
+| `beyin create` | Create a new pack interactively |
+| `beyin add <path-or-url>` | Import an existing pack from a file or URL |
+| `beyin build <pack>` | Build or rebuild a pack |
+| `beyin update <pack>` | Update a pack with new content |
+| `beyin remove <pack>` | Remove a pack |
+| `beyin list` | List all installed packs |
+| `beyin status <pack>` | Show pack details and readiness |
+| `beyin query <pack> "question"` | Ask a question directly (requires Ollama) |
+| `beyin add-source <pack> <source>` | Add a new source to an installed pack |
+| `beyin remove-source <pack> <selector>` | Remove a source from an installed pack by index or text match |
+| `beyin mcp-server` | Start the MCP server |
+| `beyin settings` | View and configure settings |
+| `beyin check-deps` | Verify runtime dependencies |
+| `beyin about` | Version and info |
+| `beyin help` | List all commands |
+
+---
+
+## Query with a Local Model
+
+You can query your packs with a local model using Ollama, without sending anything to an external API. Everything stays on your machine.
+
+> **If you use beyin through an MCP-connected agent (Claude Code, Codex, etc.), you do not need Ollama.** Your agent is the LLM. beyin just retrieves results for it.
+
+**Setup:**
+
+1. Download and install Ollama from [ollama.com](https://ollama.com)
+2. Pull a model:
+
+```bash
+ollama pull llama3.2     # 2 GB, fast, good for most queries
+ollama pull qwen2.5:7b   # 4.7 GB, stronger reasoning
+```
+
+3. Start Ollama in a terminal and keep it running:
+
+```bash
+ollama serve
+```
+
+4. In another terminal, build a pack and query it:
+
+```bash
+beyin query my-pack "What does this source say about X?"
+```
+
+To change the model, run `beyin settings`.
+
+---
+
+## Troubleshooting
+
+### Pack is not queryable yet
+
+```bash
+beyin status my-pack
+beyin build my-pack
+```
+
+A `partial` pack may still be usable. Rebuilding recovers any failed sources.
+
+### MCP is connected but retrieval is not working
+
+- Make sure the pack was built: `beyin status my-pack`
+- Restart your agent after adding beyin for the first time
+- Verify the server is registered: `claude mcp list`
+- Make sure the same beyin installation is used by both CLI and the MCP server
+
+### Video or audio builds fail
+
+- Check that `ffmpeg` is installed: `ffmpeg -version`
+- Check that `yt-dlp` is installed and current: `yt-dlp --version`
+- Make sure the source URL is still reachable
+
+### Which `python` / `pip` should I use?
+
+Use the same Python environment for installation and for the MCP server. If you installed with `pip install beyin`, running `beyin mcp-server` will use that same environment automatically.
+
+---
+
+## Development (from the repo)
+
+```bash
+git clone https://github.com/buralog/beyin.git
+cd beyin
+uv sync
+```
+
+Run commands from the repo:
+
+```bash
+uv run python -m beyin.cli help
+```
+
+MCP config for a local repo install:
+
+```bash
+claude mcp add beyin -- uv run python -m beyin.cli mcp-server --cwd /absolute/path/to/beyin
+```
+
+Or manually in your agent's config file:
+
+```json
+{
+  "mcpServers": {
+    "beyin": {
+      "command": "uv",
+      "args": ["run", "python", "-m", "beyin.cli", "mcp-server"],
+      "cwd": "/absolute/path/to/beyin"
+    }
+  }
+}
+```
+
+Run tests:
+
+```bash
+uv run pytest tests/test_cli.py tests/test_mcp_server.py
+```
+
+---
+
+## Behind the Scenes
+
+1. beyin fetches or loads your source content
+2. It extracts text or generates transcripts (for audio/video)
+3. It chunks the content into indexed segments
+4. It embeds those chunks into a local vector store
+5. At query time, it retrieves the best-matching results
+
+Everything is local. No data is sent anywhere. Packs are just files on your disk.
+
+beyin uses a multilingual embedding model by default, so it works well for non-English content too, not just English sources.
+
+---
+
+## Contributing
+
+Issues and pull requests are welcome at [github.com/buralog/beyin](https://github.com/buralog/beyin).
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for pack submissions, pack policy, and code contribution guidelines.
+
+---
+
+## Legal
+
+beyin does not host, publish, or redistribute third-party content. Public packs contain only source manifests and metadata. Any retrieval, transcription, indexing, or embedding of source material happens locally on the end user's own machine.
+
+Users are responsible for ensuring that their use of beyin complies with applicable laws, copyright rules, and the terms of service of the source platforms.
+
+
+## License
+
+MIT