BrainerAI

The Active Learning Workspace

Transform passive learning into active knowledge with AI-powered organization

Features • Installation • Usage • Documentation • Contributing

---

Overview

BrainerAI is a desktop learning workspace that helps you capture and organize web content. It combines a PyQt6 desktop application with a browser extension to clip content from any website, organize it into learning paths, and optionally use AI for tagging and flashcard generation.

Key Features

Web Content Clipping Browser extension for capturing text, code, and videos Automatic metadata extraction from web pages YouTube timestamp support Learning Paths Organize clips by topic with custom colors Rich content viewer with syntax highlighting Full-text search across all content

AI Integration (Optional) Auto-generate relevant tags using GPT-3.5 Create flashcards for active recall Content categorization and analysis Local-First Architecture All data stored locally as JSON Flask REST API for extension communication Cross-platform: Windows, macOS, Linux

---

Architecture Overview

                                      ┌──────────────────────────────┐
                                      │    Browser Extension         │
                                      │    (Manifest V3)             │
                                      │    Chrome/Edge               │
                                      └──────────────┬───────────────┘
                                                    │
                                              HTTP REST API
                                                    │
                                                    ▼
                                      ┌──────────────────────────────┐
                                      │  Flask Local Server          │
                                      │  (localhost:5050)            │
                                      └──────┬─────────────────┬─────┘
                                            │                 │
                                            │                 │
                                    ┌────────▼─────┐   ┌──────▼────────┐
                                    │  PyQt6 GUI   │   │  AI Engine    │
                                    │  Desktop App │   │  (OpenAI API) │
                                    └────────┬─────┘   └───────────────┘
                                            │
                                            │
                                    ┌────────▼─────────┐
                                    │  JSON Storage    │
                                    │  (Local Files)   │
                                    └──────────────────┘

Core Components:

Component	Technology	Purpose
Desktop Application	PyQt6	Main GUI interface with modern styling
Browser Extension	JavaScript ES6+	Web content capture (Manifest V3)
Local API Server	Flask + CORS	Bridge between extension and desktop
AI Engine	OpenAI GPT-3.5	Optional intelligent features
Data Storage	JSON	Lightweight, portable persistence

Installation

Prerequisites

Ensure you have Python 3.8 or higher installed. We recommend using uv for faster dependency installation.

Quick Setup

1. Clone the Repository

git clone https://github.com/yourusername/brainerai.git
cd brainerai

2. Install Dependencies

# Using uv (recommended for speed)
uv pip install -r requirements.txt

# Or using standard pip
pip install -r requirements.txt

3. Launch Application

python main.py

The desktop application will launch and automatically start the local API server on port 5050.

---

Browser Extension Setup

Installation Steps:

1. Open your browser (Chrome or Edge)
2. Navigate to chrome://extensions/
3. Enable Developer mode (toggle in top-right)
4. Click Load unpacked
5. Select the extension folder from the project directory
6. Pin the extension icon to your toolbar for easy access

---

OpenAI Configuration (Optional)

To enable AI-powered features:

Step	Action
1	Get API key from OpenAI Platform
2	Launch BrainerAI desktop app
3	Go to File → Settings
4	Paste your API key and save

Note: The application works fully without AI features. OpenAI integration is optional for enhanced functionality.

---

Usage

Creating Learning Paths

Organize your knowledge by creating themed learning paths:

1. Click "+ New Learning Path" in the sidebar
2. Enter a descriptive name (e.g., "Machine Learning", "Python Basics")
3. Choose a color for visual identification
4. Add optional description for context

Capturing Web Content

From Any Webpage:

1. Select the text, code, or content you want to save
2. Click the BrainerAI extension icon in your browser
3. Choose content type:
   • TEXT - Articles, documentation, blog posts
   • VIDEO - YouTube tutorials with timestamps
   • CODE - Code snippets and examples
4. Select target learning path
5. Click "SAVE CLIP"

