Revamp README and remove emojis from documentation

+10

.env.example

··· 1 + # solstone Environment Configuration 2 + # Copy this file to .env and fill in your values 3 + 4 + # Required: Path to your journal directory 5 + JOURNAL_PATH=/path/to/your/journal 6 + 7 + # AI API Keys (at least one required) 8 + GOOGLE_API_KEY=your-google-api-key 9 + OPENAI_API_KEY=your-openai-api-key 10 + ANTHROPIC_API_KEY=your-anthropic-api-key

+11 -11

AGENTS.md

··· 2 2 3 3 This document provides comprehensive guidelines for contributing to solstone, whether you're an AI assistant, human developer, or automated system. 4 4 5 - ## 📋 Project Overview 5 + ## Project Overview 6 6 7 7 **solstone** is a Python-based AI-driven desktop journaling toolkit that provides: 8 8 ··· 15 15 16 16 --- 17 17 18 - ## 🔑 Key Concepts 18 + ## Key Concepts 19 19 20 20 Understanding these core concepts is essential for working with solstone: 21 21 ··· 33 33 34 34 --- 35 35 36 - ## 🏗️ Project Structure 36 + ## Project Structure 37 37 38 38 ``` 39 39 solstone/ ··· 62 62 63 63 --- 64 64 65 - ## 🏛️ Architecture & Data Flow 65 + ## Architecture & Data Flow 66 66 67 67 **Core Pipeline**: `observe` (capture) → JSON transcripts → `think` (analyze) → SQLite index → `convey` (web UI) 68 68 ··· 82 82 83 83 --- 84 84 85 - ## 🧪 Testing with Fixtures 85 + ## Testing with Fixtures 86 86 87 87 ```python 88 88 # Use comprehensive mock journal data for testing ··· 94 94 95 95 --- 96 96 97 - ## 💻 Coding Standards & Style 97 + ## Coding Standards & Style 98 98 99 99 ### Language & Tools 100 100 * **Black** (`make format`) - Code formatting ··· 117 117 118 118 --- 119 119 120 - ## 🧪 Testing & Quality Assurance 120 + ## Testing & Quality Assurance 121 121 122 122 ### Test Structure 123 123 * **Framework**: pytest with coverage reporting ··· 163 163 164 164 --- 165 165 166 - ## 📝 Important Development Notes 166 + ## Important Development Notes 167 167 168 168 ### Environment Management 169 169 * **JOURNAL_PATH**: The live journal path is stored in `.env`. To access it: ··· 187 187 188 188 --- 189 189 190 - ## 📦 Dependencies Management 190 + ## Dependencies Management 191 191 192 192 * **Minimize Dependencies**: Use standard library when possible 193 193 * **Production**: Add to `dependencies` in `pyproject.toml` ··· 196 196 197 197 --- 198 198 199 - ## 🎯 Development Principles 199 + ## Development Principles 200 200 201 201 * **DRY, KISS, YAGNI**: Extract common logic, prefer simple solutions, don't over-engineer 202 202 * **Single Responsibility**: Functions/classes do one thing well ··· 207 207 208 208 --- 209 209 210 - ## 🚀 Quick Reference 210 + ## Quick Reference 211 211 212 212 ### Common Commands 213 213 ```bash

+51 -133

README.md

