refactor: Major codebase reorganization and documentation overhaul #379
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Changes: - Move migrations/ under open_notebook/database/migrations/ - Extract AI models to open_notebook/ai/ (Model, ModelManager, provision) - Extract podcasts to open_notebook/podcasts/ (EpisodeProfile, SpeakerProfile, PodcastEpisode) - Reorganize prompts to mirror graphs structure (chat/, source_chat/) This improves code organization by: - Consolidating database concerns (migrations now with database code) - Separating AI infrastructure from domain entities - Isolating podcast feature into its own module - Creating consistent prompt/graph naming conventions All 52 tests pass.
… codebase Create a hierarchical CLAUDE.md documentation system for the entire Open Notebook codebase with focus on concise, pattern-driven reference cards rather than comprehensive tutorials. ## Changes ### Core Documentation System - Updated `.claude/commands/build-claude-md.md` to distinguish between leaf and parent modules, with special handling for prompt/template modules - Established clear patterns: * Leaf modules (40-70 lines): Components, hooks, API clients * Parent modules (50-150 lines): Architecture, cross-layer patterns, data flows * Template modules: Pattern focus, not catalog listings ### Generated Documentation Created 15 CLAUDE.md reference files across the project: **Frontend (React/Next.js)** - frontend/src/CLAUDE.md: Architecture overview, data flow, three-tier design - frontend/src/lib/hooks/CLAUDE.md: React Query patterns, state management - frontend/src/lib/api/CLAUDE.md: Axios client, FormData handling, interceptors - frontend/src/lib/stores/CLAUDE.md: Zustand state persistence, auth patterns - frontend/src/components/ui/CLAUDE.md: Radix UI primitives, CVA styling **Backend (Python/FastAPI)** - open_notebook/CLAUDE.md: System architecture, layer interactions - open_notebook/ai/CLAUDE.md: Model provisioning, Esperanto integration - open_notebook/domain/CLAUDE.md: Data models, ObjectModel/RecordModel patterns - open_notebook/database/CLAUDE.md: Repository pattern, async migrations - open_notebook/graphs/CLAUDE.md: LangGraph workflows, async orchestration - open_notebook/utils/CLAUDE.md: Cross-cutting utilities, context building - open_notebook/podcasts/CLAUDE.md: Episode/speaker profiles, job tracking **API & Other** - api/CLAUDE.md: REST layer, service architecture - commands/CLAUDE.md: Async command handlers, job queue patterns - prompts/CLAUDE.md: Jinja2 templates, prompt engineering patterns (refactored) **Project Root** - CLAUDE.md: Project overview, three-tier architecture, tech stack, getting started ### Key Features - Zero duplication: Parent modules reference child CLAUDE.md files, don't repeat them - Pattern-focused: Emphasizes how components work together, not component catalogs - Scannable: Short bullets, code examples only when necessary (1-2 per file) - Practical: "How to extend" guides, quirks/gotchas for each module - Navigation: Root CLAUDE.md acts as hub pointing to specialized documentation ### Cleanup - Removed unused `batch_fix_services.py` - Removed deprecated `open_notebook/plugins/podcasts.py` - Updated .gitignore for documentation consistency ## Impact New contributors can now: 1. Read root CLAUDE.md for system architecture (5 min) 2. Jump to specific layer documentation (frontend, api, open_notebook) 3. Dive into module-specific patterns in child CLAUDE.md files (1 min per module) All documentation is lean, reference-focused, and avoids duplication.
- Replace old docs structure with new comprehensive documentation - Organize into 8 major sections (0-START-HERE through 7-DEVELOPMENT) - Convert CONFIGURATION.md, CONTRIBUTING.md, MAINTAINER_GUIDE.md to redirects - Remove outdated MIGRATION.md and DESIGN_PRINCIPLES.md - Fix all internal documentation links and cross-references - Add progressive disclosure paths for different user types - Include 44 focused guides covering all features - Update README.md to remove v1.0 breaking changes notice
…r latest major versions
|
Claude finished @lfnovo's task —— View job PR Review: Major Codebase Reorganization ✅Reviewed this comprehensive refactoring PR with 100 files changed and +19,192/-18,302 lines. Review Tasks:
✅ Code Quality & Best PracticesExcellent code organization improvements:
Good practices maintained:
✅ Documentation Overhaul - Outstanding WorkThe new numbered documentation structure (0-7) is a significant improvement:
CLAUDE.md files provide excellent AI-assistant guidance throughout the codebase. ✅ Dependency UpdatesLangChain dependency updates look solid:
|
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
39 issues found across 180 files
Note: This PR contains a large number of files. cubic only reviews up to 75 files per PR, so some files may not have been reviewed.
Prompt for AI agents (all issues)
Check if these issues are valid — if so, understand the root cause of each and fix them.
<file name="docs/4-AI-PROVIDERS/index.md">
<violation number="1" location="docs/4-AI-PROVIDERS/index.md:22">
P2: Inconsistent pricing units across providers - OpenAI/Google use 'per 1K tokens' while Anthropic/Groq use 'per 1M tokens'. This makes the comparison table misleading and could cause users to make incorrect cost decisions. Consider standardizing all pricing to 'per 1M tokens' (the modern industry standard).</violation>
</file>
<file name="docs/5-CONFIGURATION/reverse-proxy.md">
<violation number="1" location="docs/5-CONFIGURATION/reverse-proxy.md:203">
P2: The `X-XSS-Protection` header is deprecated and removed from modern browsers. The XSS Auditor it controlled has been discontinued because it could introduce vulnerabilities. Consider removing this header or replacing it with a Content-Security-Policy header for XSS protection.</violation>
</file>
<file name="docs/2-CORE-CONCEPTS/index.md">
<violation number="1" location="docs/2-CORE-CONCEPTS/index.md:24">
P3: Grammatical error: 'reduced' should be 'reduce' to maintain present tense consistency with the rest of the paragraph.</violation>
</file>
<file name="docs/0-START-HERE/quick-start-openai.md">
<violation number="1" location="docs/0-START-HERE/quick-start-openai.md:143">
P2: Incorrect service name in troubleshooting command. The docker-compose.yml defines the service as `open_notebook`, but this command references `api`. This will cause the command to fail with "no such service: api".</violation>
</file>
<file name="docs/2-CORE-CONCEPTS/notebooks-sources-notes.md">
<violation number="1" location="docs/2-CORE-CONCEPTS/notebooks-sources-notes.md:22">
P3: Missing closing pipe character `│` in ASCII diagram. This line is missing the right border that all other lines in the box have.</violation>
</file>
<file name="docs/5-CONFIGURATION/environment-reference.md">
<violation number="1" location="docs/5-CONFIGURATION/environment-reference.md:294">
P2: The regex pattern `^[A-Z_]+=` won't match env vars containing numbers (e.g., `LANGCHAIN_TRACING_V2`, `AZURE_OPENAI_API_VERSION`). Consider updating to include digits.</violation>
<violation number="2" location="docs/5-CONFIGURATION/environment-reference.md:303">
P2: The example URL contains a space which is invalid. URLs cannot have unencoded spaces. Consider using a different example that legitimately benefits from quoting, such as a file path or a value with special characters.</violation>
</file>
<file name="docs/1-INSTALLATION/from-source.md">
<violation number="1" location="docs/1-INSTALLATION/from-source.md:7">
P2: Python version requirement is inaccurate. The project requires `>=3.11,<3.13` (per pyproject.toml), but the documentation says "Python 3.11+" which could mislead users into using unsupported Python 3.13+ versions.</violation>
</file>
<file name="docs/5-CONFIGURATION/database.md">
<violation number="1" location="docs/5-CONFIGURATION/database.md:50">
P3: Typo: "noteobok" should be "notebook".</violation>
</file>
<file name="docs/3-USER-GUIDE/index.md">
<violation number="1" location="docs/3-USER-GUIDE/index.md:16">
P2: Heading claims "Eight Core Features" but only seven features are listed (numbered 1-7). Either update the heading to "Seven Core Features" or add the missing eighth feature.</violation>
</file>
<file name="docs/2-CORE-CONCEPTS/ai-context-rag.md">
<violation number="1" location="docs/2-CORE-CONCEPTS/ai-context-rag.md:155">
P2: Factually incorrect claim: BM25 is not the algorithm Google uses. Google employs proprietary ranking systems including PageRank, neural models (BERT, MUM), and many other signals. BM25 is a classic IR algorithm used by systems like Elasticsearch, but it's not what powers Google Search. Consider rephrasing to something like "Uses BM25 ranking (a proven algorithm also used by Elasticsearch)" or simply describe what BM25 does without the comparison.</violation>
</file>
<file name="docs/5-CONFIGURATION/openai-compatible.md">
<violation number="1" location="docs/5-CONFIGURATION/openai-compatible.md:76">
P2: Copy-paste error: The API key environment variable for embeddings should be `OPENAI_COMPATIBLE_API_KEY_EMBEDDING`, not `OPENAI_COMPATIBLE_BASE_URL_EMBEDDING`. This follows the pattern used for TTS (`API_KEY_TTS`) and STT (`API_KEY_STT`).</violation>
</file>
<file name="docs/3-USER-GUIDE/transformations.md">
<violation number="1" location="docs/3-USER-GUIDE/transformations.md:371">
P2: The comparison table says Transformations scope is "One source at a time" but the batch processing section above clearly describes processing multiple sources in parallel. Consider rewording to "One source per output" or "Processes sources individually" to clarify that batch is supported but each source produces its own note.</violation>
</file>
<file name="docs/1-INSTALLATION/docker-compose.md">
<violation number="1" location="docs/1-INSTALLATION/docker-compose.md:39">
P1: Data persistence issue: `memory` storage mode stores data only in RAM, which will be lost on container restart. The volume mount `surreal_data:/mydata` is ineffective with this configuration. For persistent storage, use `file:/mydata` instead of `memory`.</violation>
<violation number="2" location="docs/1-INSTALLATION/docker-compose.md:272">
P2: Service name mismatch: should be `open_notebook` to match the service defined in docker-compose.yml above.</violation>
<violation number="3" location="docs/1-INSTALLATION/docker-compose.md:303">
P1: Broken link: `docs/deployment/security.md` does not exist in the new documentation structure. Consider updating to point to the appropriate file in `docs/5-CONFIGURATION/` or remove the link.</violation>
<violation number="4" location="docs/1-INSTALLATION/docker-compose.md:304">
P1: Broken link: `docs/deployment/reverse-proxy.md` does not exist in the new documentation structure. Consider updating to point to the appropriate file in `docs/5-CONFIGURATION/` or remove the link.</violation>
</file>
<file name="docs/0-START-HERE/quick-start-local.md">
<violation number="1" location="docs/0-START-HERE/quick-start-local.md:34">
P1: SurrealDB is configured with `memory` storage mode, which means **all user data will be lost when the container restarts**. This is a significant issue for users who follow this guide and expect their notebooks and sources to persist.
The volume `./surreal_data:/mydata` is also mapped to the wrong service (open_notebook instead of surrealdb).
Consider using persistent storage like the official docker-compose.full.yml which uses `rocksdb:/mydata/mydatabase.db`.</violation>
</file>
<file name="README.dev.md">
<violation number="1" location="README.dev.md:251">
P2: Documentation references incorrect migration path. Migrations were moved to `open_notebook/database/migrations/` according to this PR, but this section points to the old `migrations/` path at root.</violation>
</file>
<file name="docs/7-DEVELOPMENT/architecture.md">
<violation number="1" location="docs/7-DEVELOPMENT/architecture.md:1">
P2: Incorrect migration path. The migrations are now located at `/open_notebook/database/migrations/` according to the PR changes, not `/migrations/`.</violation>
</file>
<file name="frontend/src/lib/hooks/CLAUDE.md">
<violation number="1" location="frontend/src/lib/hooks/CLAUDE.md:56">
P3: Invalid syntax `[...]` in code example. The spread operator requires an iterable - use `[]` for an empty array or provide actual mock data like `[{ id: 1, name: 'test' }]`.</violation>
</file>
<file name="CLAUDE.md">
<violation number="1" location="CLAUDE.md:196">
P2: Incorrect migration path in documentation. Migrations were moved to `open_notebook/database/migrations/` according to this PR, but this instruction still references the old `migrations/` path.</violation>
</file>
<file name="docs/7-DEVELOPMENT/testing.md">
<violation number="1" location="docs/7-DEVELOPMENT/testing.md:212">
P2: Async fixtures require `@pytest_asyncio.fixture` decorator, not `@pytest.fixture`. With pytest-asyncio in strict mode (the default), using `@pytest.fixture` on an async function returns a coroutine object instead of the awaited result, causing test failures. This pattern is repeated throughout the document, including ironically in the "Common Testing Errors" section.</violation>
</file>
<file name="docs/1-INSTALLATION/index.md">
<violation number="1" location="docs/1-INSTALLATION/index.md:147">
P2: These links point to the old `docs/deployment/` structure that was removed in this PR. The security and reverse-proxy docs now exist at `docs/5-CONFIGURATION/`. Also, `retry-configuration.md` doesn't exist in the new structure.</violation>
</file>
<file name="docs/0-START-HERE/quick-start-cloud.md">
<violation number="1" location="docs/0-START-HERE/quick-start-cloud.md:182">
P2: Incorrect service name in troubleshooting command. The docker-compose.yml defines the service as `open_notebook`, not `api`. Users following this troubleshooting step will get an error.</violation>
</file>
<file name="CONFIGURATION.md">
<violation number="1" location="CONFIGURATION.md:16">
P2: Broken documentation link: `docs/5-CONFIGURATION/server.md` does not exist. Either create the missing file or remove/update this link to point to valid documentation.</violation>
</file>
<file name="docs/1-INSTALLATION/single-container.md">
<violation number="1" location="docs/1-INSTALLATION/single-container.md:37">
P1: Missing SurrealDB volume mount in docker-compose example. The single container requires two volumes: `/app/data` for application data and `/mydata` for SurrealDB data. Without the `/mydata` volume, database data will be lost when the container restarts.</violation>
</file>
<file name="docs/7-DEVELOPMENT/api-reference.md">
<violation number="1" location="docs/7-DEVELOPMENT/api-reference.md:197">
P1: Documentation inconsistency: Line 189 states to use `X-Password` header, but the actual API (and earlier examples in this same document) uses `Authorization: Bearer your_password`. This will confuse developers and cause authentication failures.</violation>
</file>
<file name="docs/7-DEVELOPMENT/development-setup.md">
<violation number="1" location="docs/7-DEVELOPMENT/development-setup.md:354">
P2: Documentation references the old migrations path `/migrations/` which was moved to `/open_notebook/database/migrations/` as part of this PR. This will confuse developers trying to troubleshoot migration issues.</violation>
</file>
<file name="docs/6-TROUBLESHOOTING/ai-chat-issues.md">
<violation number="1" location="docs/6-TROUBLESHOOTING/ai-chat-issues.md:278">
P2: Misleading advice: suggesting a 'smaller' model doesn't solve context length issues. Model parameter size and context window size are different things. Phi models typically have smaller context windows (2K-4K), which would make this problem worse. Consider recommending models with larger context windows instead.</violation>
</file>
<file name="docs/index.md">
<violation number="1" location="docs/index.md:175">
P2: Broken link: `../7-DEVELOPMENT/architecture.md` should be `7-DEVELOPMENT/architecture.md`. The `../` prefix navigates up to the repo root instead of staying in the `docs/` directory.</violation>
<violation number="2" location="docs/index.md:212">
P2: Broken link: `../7-DEVELOPMENT/index.md` should be `7-DEVELOPMENT/index.md`. The `../` prefix navigates up to the repo root instead of staying in the `docs/` directory.</violation>
</file>
<file name="docs/7-DEVELOPMENT/quick-start.md">
<violation number="1" location="docs/7-DEVELOPMENT/quick-start.md:7">
P2: Python version constraint is inaccurate. The project requires Python `>=3.11,<3.13` (only 3.11 and 3.12), but the documentation says "Python 3.11+" which implies 3.13+ is also supported. This could cause setup failures for developers with Python 3.13.</violation>
</file>
<file name="docs/5-CONFIGURATION/advanced.md">
<violation number="1" location="docs/5-CONFIGURATION/advanced.md:101">
P2: Misleading example: `open_notebook` is a Python package, not a Rust crate. `RUST_LOG` only affects Rust code. This example won't do anything useful and may confuse users. Consider removing or replacing with a valid Python logging configuration.</violation>
<violation number="2" location="docs/5-CONFIGURATION/advanced.md:169">
P1: Incorrect Docker port in `SURREAL_URL`. When changing the host port mapping, the internal container port remains 8000. The URL should be `ws://surrealdb:8000/rpc` since Docker internal networking uses container ports, not host-mapped ports.</violation>
</file>
<file name="docs/7-DEVELOPMENT/code-standards.md">
<violation number="1" location="docs/7-DEVELOPMENT/code-standards.md:351">
P2: The `@validator` decorator is deprecated in Pydantic v2 (which this project uses). Use `@field_validator` instead to avoid deprecation warnings and ensure forward compatibility with Pydantic v3.</violation>
</file>
<file name="docs/5-CONFIGURATION/index.md">
<violation number="1" location="docs/5-CONFIGURATION/index.md:100">
P3: Typo: "it's" should be "its" (possessive form, not contraction).</violation>
<violation number="2" location="docs/5-CONFIGURATION/index.md:115">
P3: Typo: "installation" should be "information".</violation>
<violation number="3" location="docs/5-CONFIGURATION/index.md:158">
P2: Inconsistent environment variable name. Earlier in the document `OLLAMA_BASE_URL` is used, but here `OLLAMA_API_BASE` is used. These should be consistent to avoid user confusion.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
| → [Setup Guide](../5-CONFIGURATION/ai-providers.md#openai) | ||
|
|
||
| **Anthropic (Claude)** | ||
| - Cost: ~$0.80-3.00 per 1M tokens |
Contributor
There was a problem hiding this comment.
P2: Inconsistent pricing units across providers - OpenAI/Google use 'per 1K tokens' while Anthropic/Groq use 'per 1M tokens'. This makes the comparison table misleading and could cause users to make incorrect cost decisions. Consider standardizing all pricing to 'per 1M tokens' (the modern industry standard).
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/4-AI-PROVIDERS/index.md, line 22:
<comment>Inconsistent pricing units across providers - OpenAI/Google use 'per 1K tokens' while Anthropic/Groq use 'per 1M tokens'. This makes the comparison table misleading and could cause users to make incorrect cost decisions. Consider standardizing all pricing to 'per 1M tokens' (the modern industry standard).</comment>
<file context>
@@ -0,0 +1,199 @@
+→ [Setup Guide](../5-CONFIGURATION/ai-providers.md#openai)
+
+**Anthropic (Claude)**
+- Cost: ~$0.80-3.00 per 1M tokens
+- Speed: Fast
+- Quality: Excellent
</file context>
| # Security headers | ||
| add_header X-Frame-Options DENY; | ||
| add_header X-Content-Type-Options nosniff; | ||
| add_header X-XSS-Protection "1; mode=block"; |
Contributor
There was a problem hiding this comment.
P2: The X-XSS-Protection header is deprecated and removed from modern browsers. The XSS Auditor it controlled has been discontinued because it could introduce vulnerabilities. Consider removing this header or replacing it with a Content-Security-Policy header for XSS protection.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/5-CONFIGURATION/reverse-proxy.md, line 203:
<comment>The `X-XSS-Protection` header is deprecated and removed from modern browsers. The XSS Auditor it controlled has been discontinued because it could introduce vulnerabilities. Consider removing this header or replacing it with a Content-Security-Policy header for XSS protection.</comment>
<file context>
@@ -0,0 +1,738 @@
+ # Security headers
+ add_header X-Frame-Options DENY;
+ add_header X-Content-Type-Options nosniff;
+ add_header X-XSS-Protection "1; mode=block";
+ add_header Strict-Transport-Security "max-age=31536000; includeSubDomains";
+
</file context>
| ### 3. [Chat vs. Transformations](chat-vs-transformations.md) | ||
| Why Open Notebook has different interaction modes and when to use each one. | ||
|
|
||
| **Key idea**: Chat is conversational exploration (you control context). Transformations are insight extractions. They reduced content to smaller bits of concentrated/dense information, which is much more suitable for an AI to use. |
Contributor
There was a problem hiding this comment.
P3: Grammatical error: 'reduced' should be 'reduce' to maintain present tense consistency with the rest of the paragraph.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/2-CORE-CONCEPTS/index.md, line 24:
<comment>Grammatical error: 'reduced' should be 'reduce' to maintain present tense consistency with the rest of the paragraph.</comment>
<file context>
@@ -0,0 +1,70 @@
+### 3. [Chat vs. Transformations](chat-vs-transformations.md)
+Why Open Notebook has different interaction modes and when to use each one.
+
+**Key idea**: Chat is conversational exploration (you control context). Transformations are insight extractions. They reduced content to smaller bits of concentrated/dense information, which is much more suitable for an AI to use.
+
+---
</file context>
|
|
||
| 1. Double-check your API key (no extra spaces) | ||
| 2. Verify you added credits at https://platform.openai.com | ||
| 3. Restart: `docker compose restart api` |
Contributor
There was a problem hiding this comment.
P2: Incorrect service name in troubleshooting command. The docker-compose.yml defines the service as open_notebook, but this command references api. This will cause the command to fail with "no such service: api".
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/0-START-HERE/quick-start-openai.md, line 143:
<comment>Incorrect service name in troubleshooting command. The docker-compose.yml defines the service as `open_notebook`, but this command references `api`. This will cause the command to fail with "no such service: api".</comment>
<file context>
@@ -0,0 +1,174 @@
+
+1. Double-check your API key (no extra spaces)
+2. Verify you added credits at https://platform.openai.com
+3. Restart: `docker compose restart api`
+
+### "Cannot connect to server"
</file context>
| │ ├─ AI Summary (auto-generated) │ | ||
| │ ├─ Key Concepts (transformation) │ | ||
| │ ├─ My Research Notes (manual) │ | ||
| │ └─ Chat Insights (from conversation) |
Contributor
There was a problem hiding this comment.
P3: Missing closing pipe character │ in ASCII diagram. This line is missing the right border that all other lines in the box have.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/2-CORE-CONCEPTS/notebooks-sources-notes.md, line 22:
<comment>Missing closing pipe character `│` in ASCII diagram. This line is missing the right border that all other lines in the box have.</comment>
<file context>
@@ -0,0 +1,284 @@
+│ ├─ AI Summary (auto-generated) │
+│ ├─ Key Concepts (transformation) │
+│ ├─ My Research Notes (manual) │
+│ └─ Chat Insights (from conversation)
+│ │
+└─────────────────────────────────────┘
</file context>
| ports: | ||
| - "8001:8000" # Change from 8000 to 8001 | ||
| environment: | ||
| - SURREAL_URL=ws://surrealdb:8001/rpc # Update connection URL |
Contributor
There was a problem hiding this comment.
P1: Incorrect Docker port in SURREAL_URL. When changing the host port mapping, the internal container port remains 8000. The URL should be ws://surrealdb:8000/rpc since Docker internal networking uses container ports, not host-mapped ports.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/5-CONFIGURATION/advanced.md, line 169:
<comment>Incorrect Docker port in `SURREAL_URL`. When changing the host port mapping, the internal container port remains 8000. The URL should be `ws://surrealdb:8000/rpc` since Docker internal networking uses container ports, not host-mapped ports.</comment>
<file context>
@@ -0,0 +1,567 @@
+ ports:
+ - "8001:8000" # Change from 8000 to 8001
+ environment:
+ - SURREAL_URL=ws://surrealdb:8001/rpc # Update connection URL
+```
+
</file context>
| name: str | ||
| description: str = "" | ||
|
|
||
| @validator('name') |
Contributor
There was a problem hiding this comment.
P2: The @validator decorator is deprecated in Pydantic v2 (which this project uses). Use @field_validator instead to avoid deprecation warnings and ensure forward compatibility with Pydantic v3.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/7-DEVELOPMENT/code-standards.md, line 351:
<comment>The `@validator` decorator is deprecated in Pydantic v2 (which this project uses). Use `@field_validator` instead to avoid deprecation warnings and ensure forward compatibility with Pydantic v3.</comment>
<file context>
@@ -0,0 +1,375 @@
+ name: str
+ description: str = ""
+
+ @validator('name')
+ def name_not_empty(cls, v):
+ if not v.strip():
</file context>
| ### Scenario 4: Using Ollama Locally | ||
| ```env | ||
| # In .env: | ||
| OLLAMA_API_BASE=http://localhost:11434 |
Contributor
There was a problem hiding this comment.
P2: Inconsistent environment variable name. Earlier in the document OLLAMA_BASE_URL is used, but here OLLAMA_API_BASE is used. These should be consistent to avoid user confusion.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/5-CONFIGURATION/index.md, line 158:
<comment>Inconsistent environment variable name. Earlier in the document `OLLAMA_BASE_URL` is used, but here `OLLAMA_API_BASE` is used. These should be consistent to avoid user confusion.</comment>
<file context>
@@ -0,0 +1,334 @@
+### Scenario 4: Using Ollama Locally
+```env
+# In .env:
+OLLAMA_API_BASE=http://localhost:11434
+# No API key needed
+```
</file context>
| OPENROUTER_API_KEY=... | ||
| ``` | ||
|
|
||
| Or, if you are planning to use only local providers, you can setup Ollama by configuring it's base URL. This will get you set and ready with text and embeddings in one go: |
Contributor
There was a problem hiding this comment.
P3: Typo: "it's" should be "its" (possessive form, not contraction).
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/5-CONFIGURATION/index.md, line 100:
<comment>Typo: "it's" should be "its" (possessive form, not contraction).</comment>
<file context>
@@ -0,0 +1,334 @@
+OPENROUTER_API_KEY=...
+```
+
+Or, if you are planning to use only local providers, you can setup Ollama by configuring it's base URL. This will get you set and ready with text and embeddings in one go:
+
+```
</file context>
| OPENAI_COMPATIBLE_BASE_URL_EMBEDDING=http://localhost:1234/v1 | ||
| ``` | ||
|
|
||
| > For more installation on using OpenAI compatible endpoints, see [here](openai-compatible.md). |
Contributor
There was a problem hiding this comment.
P3: Typo: "installation" should be "information".
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/5-CONFIGURATION/index.md, line 115:
<comment>Typo: "installation" should be "information".</comment>
<file context>
@@ -0,0 +1,334 @@
+OPENAI_COMPATIBLE_BASE_URL_EMBEDDING=http://localhost:1234/v1
+```
+
+> For more installation on using OpenAI compatible endpoints, see [here](openai-compatible.md).
+
+
</file context>
jonigl
added a commit
to jonigl/open-notebook
that referenced
this pull request
Jan 6, 2026
7 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR implements a comprehensive refactoring of the codebase structure and documentation system, focusing on improved maintainability, better code organization, and enhanced developer experience.
Key Changes
Detailed Changes
1. Code Organization
New module structure:
open_notebook/ai/moduledomain/models.py→ai/models.pygraphs/utils.py→ai/provision.pyopen_notebook/podcasts/moduledomain/podcast.py→podcasts/models.pyplugins/podcasts.py(293 lines)/migrations/→/open_notebook/database/migrations/prompts/chat.jinja→prompts/chat/system.jinja2. Documentation Overhaul (18,000+ line changes)
Removed old structure:
docs/getting-started/,docs/user-guide/,docs/features/,docs/deployment/,docs/troubleshooting/,docs/development/New numbered structure:
0-START-HERE/- Quick start guides (local, cloud, OpenAI)1-INSTALLATION/- Docker Compose, from source, single container2-CORE-CONCEPTS/- Notebooks/sources/notes, RAG/context, chat vs transformations, podcasts3-USER-GUIDE/- Complete user documentation with screenshots and examples4-AI-PROVIDERS/- Provider configuration and setup5-CONFIGURATION/- Environment variables, security, reverse proxy, advanced options6-TROUBLESHOOTING/- Connection issues, AI issues, FAQ, quick fixes7-DEVELOPMENT/- Architecture, API reference, contributing, testing, maintainer guide3. CLAUDE.md Reference Documentation
Added comprehensive AI-assistant guidance across the codebase:
CLAUDE.md(project overview and architecture)api/CLAUDE.md(FastAPI structure and patterns)frontend/src/CLAUDE.md+ subdirectories (React architecture)open_notebook/CLAUDE.md+ all submodules (ai, database, domain, graphs, podcasts, utils)prompts/CLAUDE.md(prompt engineering guidance)commands/CLAUDE.md(command patterns)4. Dependency Updates
pyproject.tomlwith cleaner dependency specificationsuv.lockwith updated dependency tree5. Developer Experience
README.mdfor quick project overviewREADME.dev.mdwith detailed developer documentationMakefilewith improved development commandsMIGRATION.md(integrated into main documentation)MAINTAINER_GUIDE.mdbatch_fix_services.pyCONFIGURATION.mdandCONTRIBUTING.mdFiles Changed
180 files affected with +19,192 insertions, -18,302 deletions
Test Plan
uv run pytest tests/Breaking Changes
None - This is a refactoring that maintains backward compatibility. All imports have been updated, and the public API remains unchanged.
Migration Notes
No migration required for users. All changes are internal to the codebase structure.