mirror of
https://github.com/lfnovo/open-notebook.git
synced 2026-05-02 21:30:38 +00:00
b7e656a319
New front-end Launch Chat API Manage Sources Enable re-embedding of all contents Sources can be added without a notebook now Improved settings Enable model selector on all chats Background processing for better experience Dark mode Improved Notes Improved Docs: - Remove all Streamlit references from documentation - Update deployment guides with React frontend setup - Fix Docker environment variables format (SURREAL_URL, SURREAL_PASSWORD) - Update docker image tag from :latest to :v1-latest - Change navigation references (Settings → Models to just Models) - Update development setup to include frontend npm commands - Add MIGRATION.md guide for users upgrading from Streamlit - Update quick-start guide with correct environment variables - Add port 5055 documentation for API access - Update project structure to reflect frontend/ directory - Remove outdated source-chat documentation files
4.7 KiB
4.7 KiB
Development Documentation
Welcome to the Open Notebook development documentation! This section provides comprehensive technical information for developers and contributors.
📋 Quick Navigation
Getting Started
- Architecture Overview - Understanding the system design and components
- API Reference - Complete REST API documentation
- Contributing Guide - Development workflow and standards
Development Setup
Before diving into the documentation below, make sure you have Open Notebook set up locally:
# Clone the repository
git clone https://github.com/lfnovo/open-notebook
cd open-notebook
# Install dependencies with uv
uv sync
# Start the development environment
make start-all
For detailed setup instructions, see the Installation Guide.
🏗️ System Architecture
Open Notebook is built with a modern Python stack using:
- Backend: FastAPI with async/await patterns
- Database: SurrealDB for flexible document storage
- Frontend: Next.js for rapid UI development
- AI Integration: Multi-provider support via Esperanto library
- Processing: LangChain for AI workflows and content processing
Key Components
| Component | Description | Location |
|---|---|---|
| API Layer | FastAPI REST endpoints | api/ |
| Domain Models | Core business logic | open_notebook/domain/ |
| Database | SurrealDB repository pattern | open_notebook/database/ |
| AI Graphs | LangChain processing workflows | open_notebook/graphs/ |
| React frontend | Web interface | pages/ |
| Commands | Background job processing | commands/ |
🔧 Development Workflow
Code Standards
- Python: PEP 8 compliance with type hints
- Async/Await: Consistent async patterns throughout
- Error Handling: Comprehensive exception handling
- Logging: Structured logging with Loguru
- Testing: Unit and integration tests with pytest
Database Patterns
Open Notebook uses SurrealDB with a custom repository pattern:
# Create records
await repo_create("table", data)
# Query with SurrealQL
await repo_query("SELECT * FROM table WHERE field = $value", {"value": "example"})
# Update records
await repo_update("table", record_id, data)
AI Integration
Multi-provider AI support via the Esperanto library:
from esperanto import AIFactory
# Create language model
model = AIFactory.create_language("openai", "gpt-4")
# Generate completion
response = model.chat_complete(messages)
🚀 Key Features to Understand
1. Multi-Notebook Organization
- Notebooks contain sources, notes, and chat sessions
- Each notebook maintains isolated context
- Sources can be shared across notebooks (roadmap)
2. Content Processing Pipeline
- Ingestion: Documents, URLs, text → structured content
- Embedding: Vector representations for semantic search
- Transformations: AI-powered content analysis
- Indexing: Both full-text and vector search
3. AI Workflows
- Chat: Context-aware conversations
- Ask: Multi-step question answering
- Transformations: Content summarization and analysis
- Podcast Generation: Advanced multi-speaker content
4. Background Processing
- Commands system for long-running tasks
- Async job queue with SurrealDB
- Status tracking and error handling
📝 Contributing
We welcome contributions! Here's how to get started:
- Read the Contributing Guide for detailed workflow
- Check the Architecture Overview to understand the system
- Browse the API Reference for endpoint details
- Join our Discord for community support
Current Development Priorities
- React Frontend: Replacing Next.js with modern React UI
- Performance: Async processing and caching improvements
- Testing: Expanded test coverage
- Documentation: API documentation and examples
📖 Additional Resources
External Documentation
Community
- Discord Server - Development discussions
- GitHub Issues - Bug reports and features
- GitHub Discussions - Ideas and questions
Ready to contribute? Start with the Contributing Guide and join our vibrant developer community!