Skip to content

Commit 591c52b

Browse files
raoldclaude
raold
and
claude
committed
feat: Add comprehensive photo processing pipeline with web dashboard
- Moved photo processor to app/services/photo_processor.py - Created web dashboard with real-time monitoring at /photo-pipeline - Added HEIC to JPEG conversion support - Integrated LLaVA 1.6 34B for AI image descriptions - WebSocket-based live progress updates with pause/resume - Performance metrics tracking (currently ~0.06 img/s with LLaVA 34B) - Processes Google Photos Takeout exports with CLIP embeddings Note: Full processing of 57k+ images takes ~12 days with LLaVA analysis Consider reducing LLaVA sampling rate or using smaller model for speed Co-Authored-By: Claude <[email protected]>
1 parent fd52547 commit 591c52b

File tree

5 files changed

+1305
-1
lines changed

5 files changed

+1305
-1
lines changed

‎.claude/settings.local.json‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,25 @@
9090
"Bash(cmd.exe:*)",
9191
"WebFetch(domain:huggingface.co)",
9292
"Bash(git mv:*)",
93-
"Bash(sed:*)"
93+
"Bash(sed:*)",
94+
"Bash(.venvScriptsactivate)",
95+
"Bash(python:*)",
96+
"Bash(docker ps:*)",
97+
"Bash(docker-compose:*)",
98+
"Bash(.venvScriptspython scriptsrun_dev.py)",
99+
"WebFetch(domain:docs.anthropic.com)",
100+
"WebSearch",
101+
"Bash(powershell:*)",
102+
"Bash(.venv\\Scripts\\pip.exe install:*)",
103+
"Bash(wsl docker-compose:*)",
104+
"Bash(wsl service docker:*)",
105+
"Bash(dir:*)",
106+
"Bash(.venvScriptspython.exe clip_api.py)",
107+
"Bash(.venv\\Scripts\\python.exe services\\gpu\\clip\\clip_api.py:*)",
108+
"Bash(wsl python3:*)",
109+
"Bash(wsl ip route:*)",
110+
"Bash(wsl ls:*)",
111+
"Bash(docker exec:*)"
94112
],
95113
"deny": []
96114
}

‎CLAUDE.md‎

