Commit graph

112 commits

Author SHA1 Message Date
Luis Novo
faa2b16e77
docs: codify the release confidence process with executable tooling (#1052)
Captures the process designed and executed for v1.11.0 so every future
release reproduces it:

- .github/RELEASE_PROCESS.md v2: changelog audit, risk-based test
  matrix (buckets A/B/C), the Docker image gate, fix-loop re-test
  policy, CI-based publishing path, communication structure with a
  mandatory credits section, retro, and the gotchas that cost
  iterations this cycle
- ADR-005: why releases now pass a risk-based confidence process gated
  on the real image, with the v1.11.0 evidence (bugs the unit suite
  could not catch: SEARCH-index ORDER BY 500, credential clear no-op)
- scripts/release-test/: the harness built during v1.11.0 —
  fresh-install + upgrade gate (release-image-test.sh) and the
  browsable RC stack with optional dev-data copy (rc-stack.sh), plus
  compose/nginx encoding the API_URL, host.docker.internal and
  SurrealDB import learnings
- make release-test / release-stack / release-stack-down targets
2026-07-11 16:56:14 -03:00
Marcos García
4e96a274f2
fix: remove deprecated gemini models (#1027)
* fix: update Google model version in connection tester and tests

* fix: updated the gemini model lists that references deprecated models

* fix: update also documentation. This is more prone to not follow the maintainer's directives, so PTADL

* fix: forgot two references to gemini deprecated versions

* fix: use valid, longer-lived gemini model IDs

Several IDs the PR introduced don't exist or are near shutdown, verified
against Google's official model/deprecation pages (2026-07):
- connection test model gemini-2.5-flash -> gemini-3.5-flash (2.5-flash
  retires 2026-10-16; 3.5-flash is the current stable GA and Google's
  named replacement, so the #970 fix doesn't re-break in ~3 months)
- gemini-3.5-pro (does not exist) -> gemini-2.5-pro in docs
- plain gemini-3.1-flash (not a GA Gemini-API id) dropped from the Vertex
  discovery list / preferences / docs; use gemini-3.5-flash or -flash-lite
- dead gemini-pro dropped from preferences and docs
Ported #996's #970 regression test, pinned to gemini-3.5-flash.

---------

Co-authored-by: Luis Novo <lfnovo@gmail.com>
2026-07-10 15:59:56 -03:00
Pico
c04c52cc0f
chore: remove dead auth helper and fix stale default-password docs (#1026)
check_api_password() (an unused HTTPBearer-based dependency, superseded
by PasswordAuthMiddleware) and its now-unused imports are dead code -
nothing calls it. Removed.

Docs across api/CLAUDE.md, docs/3-USER-GUIDE/api-configuration.md,
docs/5-CONFIGURATION/security.md, docs/7-DEVELOPMENT/security.md, and
docs/SECURITY_REVIEW.md still described a hardcoded default password
("open-notebook-change-me") that PasswordAuthMiddleware doesn't actually
have - if OPEN_NOTEBOOK_PASSWORD is unset, auth is fully disabled
instead. Updated to match actual behavior.
2026-07-10 15:47:40 -03:00
Luis Novo
b38c74cf29
docs: restructure documentation around AGENTS.md, VISION.md and decision records (#1032)
* docs: restructure documentation around AGENTS.md, VISION.md and decision records

- Consolidate 17 CLAUDE.md files into 3 AGENTS.md (root, backend, frontend);
  CLAUDE.md files become @AGENTS.md pointers
- Add VISION.md: product identity + current posture with horizon clusters
- Add docs/7-DEVELOPMENT/decisions/ with 4 retroactive ADRs and 2 PDRs
- Add 5 new engineering docs pages (credentials, content-processing,
  podcasts, prompts, frontend) absorbing knowledge from removed CLAUDE.md
- Dismember TRIAGE.md: label taxonomy into maintainer-guide.md, product
  jurisprudence into VISION.md, operator heuristics stay local (gitignored)
- Add AI-assisted/agent-generated PR guidelines to contributing.md
- Convert README.dev.md into a pointer after migrating its unique content
  (make workflow matrix, Docker publishing, add-a-language playbook)
- Fix stale docs: migration path/format, provider count, locale list;
  fix broken links (docs/index.md, PR template, CONFIGURATION.md)

* docs: fix README doc links and add markdown link check to CI

- Repoint 9 README links to pages that actually exist in docs/
- Replace literal (link) placeholder in maintainer-guide templates
- Add scripts/check_md_links.py validating relative links in tracked
  markdown (skips URLs, anchors and code spans)
- Add docs-links workflow running the check on PRs that touch markdown

* docs: add documentation restructure to changelog

* feat: add cubic.yaml with project-aware AI review agents

Three custom review agents (vision & principles alignment backed by
VISION.md, known mechanical caveats, security & testability), PR-contract
review instructions, and automatic ultrareviews for auth, credential,
encryption and migration changes.

* docs: graduate issue-first policy by change size

Small obvious fixes (typos, docs, tiny bugs, i18n completions) no longer
require an issue; features and architecture changes still do. Sizeable
PRs opened without an issue convert to draft while the issue goes
through triage (1-2 days). Applied consistently across contributing
guide, root CONTRIBUTING pointer, PR template, maintainer guide red
flags and cubic review instructions.

* docs: align PR template Related Issue section with graduated issue-first policy

* docs: address review — generalize ADR-002/004, unwrap hard-wrapped lines

- ADR-002 now records the general delegation rule (platform/media support
  that needs heavy coding lives in focused external libraries) covering
  Esperanto, Content Core and podcast-creator
- ADR-004 now records the durable decision (long-running work runs on
  background workers — heavy content, varied machine sizes, never lock
  usage) with the queue technology as a swappable implementation detail
  pending #381
- Remove mid-paragraph hard line wrapping from authored docs to match
  repo convention (one line per paragraph)

* fix: address cubic review — stale doc facts, make dev/full targets, link checker query strings

- credentials.md: only PROVIDER_CONFIG exists as a map; Vertex/Azure/
  OpenAI-compatible provisioning is inline in _provision_*() functions
- content-processing.md: correct ContextConfig priority weights
  (source 100 > insight 75 > note 50)
- development-setup.md + Makefile: make dev/full pointed at root compose
  files that don't exist; targets now use examples/docker-compose-dev.yml
  and examples/docker-compose-full-local.yml with --project-directory .
- check_md_links.py: strip query strings before file-existence checks
2026-07-10 15:33:19 -03:00
Pico
4d8fd72c1b
fix: contain podcast audio paths and batch job-status lookups (#1018)
Two small fixes to the podcast episode-listing path, plus a doc note:

- audio_file is only ever set server-side today from a UUID-named
  directory under PODCASTS_FOLDER, so this can't currently be tripped -
  but the stream/retry/delete endpoints didn't verify the resolved path
  actually stayed within PODCASTS_FOLDER before following it. Add
  _is_audio_path_contained() as defense in depth against a future code
  path (e.g. importing external audio) setting audio_file to something
  else.

- Listing episodes called get_job_detail() -> get_command_status() once
  per episode, each its own round trip (no connection pooling). Add
  PodcastEpisode.get_job_details_for_commands() to batch-fetch status
  for every episode's command in one query instead.

Also documents (docs/7-DEVELOPMENT/security.md) that podcast_creator's
configure("templates", {...}) compiles strings as Jinja2 template
source - the same shape as the SSTI vulnerability fixed in
transformation.py (GHSA-f35w-wx37-26q7). Confirmed dormant: no code path
in this repo calls it today. commands/podcast_commands.py gets a
matching code comment warning against wiring user text into it if a
"custom podcast template" feature is ever added.
2026-07-10 13:48:24 -03:00
Pico
5316b1a8f3
fix: reject oversized request bodies before auth/routing (#1014)
* fix: reject oversized request bodies before auth/routing

No limit existed on request body size, so a single upload could exhaust
memory/disk before any validation ran. MaxBodySizeMiddleware
(api/middleware.py) rejects requests over OPEN_NOTEBOOK_MAX_UPLOAD_SIZE_MB
(default 100MB) via both a Content-Length pre-check and by counting bytes
as the body streams in, so it also catches chunked requests with no
Content-Length header.

Registered after PasswordAuthMiddleware (wrapping it) so oversized
requests are rejected before spending any work on credential checks, and
inside CORSMiddleware so a rejected upload still gets CORS headers.

* fix: clamp non-positive size limits and log rejected requests

OPEN_NOTEBOOK_MAX_UPLOAD_SIZE_MB=0 (or negative) made every request with a
body 413; fall back to the default instead, with a warning. Also log each
413 rejection so operators can diagnose failed uploads.

---------

Co-authored-by: Luis Novo <lfnovo@gmail.com>
2026-07-10 11:15:18 -03:00
Pico
fd7dee7ced
fix: don't combine wildcard CORS origins with allow_credentials (#1013)
* fix: don't combine wildcard CORS origins with allow_credentials

Combining allow_origins=["*"] with allow_credentials=True makes
Starlette's CORSMiddleware reflect the request's Origin header verbatim
instead of returning a literal "*" (browsers reject a literal wildcard
alongside credentials) - defeating the origin allowlist for any
credentialed request.

allow_credentials is now tied to whether CORS_ORIGINS was explicitly
scoped: False for the default wildcard, True once an operator opts into
specific origins. _cors_headers() (the manual CORS builder for error
responses raised before CORSMiddleware runs) is updated to match, so it
can't grant credentials the real middleware wouldn't.

Not independently exploitable today (the frontend never sends
credentialed requests, and auth is a Bearer header, not a cookie), but
there's no reason to allow it for the default wildcard case.

* fix: key allow_credentials on the parsed origins list, not the env var

An operator who explicitly sets CORS_ORIGINS=* got allow_credentials=True
with a wildcard origin list - the exact reflect-any-Origin behavior this
change exists to prevent. Introduce CORS_ALLOW_CREDENTIALS keyed on the
parsed list containing '*' and use it at both the middleware registration
and the manual error-response headers; replace the tautological formula
tests with ones exercising the real parser.

---------

Co-authored-by: Luis Novo <lfnovo@gmail.com>
2026-07-10 11:10:41 -03:00
Georgij
ad6464d45b
feat: make API listen host configurable via API_HOST (#986)
* unhardcode api listen host

* fix: keep 0.0.0.0 as API_HOST default, document the variable

---------

Co-authored-by: Luis Novo <lfnovo@gmail.com>
2026-07-03 12:58:45 -03:00
Luis Novo
c2e117e2ab
docs: fix Windows native guide referencing missing launcher script (#958)
Rewrite the Windows native Quick Start to start the four services manually via uv run, and add an optional sample launcher users can save themselves, instead of pointing at a start-open-notebook.bat that the repo never shipped.

Fixes #846
2026-06-21 19:35:51 -03:00
Luis Novo
f2efa0c6fb
docs: document ESPERANTO_TTS_TIMEOUT env var (#952)
Documents ESPERANTO_TTS_TIMEOUT (default 300s) in the environment reference; raise it for slow/self-hosted TTS providers.

Fixes #937
2026-06-21 15:34:24 -03:00
Luis Novo
d7e1fdbc4c
docs: add EasyPanel deployment to single-container guide (#948)
Some checks are pending
Development Build / extract-version (push) Waiting to run
Development Build / build-regular (push) Blocked by required conditions
Development Build / build-single (push) Blocked by required conditions
Development Build / summary (push) Blocked by required conditions
Tests / Backend Tests (push) Waiting to run
Tests / Frontend Tests (push) Waiting to run
Documents the EasyPanel template (examples/easypanel/) in the cloud-platform deploy list, covering the one-click gallery flow and the manual playground flow. Notes it provisions the app + a dedicated SurrealDB with generated secrets.

Refs #189
2026-06-21 15:21:03 -03:00
Luis Novo
61bfe82643
docs: fix local quickstart and document the worker step (#900)
quick-start-local.md (#781):
- add the required OLLAMA_BASE_URL=http://ollama:11434 env var to the
  open_notebook service (already present in examples/docker-compose-ollama.yml)
- correct the provider/model setup navigation from "Settings → API Keys" to
  the actual "Manage → Models" location

from-source.md (#779):
- add a "Start Worker" step between API and Frontend; without the
  surreal-commands worker, sources stay stuck at CommandStatus.NEW
- fix the same outdated "Settings → API Keys" navigation reference
2026-06-16 04:29:32 -03:00
Leon.C
075686a679
docs: add Code of Conduct (Contributor Covenant v2.1) (#856)
* docs: add Code of Conduct (Contributor Covenant v2.1)

The contributing guide references a Code of Conduct that contributors
are expected to uphold, but the file was missing. This adds the
standard Contributor Covenant v2.1 and links to it from the
contributing guide.

* docs: point Code of Conduct enforcement contact to project channels

Replace the placeholder conduct@opennotebook.dev address (not a project
domain) with the open-notebook.ai contact form and the project Discord.

---------

Co-authored-by: zichen0116 <zichen0116@users.noreply.github.com>
Co-authored-by: Luis Novo <lfnovo@gmail.com>
2026-06-13 09:13:49 -03:00
doganreis
0aaaa32455
feat(i18n): add Turkish (tr-TR) translation (#871)
* feat(i18n): add Turkish (tr-TR) translation

* fix(i18n): derive LanguageCode from resources to avoid sync drift

* fix(i18n): make Turkish selectable and fix tr-TR syntax errors

- Fix unescaped quotes in tr-TR search strings that broke the build
- Add Turkish entry to LanguageToggle so it is selectable in the UI
- Register Turkish date-fns locale for date formatting
- Add turkish language name key across all locales for consistency

---------

Co-authored-by: Luis Novo <lfnovo@gmail.com>
2026-06-13 08:46:15 -03:00
Luis Novo
f8625a5811
feat: bump esperanto to 2.22.0 + Ollama num_ctx override (#833)
Upgrade esperanto 2.20.0 -> 2.22.0. The constraint (>=2.20.0,<3) already
allowed it; this relocks and picks up upstream fixes (OpenRouter json body,
clearer null-embedding errors, streaming ToolCall objects, base_url
trailing-slash normalization, Ollama thinking-model content).

Esperanto 2.21.0 lowered the Ollama num_ctx default from 128000 to 8192 to
avoid OOM on consumer GPUs. We keep that safe default and add an optional
per-credential num_ctx override for self-hosters whose hardware can handle a
larger context window:

- Credential gains a num_ctx field, surfaced via to_esperanto_config() so it
  flows into AIFactory automatically (no ModelManager change needed).
- Credential create/update API schemas + router pass num_ctx through.
- Frontend: optional numeric field on the Ollama credential form, with i18n
  labels translated across all 13 locales.
- Docs: document the new default and the override under AI providers.

Closes #825
2026-06-02 06:20:24 -03:00
TianjinAI
ce7e0b5d3b
docs: add windows native installation guide (#463)
* docs: add windows native installation guide

Added a comprehensive installation guide for Open Notebook on Windows, covering prerequisites, setup steps, critical fixes, and troubleshooting.

* docs: move windows native guide into 1-INSTALLATION and link from index

---------

Co-authored-by: Luis Novo <lfnovo@gmail.com>
2026-06-02 04:57:05 -03:00
Luis Novo
f2182dbdce
fix(embedding): drop degenerate tiny chunks before embedding (#764) (#768)
Some checks failed
Development Build / extract-version (push) Has been cancelled
Tests / Backend Tests (push) Has been cancelled
Tests / Frontend Tests (push) Has been cancelled
Development Build / build-regular (push) Has been cancelled
Development Build / build-single (push) Has been cancelled
Development Build / summary (push) Has been cancelled
Header-based splitters (notably HTMLHeaderTextSplitter on complex pages
like Wikipedia or Project Gutenberg) can emit single-character or
punctuation-only chunks. Some embedding providers — including
llama.cpp's OpenAI-compatible endpoint — return null vector elements
for such inputs, which then crash response parsing in Esperanto with
'TypeError: float() argument must be a string or a real number, not
NoneType'.

chunk_text() now filters chunks below OPEN_NOTEBOOK_MIN_CHUNK_SIZE
tokens (default 5) after splitting. The filter is bypassed when it
would empty the result list, so legitimately short documents are
preserved.
2026-05-31 09:43:47 -03:00
fromnewcoder
5e432b1f23
docs: add external Ollama setup guide (#812)
* docs: add external Ollama setup guide

Add guide for users who have Ollama installed separately and don't
want Docker to run the Ollama service. Includes connection instructions
for host.docker.internal routing.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* chore: remove obsolete test for Ollama embeddings API

* chore: remove ARCHITECTURE_DIAGRAMS.md file

---------

Co-authored-by: jjay <jjay@gmail.com>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-29 10:30:52 -03:00
Luis Novo
ec41ef8f2f
feat(api): add configurable CORS origins via CORS_ORIGINS (#767)
Some checks failed
Development Build / extract-version (push) Has been cancelled
Tests / Backend Tests (push) Has been cancelled
Tests / Frontend Tests (push) Has been cancelled
Development Build / build-regular (push) Has been cancelled
Development Build / build-single (push) Has been cancelled
Development Build / summary (push) Has been cancelled
Replace hardcoded `allow_origins=["*"]` with a parsed `CORS_ORIGINS`
environment variable (comma-separated). Default remains `*` for
backward compatibility — no existing deployment breaks — but the API
now logs a startup warning prompting users to set it explicitly for
production.

Exception handlers now route their CORS headers through a shared
`_cors_headers()` helper that mirrors Starlette's CORSMiddleware
behavior: reflects the request Origin when allowed (handling the
browser-rejected `*` + credentials combination correctly), and omits
`Access-Control-Allow-Origin` for disallowed origins so error bodies
don't leak cross-origin when `CORS_ORIGINS` is configured.

Closes #585, #730.

Based on the original work by Greg Grace in #597; rewritten on top of
current main to address prior review feedback (load_dotenv kept at
top, `import os` grouped with stdlib, `_cors_headers` defined before
its exception-handler callers, origins parsed once at module load)
and to choose a non-breaking default paired with a startup warning
instead of a stricter-by-default origin.

Co-authored-by: Greg Grace <ggrace@519lab.com>
2026-04-19 16:22:10 -03:00
Artyom Mezin
4efe613f69
Make embedding batch size configurable (#742)
* Make embedding batch size configurable

* Address embedding batch size review nits
2026-04-19 15:37:42 -03:00
Luis Novo
66a10996da
Merge pull request #734 from vincentrou/fix-docs-quick-start-local
Some checks failed
Development Build / extract-version (push) Has been cancelled
Tests / Backend Tests (push) Has been cancelled
Tests / Frontend Tests (push) Has been cancelled
Development Build / build-regular (push) Has been cancelled
Development Build / build-single (push) Has been cancelled
Development Build / summary (push) Has been cancelled
Update docs quick start local
2026-04-17 09:01:34 -03:00
Rousseau Vincent
b3452582c9
Remove reference to OLLAMA_NUM_GPU 2026-04-15 16:26:14 +02:00
Luis Novo
4222329451
fix: map base_url to endpoint for Azure credentials (#741)
* fix: map base_url to endpoint for Azure credentials

The Azure credential form only exposes a base_url field, but the
connection tester, key provisioner, and Esperanto config all expect
an endpoint field. This maps base_url to endpoint for Azure providers
so credentials work without requiring a dedicated endpoint form field.

Closes #727

* docs: update Azure credential docs to reflect base_url mapping
2026-04-09 13:22:00 -03:00
Luis Novo
8ee18d1fb7 docs: add security guidelines for contributors
Add security.md covering database query safety, template rendering,
file handling, secrets management, and a code review checklist.
Informed by CERT-EU coordinated vulnerability disclosures.
2026-04-09 12:16:09 -03:00
Rousseau Vincent
ff3525e46b
Update surrealdb user and add gpu for ollama
Added user root for surrealdb service and nvidia GPU support in ollama service.
2026-04-08 10:22:33 +02:00
Luis Novo
3934fe7e5e chore: bump version to 1.8.2 and update changelog and provider docs
- Bump version from 1.8.1 to 1.8.2
- Add changelog entry for DashScope and MiniMax provider support
- Update provider counts across README and docs (16+ → 18+, 15+ → 17+)
- Add DashScope and MiniMax to README provider support matrix
2026-04-06 10:59:47 -03:00
Luis Novo
adc03e56bb feat: add DashScope (Qwen) and MiniMax provider support
- Bump esperanto dependency to >=2.20.0 for new provider profiles
- Register both providers in credentials, key provider, connection tester, model discovery, and models router
- Add frontend provider entries (display names, modalities, docs links)
- Add documentation sections for both providers in ai-providers.md, environment-reference.md, and provider comparison
2026-04-06 10:54:37 -03:00
Luis Novo
746218248c docs: add surrealdb service notes to docker-compose snippets
The v1-latest image requires a separate surrealdb service unlike the
deprecated single-container image. Add comments pointing to the full
base docker-compose.yml in all partial code examples.
2026-04-06 08:15:33 -03:00
Luis Novo
309004aef4 docs: deprecate single-container image in favor of Docker Compose
The v1-single image is being phased out ahead of v2. This adds
deprecation notices to the single-container docs and replaces
v1-latest-single image references with v1-latest across all
configuration guides and issue templates.

Closes #498
2026-04-06 08:10:32 -03:00
dobberr
4f259e2166
Fixed surrealdb being stuck (#656)
Removed healthcheck comment and adjusted environment variables.
2026-03-10 21:33:25 -03:00
Luis Novo
eac837d555
feat(podcasts): model registry integration, credential passthrough & new features (#632)
Some checks failed
Development Build / extract-version (push) Has been cancelled
Tests / Backend Tests (push) Has been cancelled
Tests / Frontend Tests (push) Has been cancelled
Development Build / build-regular (push) Has been cancelled
Development Build / build-single (push) Has been cancelled
Development Build / summary (push) Has been cancelled
* feat(podcasts): integrate model registry for profiles and credential passthrough

Replace loose provider/model string fields with record<model> references
in podcast profiles, enabling credential passthrough to podcast-creator.

Backend:
- EpisodeProfile: outline_llm, transcript_llm (record<model>) replace
  outline_provider/outline_model strings. New language field (BCP 47).
- SpeakerProfile: voice_model (record<model>) replaces tts_provider/
  tts_model strings. Per-speaker voice_model override support.
- Migration 14: schema changes making legacy fields optional, adding new
  record<model> fields.
- Data migration (migration.py): auto-converts legacy profiles to model
  registry references on startup. Idempotent.
- podcast_commands.py: resolves credentials for ALL profiles before
  calling podcast-creator.
- New /api/languages endpoint (pycountry + babel) with BCP 47 locale
  codes (pt-BR, en-US, etc.).

Frontend:
- Episode/speaker profile forms use ModelSelector instead of manual
  provider/model dropdowns.
- Language dropdown with BCP 47 codes in episode profile form.
- Per-speaker TTS voice model override in speaker profile form.
- "Templates" tab renamed to "Profiles".
- Setup required badge on unconfigured profiles.
- i18n updated across all 8 locales.

Closes #486, closes #552

* fix(i18n): remove unused legacy podcast provider/model keys

Remove 10 orphaned i18n keys across all 8 locales that were left behind
after replacing manual provider/model dropdowns with ModelSelector.

* fix: address review violations in podcast model registry

- P1: Remove profiles with failed model resolution from dicts to prevent
  podcast-creator validation errors on unrelated profiles
- P2: Use centralized QUERY_KEYS.languages instead of inline key
- P3: Fix ISO 639-1 → BCP 47 in model field description and CLAUDE.md
- P3: Update "templates" → "profiles" in locale string values (all 8)

* chore: bump version to 1.8.0
2026-02-27 11:06:47 -03:00
Luis Novo
ce64a5f20c
fix(docker): pin SurrealDB version and fix single-container docs (#629)
Some checks failed
Development Build / extract-version (push) Has been cancelled
Tests / Backend Tests (push) Has been cancelled
Tests / Frontend Tests (push) Has been cancelled
Development Build / build-regular (push) Has been cancelled
Development Build / build-single (push) Has been cancelled
Development Build / summary (push) Has been cancelled
- Replace curl-based SurrealDB install in Dockerfile.single with a
  multi-stage build that copies the binary from surrealdb/surrealdb:v2,
  aligning it with the version used in docker-compose.yml and preventing
  breakage when newer SurrealDB versions introduce syntax changes.
- Fix SURREAL_PASSWORD documentation in single-container.md: the actual
  password set in supervisord.single.conf is `root`, not `password`.

Closes #498
2026-02-25 20:32:29 -03:00
Luis Novo
c7a457ee78 docs: add missing SURREAL_NAMESPACE and SURREAL_DATABASE env vars
The inline docker-compose example in README and the environment
variable reference tables in installation docs were missing these
two required variables, causing connection failures for users who
copy-pasted the examples instead of downloading the actual file.

Closes #592
2026-02-18 22:16:15 -03:00
Luis Novo
924cd88494
docs: update documentation for error handling and podcast retry (#599)
Some checks are pending
Development Build / extract-version (push) Waiting to run
Development Build / build-regular (push) Blocked by required conditions
Development Build / build-single (push) Blocked by required conditions
Development Build / summary (push) Blocked by required conditions
Tests / Backend Tests (push) Waiting to run
Tests / Frontend Tests (push) Waiting to run
* docs: update CLAUDE.md and user docs for error handling and podcast retry

Add missing documentation for features introduced in v1.7.2 (#590) and
v1.7.3 (#595): error classification system, global exception handlers,
ConfigurationError, podcast failure recovery, and retry endpoint.

* chore: update uv.lock
2026-02-18 09:56:04 -03:00
Luis Novo
9811c58d15
docs: fix docker container names in local setup guides (#577)
Some checks are pending
Development Build / extract-version (push) Waiting to run
Development Build / build-regular (push) Blocked by required conditions
Development Build / build-single (push) Blocked by required conditions
Development Build / summary (push) Blocked by required conditions
Docker Compose v2 derives container names from the directory name using
dashes. Since the docs instruct users to create an `open-notebook-local`
folder, the correct container name is `open-notebook-local-ollama-1`,
not `open_notebook-ollama-1`.

Fixes #575
2026-02-14 18:38:32 -03:00
Luis Novo
3f352cfcce
feat: credential-based API key management (#477) (#540)
* feat: replace provider config with credential-based system (#477)

Introduce a new credential management system replacing the old
ProviderConfig singleton and standalone Models page. Each credential
stores encrypted API keys and provider-specific configuration with
full CRUD support via a unified settings UI.

Backend:
- Add Credential domain model with encrypted API key storage
- Add credentials API router (CRUD, discovery, registration, testing)
- Add encryption utilities for secure key storage
- Add key_provider for DB-first env-var fallback provisioning
- Add connection tester and model discovery services
- Integrate ModelManager with credential-based config
- Add provider name normalization for Esperanto compatibility
- Add database migrations 11-12 for credential schema

Frontend:
- Rewrite settings/api-keys page with credential management UI
- Add model discovery dialog with search and custom model support
- Add compact default model assignments (primary/advanced layout)
- Add inline model testing and credential connection testing
- Add env-var migration banner
- Update navigation to unified settings page
- Remove standalone models page and old settings components

i18n:
- Update all 7 locale files with credential and model management keys

Closes #477

Co-Authored-By: JFMD <git@jfmd.us>
Co-Authored-By: OraCatQAQ <570768706@qq.com>

* fix: address PR #540 review comments

- Fix docs referencing removed Models page
- Fix error-handler returning raw messages instead of i18n keys
- Fix auth.py misleading docstring and missing no-password guard
- Fix connection_tester using wrong env var for openai_compatible
- Add provision_provider_keys before model discovery/sync
- Update CLAUDE.md to reflect credential-based system
- Fix missing closing brace in api-keys page useEffect

* fix: add logging to credential migration and surface errors in UI

- Add comprehensive logging to migrate-from-env and
  migrate-from-provider-config endpoints (start, per-provider
  progress, success/failure with stack traces, final summary)
- Fix frontend migration hooks ignoring errors array from response
- Show error toast when migration fails instead of "nothing to migrate"
- Invalidate status/envStatus queries after migration so banner updates

* docs: update CLAUDE.md files for credential system

Replace stale ProviderConfig and /api-keys/ references across 8 CLAUDE.md
files to reflect the new Credential-based system from PR #540.

* docs: update user documentation for credential-based system

Replace env var API key instructions with Settings UI credential
workflow across all user-facing documentation. The new flow is:
set OPEN_NOTEBOOK_ENCRYPTION_KEY → start services → add credential
in Settings UI → test → discover models → register.

- Rewrite ai-providers.md, api-configuration.md, environment-reference.md
- Update all quick-start guides and installation docs
- Update ollama.md, openai-compatible.md, local-tts/stt networking sections
- Update reverse-proxy.md, development-setup.md, security.md
- Fix broken links to non-existent docs/deployment/ paths
- Add credentials endpoints to api-reference.md
- Move all API key env vars to deprecated/legacy sections

* chore: bump version to 1.7.0-rc1

Release candidate for credential-based provider management system.

* fix: initialize provider before try block in test_credential

Prevents UnboundLocalError when Credential.get() throws (e.g.,
invalid credential_id) before provider is assigned.

* fix: reorder down migration to drop index before table

Removes duplicate REMOVE FIELD statement and reorders so the index
is dropped before the table, preventing rollback failures.

* refactor: simplify encryption key to always derive via SHA-256

Remove the dual code path in _ensure_fernet_key() that detected native
Fernet keys. Since the credential system is new, always deriving via
SHA-256 removes unnecessary complexity. Also removes the generate_key()
function and Fernet.generate_key() references from docs.

* fix: correct mock patch targets in embedding tests and URL validation

Fix embedding tests patching wrong module path for model_manager
(was targeting open_notebook.utils.embedding.model_manager but it's
imported locally from open_notebook.ai.models). Also fix URL validation
to allow unresolvable hostnames since they may be valid in the
deployment environment (e.g., Azure endpoints, internal DNS).

* feat: add global setup banner for encryption and migration status

Show a persistent banner in AppShell when encryption key is missing
(red) or env var API keys can be migrated (amber), so users see
these prompts on every page instead of only on Settings > API Keys.

Includes a docs link for the encryption banner and i18n support
across all 7 locales.

* docs: several improvements to docker-compose e env examples

* Update README.md

Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>

* docs: fix env var format in README and update model setup instructions

Align the encryption key snippet in README Step 2 with the list
format used in the compose file. Replace deprecated "Settings →
Models" instructions with credential-based Discover Models flow.

* fix: address credential system review issues

- Fix SSRF bypass via IPv4-mapped IPv6 addresses (::ffff:169.254.x.x)
- Fix TTS connection test missing config parameter
- Add Azure-specific model discovery using api-key auth header
- Add Vertex static model list for credential-based discovery
- Fix PROVIDER_DISCOVERY_FUNCTIONS incorrect azure/vertex mapping
- Extract business logic to api/credentials_service.py (service layer)
- Move credential Pydantic schemas to api/models.py
- Update tests to use new service imports and ValueError assertions

* fix: sanitize error responses and migrate key_provider to Credential

- Replace raw exception messages in all credential router 500 responses
  with generic error strings (internal details logged server-side only)
- Refactor key_provider.py to use Credential.get_by_provider() instead
  of deprecated ProviderConfig.get_instance()
- Remove unused functions (get_provider_configs, get_default_api_key,
  get_provider_config) that were dead code

---------

Co-authored-by: JFMD <git@jfmd.us>
Co-authored-by: OraCatQAQ <570768706@qq.com>
2026-02-10 08:30:22 -03:00
Nikita
2137758103
docs: add local STT setup guide (#521)
Some checks failed
Development Build / extract-version (push) Has been cancelled
Development Build / build-regular (push) Has been cancelled
Development Build / build-single (push) Has been cancelled
Development Build / summary (push) Has been cancelled
Add comprehensive documentation for setting up local speech-to-text
using Speaches with faster-whisper. Includes model recommendations,
GPU acceleration, Docker networking, and troubleshooting.

Also updates related docs with cross-references to the new guide.

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-01 18:54:49 -03:00
Luis Novo
303ffacfa5
docs: add reverse proxy timeout configuration (#501)
Some checks failed
Development Build / extract-version (push) Has been cancelled
Development Build / build-regular (push) Has been cancelled
Development Build / build-single (push) Has been cancelled
Development Build / summary (push) Has been cancelled
* chore: force env file on api

* docs: add reverse proxy timeout configuration for all proxies

- Add timeout configuration to Caddy examples (read_timeout, write_timeout)
- Add Traefik serversTransport timeout configuration
- Increase nginx timeout from 300s to 600s to match frontend
- Expand timeout troubleshooting section with symptoms and solutions
- Reference API_CLIENT_TIMEOUT and ESPERANTO_LLM_TIMEOUT env vars

Fixes #447
2026-01-30 00:02:03 -03:00
Luis Novo
b1d4c5cd34
fix: Docker networking and permissions documentation (#500)
* chore: force env file on api

* fix: Docker networking and permissions documentation

- Add HOSTNAME=0.0.0.0 as default in Dockerfiles for reverse proxy compatibility
- Document Linux extra_hosts requirement for host.docker.internal
- Add user: root to SurrealDB examples for bind mount permissions on Linux
- Update environment reference and reverse proxy docs

Fixes #483, fixes #485, fixes #409
2026-01-29 23:54:17 -03:00
Luis Novo
03f9edfec2
feat: use standard HTTP_PROXY/HTTPS_PROXY environment variables (#499)
Update proxy configuration to use industry-standard environment variables
(HTTP_PROXY, HTTPS_PROXY, NO_PROXY) instead of custom variables.

The underlying libraries (esperanto, content-core, podcast-creator)
now automatically detect proxy settings from these standard variables.

- Bump content-core>=1.14.1 (fixes #494)
- Bump esperanto>=2.18
- Bump podcast-creator>=0.9
- Update documentation with new proxy configuration
2026-01-29 23:31:02 -03:00
Luis Novo
47c513edfd
fix: improve error logging for chat model configuration issues (#458)
Some checks are pending
Development Build / extract-version (push) Waiting to run
Development Build / test-build (push) Blocked by required conditions
Development Build / summary (push) Blocked by required conditions
* docs: update CHANGELOG for v1.6.0 release

* fix: improve error logging for chat model configuration issues (#358)

- Add detailed error logging in provision.py when model lookup fails
- Add warning logging in models.py when default model is not configured
- Add traceback logging in chat router exception handler
- Update Ollama docs with model name configuration guidance
- Update troubleshooting docs with "Failed to send message" solutions
- Bump version to 1.6.1

* chore: uvlock
2026-01-23 16:45:13 -03:00
nanshaws
9c61ffef9a
docs: add conda installation instructions to README (#446)
* docs: add conda installation instructions to README

docs: add conda installation instructions to README

* docs: add conda environment setup as an alternative to uv

docs: add conda environment setup as an alternative to uv
2026-01-18 16:50:19 -03:00
LUIS NOVO
136698864e feat: upgrade Next.js 15 → 16 to fix large file uploads
- Upgrade Next.js from 15.4.10 to 16.1.1
- Upgrade React from 19.1.0 to 19.2.3
- Rename middleware.ts → proxy.ts (Next.js 16 requirement)
- Update function name: middleware → proxy
- Enable proxyClientMaxBodySize configuration (now supported in Next.js 16)
- Update documentation to reference Next.js 16 requirement
- Fix upload size limit issue for files >10MB

This upgrade fixes GitHub issue #361 where users cannot upload files
larger than 10MB. The proxyClientMaxBodySize configuration option was
introduced in Next.js 16.1+ and allows configuring the proxy body size
limit to 100MB.

Fixes #361
Related to PR #405
2026-01-14 10:33:19 -03:00
Luis Novo
bdfdc9eecd
Merge pull request #404 from lfnovo/fix/cors-headers-on-error-responses
fix: add CORS headers to error responses and document file upload limits
2026-01-09 20:09:04 -03:00
LUIS NOVO
52177f7546 fix: add CORS headers to error responses and document file upload limits
- Added custom exception handler to ensure CORS headers are included in
  all HTTP error responses from the API
- Added documentation for 413 (Payload Too Large) errors when behind
  reverse proxies (nginx, traefik, kubernetes ingress)
- Added client_max_body_size to nginx configuration examples
- Documented how to configure CORS headers for proxy-level error responses

Fixes #401
2026-01-09 20:08:13 -03:00
Luis Novo
b045694992
Merge pull request #400 from lfnovo/fix/surrealdb-persistent-storage
fix: use persistent rocksdb storage instead of memory in docker-compose docs
2026-01-09 20:06:16 -03:00
LUIS NOVO
fd03122aa3 fix: use persistent rocksdb storage instead of memory in docker-compose docs
Changed SurrealDB configuration from in-memory storage to RocksDB with
bind mounts for data persistence. Users' data will now survive container
restarts.

Fixes #398
2026-01-09 19:47:47 -03:00
Luis Novo
b8203db380
Merge pull request #396 from lfnovo/pr-346-mcp-integration
feat: add MCP integration documentation
2026-01-09 08:17:27 -03:00
Piotr Mrzygłowski
879e41a180 feat: add MCP integration documentation to README and create dedicated MCP integration guide 2026-01-09 08:14:39 -03:00
Luis Novo
76827af53f
Merge pull request #395 from lfnovo/docs/add-pull-policy-always
docs: add pull_policy always to docker-compose examples
2026-01-09 08:00:20 -03:00