··· 2 2 3 3 # solstone 4 4 5 - solstone is an open source project maintained by sol pbc. 6 - 7 - Navigate Work Intelligently 8 - 9 - A comprehensive Python-based AI-driven desktop journaling toolkit for multimodal capture, analysis, and intelligent navigation of workplace activities. solstone organizes captured data under a **journal** directory containing daily `YYYYMMDD` folders, enabling powerful temporal analysis and review. 10 - 11 - ## 🚀 Features 5 + Navigate Life Intelligently 12 6 13 - ### Core Modules 7 + solstone is an open source project maintained by sol pbc. 14 8 15 - - **Observe** 👁️👂 - Multimodal capture and analysis 16 - - `observer` - Screen and audio capture (auto-detects platform) 17 - - `observe-describe` - Analyzes visual changes with AI 18 - - `observe-transcribe` - Transcribes audio with AI APIs 19 - - `observe-sense` - Unified observation coordination 20 - - *Supports Linux/GNOME and macOS* 21 - 22 - - **Think** 🧠 - Data processing and insights 23 - - `think-insight` - Generates AI-powered insights and summaries 24 - - `think-cluster` - Groups related content 25 - - `think-indexer` - Builds searchable database 26 - - `think-supervisor` - Orchestrates agent workflows 27 - - `think-dream` - Full daily data pipeline 9 + A Python-based desktop journaling toolkit that captures screen and audio activity, processes it with AI, and provides intelligent navigation through a web interface. All data is organized in a local journal directory with daily folders, enabling temporal analysis and full ownership of your information. 28 10 29 - - **Convey** 🌐 - Web interface and review 30 - - `convey` - Launch web UI (with `--password` for auth) 31 - - Review facet-scoped entities, meetings, and tasks 32 - - Live transcription monitoring 33 - - Calendar view with daily summaries 11 + ## Platform Support 34 12 35 - ### Additional Tools 13 + - Linux (GNOME/X11 with PipeWire) 14 + - macOS 36 15 37 - - **MCP Server** 🛰️ - `muse-mcp-tools` launches Model Context Protocol server 38 - - **Cortex** 🧩 - `muse-cortex` provides agent-based task execution 39 - - **Help** ❓ - `solstone` lists all available commands 16 + ## Key Capabilities 40 17 41 - ## 📦 Installation 18 + - **Multimodal Capture** - Screen recording and audio capture with automatic segmentation 19 + - **AI Transcription** - Speaker-diarized audio transcription with multiple backend support 20 + - **Visual Analysis** - AI-powered screen content categorization and extraction 21 + - **Intelligent Insights** - Automated daily summaries, meeting detection, and entity extraction 22 + - **Facet Organization** - Group content by project or context (work, personal, etc.) 23 + - **Web Interface** - Review transcripts, calendar views, entity tracking, and AI chat 24 + - **Agent System** - Extensible AI agents with MCP tool integration 42 25 43 - ### Basic Installation 44 - ```bash 45 - # Install package in editable mode 46 - make install 47 - # or 48 - pip install -e . 49 - ``` 26 + ## Architecture 50 27 51 - ### Full Installation (with optional dependencies) 52 - ```bash 53 - # Install with all optional dependencies (audio/video processing) 54 - make full 55 - # or 56 - pip install -e .[full] 57 28 ``` 58 - 59 - ### Development Installation 60 - ```bash 61 - # Install with development tools 62 - make dev 63 - # or 64 - pip install -e .[dev] 29 + observe (capture) --> think (analyze) --> convey (view) 30 + | | | 31 + raw media JSON extracts Flask web UI 32 + (flac, webm) (jsonl) 33 + | 34 + muse (AI agents) 65 35 ``` 66 36 67 - ## ⚙️ Configuration 37 + ## Requirements 68 38 69 - Create a `.env` file in your project root or set these environment variables: 39 + - Python 3.10 or later 40 + - At least one AI API key (Google, OpenAI, or Anthropic) 41 + - Platform-specific dependencies for screen/audio capture 70 42 71 - ```bash 72 - # Required 73 - JOURNAL_PATH=/path/to/your/journal # Where all data is stored 74 - GOOGLE_API_KEY=your-api-key # For Gemini AI services 43 + ## Quick Start 75 44 76 - # Optional 77 - OPENAI_API_KEY=your-api-key # For OpenAI services 78 - ANTHROPIC_API_KEY=your-api-key # For Claude services 79 - ``` 80 - 81 - ## 🎯 Quick Start 82 - 83 - 1. **Set up environment**: 45 + 1. Install the package: 84 46 ```bash 85 - cp .env.example .env # If available 86 - # Edit .env with your settings 47 + pip install -e . 87 48 ``` 88 49 89 - 2. **Start capturing**: 50 + 2. Configure environment (copy `.env.example` to `.env` and add your settings): 90 51 ```bash 91 - # Use the supervisor to run all observation 92 - think-supervisor 52 + JOURNAL_PATH=/path/to/your/journal 53 + GOOGLE_API_KEY=your-api-key 93 54 ``` 94 55 95 - 3. **Process captured data**: 56 + 3. Start the supervisor (handles capture and processing): 96 57 ```bash 97 - # Run full processing pipeline for today 98 - think-dream 99 - 100 - # Or process specific date 101 - think-dream 20240101 58 + think-supervisor 102 59 ``` 103 60 104 - 4. **Review in web UI**: 61 + 4. Launch the web interface: 105 62 ```bash 106 - # Launch web interface 107 - convey --password your-password 108 - # Open http://localhost:5000 63 + convey 109 64 ``` 110 65 111 - ## 🧪 Testing 112 - 113 - ```bash 114 - # Run all tests with coverage 115 - make test 116 - 117 - # Run specific tests 118 - make test-only TEST=tests/test_utils.py 119 - 120 - # Run with verbose output 121 - make test-verbose 122 - 123 - # Generate HTML coverage report 124 - make coverage 125 - ``` 126 - 127 - ## 🔧 Development 128 - 129 - ```bash 130 - # Format code 131 - make format 132 - 133 - # Run linting checks 134 - make lint 66 + ## Documentation 135 67 136 - # Type checking 137 - make check 138 - 139 - # Run all checks before committing 140 - make check-all 141 - 142 - # Clean build artifacts 143 - make clean 144 - ``` 145 - 146 - See the [Makefile](Makefile) for all available commands or run `make help`. 68 + | Topic | Document | 69 + |-------|----------| 70 + | Journal structure and data formats | [docs/JOURNAL.md](docs/JOURNAL.md) | 71 + | Capture and observation | [docs/OBSERVE.md](docs/OBSERVE.md) | 72 + | Processing and insights | [docs/THINK.md](docs/THINK.md) | 73 + | Web interface | [docs/CONVEY.md](docs/CONVEY.md) | 74 + | App development | [docs/APPS.md](docs/APPS.md) | 75 + | AI agents and Cortex | [docs/CORTEX.md](docs/CORTEX.md) | 76 + | Message bus protocol | [docs/CALLOSUM.md](docs/CALLOSUM.md) | 77 + | Troubleshooting | [docs/DOCTOR.md](docs/DOCTOR.md) | 147 78 148 - ## 📚 Documentation 79 + ## Development 149 80 150 - - [AGENTS.md](AGENTS.md) - Development guidelines and coding standards 151 - - [docs/](docs/) - All other documentation: 152 - - [JOURNAL.md](docs/JOURNAL.md) - Journal directory structure and data organization 153 - - [CORTEX.md](docs/CORTEX.md) - Agent system documentation 154 - - [OBSERVE.md](docs/OBSERVE.md) - Multimodal capture and analysis 155 - - [THINK.md](docs/THINK.md) - Data processing and AI analysis 156 - - [CONVEY.md](docs/CONVEY.md) - Web interface and app development 81 + See [AGENTS.md](AGENTS.md) for development guidelines, coding standards, and testing instructions. 157 82 158 - ## 🤝 Contributing 83 + ## Contributing 159 84 160 - Please read [CONTRIBUTING.md](CONTRIBUTING.md) for contribution terms and [AGENTS.md](AGENTS.md) for development guidelines. 85 + See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution terms. 161 86 162 87 ## License 163 88 164 - This project is licensed under the GNU Affero General Public License v3.0 165 - (AGPL-3.0-only). 166 - 167 - If you modify this software and allow users to interact with it over a network, 168 - you must make the complete corresponding source code of your modified version 169 - available to those users under the same license. 170 - 171 - See the LICENSE file for details. 89 + This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-only). See [LICENSE](LICENSE) for details.

Configure Feed

Configure Feed