Lines changed: 234 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
# Second Brain Project Context
2+
3+
## Project Overview
4+
Second Brain v5.0 - A **100% local AI-powered** knowledge management system with multimodal search, Google Drive integration, and knowledge graph visualization. NO API KEYS REQUIRED for core functionality.
5+
6+
## Development Environment
7+
8+
### Quick Setup
9+
1. **Virtual Environment**: Project uses `.venv` - Claude will activate it automatically
10+
2. **Default Port**: 8001 for development server (8000 for Docker)
11+
3. **Database**: SQLite/mock for quick dev, PostgreSQL for full stack
12+
13+
### Key Commands
14+
```bash
15+
# Start development server (port 8001)
16+
python scripts/run_dev.py # Uses SQLite/mock mode
17+
18+
# Docker operations (when needed)
19+
docker-compose up -d # Full stack with PostgreSQL
20+
docker-compose logs -f app # View logs
21+
docker-compose down # Stop services
22+
23+
# Testing
24+
pytest tests/unit/ -v # Unit tests
25+
make test-smoke # Quick smoke tests (<60s)
26+
make test-fast # Core tests (<5min)
27+
28+
# Code quality
29+
make format # Auto-format code
30+
make lint # Run linters
31+
```
32+
33+
### Platform Optimizations
34+
35+
#### Windows 11 with WSL2
36+
- **Docker Management**: Always use `wsl docker-compose` for better performance
37+
- **File Operations**: Consider `wsl` prefix for grep, find, and other Unix tools
38+
- **PostgreSQL**: Run `wsl psql` for database access
39+
- **Performance**: WSL2 provides near-native Linux performance for containers
40+
41+
Example Windows workflow:
42+
```bash
43+
# Use WSL2 for Docker (faster, more reliable)
44+
wsl docker-compose up -d
45+
wsl docker ps
46+
wsl docker-compose logs -f app
47+
48+
# But use native Windows for Python (better IDE integration)
49+
.venv\Scripts\python.exe scripts\run_dev.py
50+
```
51+
52+
#### All Platforms
53+
- **Direct Python paths** work best (`.venv/Scripts/python.exe` on Windows, `.venv/bin/python` on Unix)
54+
- **Port Conflicts**: Check with `netstat` (Windows) or `lsof` (Unix)
55+
56+
## Common Platform Pitfalls & Solutions
57+
58+
### Issue: "command not found" errors
59+
- **Windows**: You're in Git Bash, use `cmd.exe /c` for Windows commands or `wsl` for Linux commands
60+
- **Solution**: `.venv\Scripts\python.exe` or `wsl python3`
61+
62+
### Issue: Docker commands fail on Windows
63+
- **Cause**: Docker Desktop runs in WSL2
64+
- **Solution**: ALWAYS prefix with `wsl`: `wsl docker-compose up -d`
65+
66+
### Issue: Path separator confusion
67+
- **Windows**: Use backslashes `\` or raw strings
68+
- **Mac/Linux**: Use forward slashes `/`
69+
- **Solution**: Let Claude detect platform and use correct separators
70+
71+
### Issue: .env file encoding problems
72+
- **Windows**: Often saves as UTF-16 or with BOM
73+
- **Solution**: Save as UTF-8 without BOM in VS Code/Notepad++
74+
75+
### Issue: Port already in use
76+
- **Windows**: `cmd.exe /c "netstat -ano | findstr :8001"` then `taskkill /PID <pid> /F`
77+
- **Mac/Linux**: `lsof -i :8001` then `kill -9 <pid>`
78+
79+
### Issue: venv activation doesn't persist
80+
- **All platforms**: Just use direct paths: `.venv\Scripts\python.exe` (Windows) or `.venv/bin/python` (Unix)
81+
82+
## Platform-Specific Quick Reference
83+
84+
### Windows 11 + WSL2 (Recommended Workflow)
85+
```bash
86+
# Docker/Container operations - ALWAYS use WSL2
87+
wsl docker-compose up -d
88+
wsl docker ps
89+
wsl docker-compose logs -f app
90+
wsl docker exec -it secondbrain-postgres psql -U secondbrain
91+
92+
# Python/Development - Use native Windows
93+
.venv\Scripts\python.exe scripts\run_dev.py
94+
.venv\Scripts\python.exe -m pytest tests/unit/ -v
95+
96+
# File operations - Choose based on need
97+
wsl grep -r "pattern" . # Fast Unix-style search
98+
wsl find . -name "*.py" # Unix find
99+
cmd.exe /c "dir /s *.py" # Windows alternative
100+
101+
# Process management
102+
cmd.exe /c "netstat -ano | findstr :8001"
103+
taskkill /PID <pid> /F
104+
```
105+
106+
### macOS M4 / Linux (Native)
107+
```bash
108+
# Everything runs natively
109+
docker-compose up -d
110+
docker ps
111+
.venv/bin/python scripts/run_dev.py
112+
.venv/bin/python -m pytest tests/unit/ -v
113+
lsof -i :8001 # macOS
114+
ss -tlnp | grep 8001 # Linux
115+
```
116+
117+
### Why WSL2 on Windows?
118+
- **10x faster** Docker operations than Docker Desktop alone
119+
- **Native Linux tooling** (grep, awk, sed, find)
120+
- **Consistent behavior** with CI/CD pipelines
121+
- **Better PostgreSQL** integration with pgvector
122+
123+
## Project Architecture
124+
125+
### Core Services
126+
- **FastAPI Backend** (port 8001) - Main application server
127+
- **PostgreSQL + pgvector** (port 5432) - Vector database for embeddings
128+
- **LM Studio** (port 1234) - Local text generation (LLaVA 1.6 Mistral 7B)
129+
- **CLIP Service** (port 8002) - Image embeddings and similarity
130+
- **LLaVA Service** (port 8003) - Vision understanding and OCR
131+
132+
### Project Structure
133+
```
134+
/app - Main application code
135+
/routes - API endpoints (v2 API, WebSocket, Google Drive)
136+
/services - Business logic (memory, Google Drive processing)
137+
/storage - Database backends (PostgreSQL, mock)
138+
/models - Pydantic models and schemas
139+
/frontend - SvelteKit frontend application
140+
/services/gpu - GPU-accelerated vision services
141+
/tests - Comprehensive test suite
142+
/unit - Fast unit tests
143+
/integration - Integration tests
144+
/static - Static files and legacy UIs
145+
/scripts - Development and CI/CD scripts
146+
/docs - Documentation and guides
147+
```
148+
149+
## Environment Configuration
150+
151+
### Essential Setup
152+
1. Copy `.env.example` to `.env`
153+
2. Key variables:
154+
- `DATABASE_URL` - PostgreSQL connection (defaults to SQLite for dev)
155+
- `USE_MOCK_DATABASE=true` - Use mock storage for quick development
156+
- `OPENAI_API_KEY` - Optional, for enhanced features
157+
- `ENVIRONMENT=development` - Environment mode
158+
159+
### Development Modes
160+
- **Full Stack**: `make dev` (Docker with PostgreSQL + pgvector)
161+
- **Quick Mode**: `python scripts/run_dev.py` (SQLite + mock storage)
162+
- **GPU Services**: `cd services/gpu && python llava_api.py` (local vision models)
163+
164+
## Testing Strategy
165+
The project uses a tiered testing approach:
166+
- **Smoke Tests** (<60s): `make test-smoke` - Critical path validation
167+
- **Fast Tests** (<5min): `make test-fast` - Core functionality
168+
- **Comprehensive** (<15min): `make test-comprehensive` - Full validation
169+
- **Performance** (<20min): `make test-performance` - Benchmarks
170+
171+
## Key Features
172+
- **Multimodal Search**: Text and image semantic search
173+
- **Google Drive Integration**: OAuth 2.0, automatic sync
174+
- **Knowledge Graph**: Automatic relationship discovery and visualization
175+
- **100% Local Option**: Run entirely on local models without API keys
176+
- **WebSocket Support**: Real-time updates and streaming
177+
178+
## Code Quality Standards
179+
- **Formatter**: Black (line length 100)
180+
- **Linter**: Ruff with extensive rule set
181+
- **Type Checker**: MyPy in strict mode
182+
- **Test Coverage**: Minimum 80% required
183+
- Python 3.11+ required
184+
185+
## Common Tasks
186+
- View logs: `make logs` or `docker-compose logs -f app`
187+
- Database shell: `make db-shell` or connect to PostgreSQL on port 5432
188+
- Run specific test: `.venv\Scripts\python -m pytest tests/unit/test_memory_service.py -v`
189+
- Check health: `curl http://localhost:8001/health`
190+
- View API docs: http://localhost:8001/docs
191+
192+
## Important Notes
193+
- Docker-first development approach - prefer `make` commands
194+
- The `.venv` is used as fallback when Docker isn't available
195+
- Use `USE_MOCK_DATABASE=true` for rapid development without PostgreSQL
196+
- Frontend development: `cd frontend && npm run dev`
197+
- All linting/formatting should pass before committing
198+
199+
## Claude Assistant Guidelines
200+
201+
### Smart Platform Handling
202+
Claude automatically detects your platform from the environment and adjusts commands accordingly:
203+
204+
#### Windows 11 (win32)
205+
- **WSL2 First**: Prefers `wsl` for Docker, PostgreSQL, and Unix tools
206+
- **Native Python**: Uses `.venv\Scripts\python.exe` for better Windows integration
207+
- **Hybrid Approach**: Leverages WSL2's Linux performance while maintaining Windows tooling
208+
209+
#### macOS M4 (darwin) / Arch Linux (linux)
210+
- **Native Commands**: Direct execution without translation layers
211+
- **ARM Awareness**: Considers M4 architecture for macOS
212+
213+
Commands in this file are platform-agnostic - Claude will adapt them using the optimal approach for your system
214+
215+
### Session Behavior
216+
1. **Automatically on start**: Activate `.venv` silently using the right method for your OS
217+
2. **Smart command execution**: If a command fails, Claude will try platform-appropriate alternatives
218+
3. **Port awareness**: Defaults to port 8001 for development (our standard)
219+
220+
### Development Standards
221+
- Read existing code before making changes to match conventions
222+
- Prefer editing over creating new files
223+
- Run tests after significant changes
224+
- Only commit when explicitly asked
225+
- Don't create documentation unless requested
226+
227+
## Useful File Locations
228+
- API endpoints: `app/routes/v2/`
229+
- Memory logic: `app/services/memory_service.py`
230+
- Database models: `app/models/memory.py`
231+
- Mock storage: `app/storage/mock_storage.py`
232+
- PostgreSQL storage: `app/storage/postgres_unified.py`
233+
- Test fixtures: `tests/conftest.py`
234+
- Environment config: `app/config.py` and `app/core/env_manager.py`

0 commit comments

Comments
 (0)