The extension automatically captures metadata including source URL, page title, and timestamps for videos.

AI-Enhanced Features

Right-click any clip to access:

Feature	Description	Benefit
Generate Tags	AI analyzes content and suggests 3-5 relevant tags	Better organization and searchability
Generate Flashcards	Creates Q&A pairs from clip content	Active recall for better retention

Keyboard Shortcuts

Shortcut	Action
Ctrl + F	Open global search dialog
Ctrl + N	Create new learning path
Ctrl + ,	Open settings
F5	Refresh all data
Ctrl + Q	Quit application

---

Technology Stack

Core Technologies

Technology	Purpose	Version
	Application core	3.8+
	Desktop GUI	6.x
	REST API	3.x
	AI Features	GPT-3.5

Key Dependencies

# GUI Framework
PyQt6              # Cross-platform desktop interface
PyQt6-WebEngine    # Web content rendering

# Backend
Flask              # Local API server
flask-cors         # Cross-origin support

# AI & Utilities
openai             # OpenAI API client
requests           # HTTP requests

# Distribution
pyinstaller        # Executable bundling

Project Structure

BrainerAI/
├── assets/              # Icons and screenshots
├── data/                # JSON storage
│   ├── clips/
│   ├── config.json
│   └── learning_paths.json
├── extension/           # Browser extension
│   ├── manifest.json
│   ├── popup.html/js
│   ├── content.js
│   └── background.js
├── src/
│   ├── api/            # Flask server
│   ├── core/           # AI engine, file storage
│   ├── gui/            # PyQt6 UI
│   └── utils/          # Helper functions
├── config.py
├── main.py
└── requirements.txt

---

Building Executable

Create standalone executables for distribution:

python build_exe.py

Output Locations:

• Windows: dist/BrainerAI.exe
• macOS: dist/BrainerAI.app
• Linux: dist/BrainerAI

The build includes Python runtime, all dependencies, and application assets. No installation required.

---

Data Storage

BrainerAI uses a simple, portable JSON-based storage system:

File	Content	Purpose
data/learning_paths.json	Learning path metadata	Stores path names, colors, descriptions
data/clips/path_{id}.json	Clips for each path	Individual clip content and metadata
data/config.json	User settings	API keys, preferences

Benefits:

• Human-readable format for easy inspection
• Portable - copy data/ folder to backup or migrate
• No database setup required
• Privacy-first - all data stays local

---

API Reference

The local Flask server runs on http://localhost:5050 and provides:

Available Endpoints

Endpoint	Method	Description	Response
/health	GET	Server health check	{"status": "ok", "app": "BrainerAI"}
/learning-paths	GET	List all learning paths	Array of path objects
/clips	POST	Create new clip	{"id": int, "message": "..."}
/clips/{path_id}/{clip_id}	GET	Retrieve specific clip	Clip object with details
/stats	GET	Application statistics	{"learning_paths": int, "clips": int}

Example Request:

curl -X POST http://localhost:5050/clips \
  -H "Content-Type: application/json" \
  -d '{
    "learning_path_id": 1,
    "clip_type": "text",
    "content": "Your content here",
    "title": "Clip Title",
    "auto_tag": true
  }'

---

Roadmap

Planned Features:

• Spaced repetition system for flashcards
• Export learning paths to Markdown/PDF
• Integrated video player with timestamp navigation
• Dark mode theme
• Optional cloud synchronization
• Import from Notion/Obsidian
• Mobile companion app

---

Contributing

Contributions are welcome! Here's how you can help:

Ways to Contribute

Type	How to Help
Report Bugs	Open an issue with steps to reproduce
Suggest Features	Open an issue with your idea and use case
Submit Code	Fork → Create branch → Make changes → PR
Improve Docs	Fix typos, add examples, clarify instructions

---

License

MIT License

Copyright (c) 2025 BrainerAI Contributors

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.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

See LICENSE file for full details.

---

Built for learners, by learners

⬆ Back to Top