86 improved env var management

.env.example

@@ -1,8 +1,11 @@
 # ===========================================
 # OntoCast Environment Configuration
-# Copy this file to .env and update with your values. OntoCast reads only the
-# environment, so load the file into your shell before running it:
-#   set -a; source .env; set +a
+# Copy the lines you need to your own file and pass it to the CLI:
+#   ontocast --env-file my.env serve
+# --env-file is repeatable (later files win; shell exports win over all), so
+# credentials and project settings can live in separate files. Keep only the
+# lines that differ from the defaults: `ontocast config check my.env` names
+# the redundant, unknown and invalid ones.
 #
 # This is the COMPLETE surface. If you are setting OntoCast up for the first
 # time, start from `.env.example.minimal` (the variables worth a decision,
@@ -89,8 +92,8 @@ ONTOLOGY_CONTEXT_SCOPE=unit              # unit | document
 # A prefix cache is populated by a request that has already *completed*, so a
 # fan-out issuing N calls that share a prefix simultaneously has all N miss it;
 # running one unit first turns the other N-1 into hits, at the wall-clock cost
-# of one serialized call. Only worth setting together with
-# ONTOLOGY_CONTEXT_SCOPE=document, where the calls actually share a prefix.
+# of one serialized call. Only worth setting together with document scope
+# (ONTOLOGY_CONTEXT_SCOPE above), where the calls actually share a prefix.
 FANOUT_WARMUP_UNITS=0
 # The catalog ontology for ONTOLOGY_CONTEXT_MODE=fixed_single_ontology, in
 # `ontocast process` and for server requests that name none; it does not change
@@ -127,7 +130,9 @@ ENABLE_ONTOLOGY_CONSOLIDATION=false
 # LLM Configuration
 # Available providers: openai, ollama, anthropic, google
 LLM_PROVIDER=openai
-LLM_MODEL_NAME=gpt-5.4
+LLM_MODEL_NAME=gpt-5.6-luna
+# Sent only where the model accepts it: OpenAI GPT-5.5+ takes it at
+# reasoning effort none only, and Claude Opus 4.7+ / Sonnet 5+ / Fable never.
 LLM_TEMPERATURE=0.0
 LLM_API_KEY=your_openai_api_key_here
 # LLM_CACHE_ENABLED=true
@@ -137,19 +142,19 @@ LLM_API_KEY=your_openai_api_key_here
 
 # Ollama Configuration (Alternative)
 # LLM_PROVIDER=ollama
-# LLM_MODEL_NAME=llama3.1
+# LLM_MODEL_NAME=qwen3.8
 # LLM_BASE_URL=http://localhost:11434
 # LLM_TEMPERATURE=0.0
 
 # Anthropic Claude (Alternative)
 # LLM_PROVIDER=anthropic
-# LLM_MODEL_NAME=claude-sonnet-4-20250514
+# LLM_MODEL_NAME=claude-sonnet-5-5
 # LLM_API_KEY=your_anthropic_api_key_here
 # LLM_TEMPERATURE=0.0
 
 # Google Gemini (Alternative)
 # LLM_PROVIDER=google
-# LLM_MODEL_NAME=gemini-2.0-flash
+# LLM_MODEL_NAME=gemini-3.7-flash
 # LLM_API_KEY=your_google_api_key_here
 # LLM_TEMPERATURE=0.0
 
@@ -734,7 +739,7 @@ LOGGING_LEVEL=info
 # and ignored. Both join the LLM cache key, so changing one re-issues every
 # prompt. Read budget.reasoning_share_of_output first: at 0.0 the model is not
 # a reasoning model and neither knob changes its bill.
-# Discrete reasoning depth: none | minimal | low | medium | high | xhigh
+# Discrete reasoning depth: none | minimal | low | medium | high | xhigh | max
 # (unset = provider default). Read by OpenAI reasoning models as
 # reasoning_effort and by Gemini 3+ as thinking_level. The vocabulary is the
 # union across providers and model generations -- the floor is spelled minimal

.env.example.minimal

@@ -8,9 +8,8 @@
 # Convention, as in `.env.example`: an uncommented line is one you should look
 # at; `#VAR=value` is optional and the value shown is the default.
 #
-# Copy this to .env and set LLM_API_KEY. OntoCast reads only the environment,
-# so load the file into your shell before running it:
-#   set -a; source .env; set +a
+# Copy this to your own file, set LLM_API_KEY, and pass it to the CLI:
+#   ontocast --env-file my.env serve
 # Then pick a recipe: https://growgraph.github.io/ontocast/guides/recipes/
 # ===========================================
 
@@ -32,9 +31,12 @@ ONTOCAST_ONTOLOGY_DIRECTORY=/path/to/ontology/files
 
 # -- 2. LLM ---------------------------------------------------------------
 LLM_PROVIDER=openai                  # openai | ollama | anthropic | google
-LLM_MODEL_NAME=gpt-4o-mini
+LLM_MODEL_NAME=gpt-5.6-luna
 LLM_API_KEY=your-api-key-here
 LLM_TEMPERATURE=0.0                  # leave at 0.0; extraction is not a creative task
+# Reasoning models may not accept it: OpenAI GPT-5.5+ uses it only with
+# reasoning effort none, and newer Claude models never; it is then not sent.
+#LLM_REASONING_EFFORT=                # none | minimal | low | medium | high | xhigh | max
 
 # Concurrent requests to the provider, shared across all content units. Lower
 # it when you hit rate limits -- this is the knob for that, not PARALLEL_WORKERS.
@@ -115,9 +117,10 @@ CHUNK_MAX_SIZE=12000
 # citations_only extracts bibliographic metadata instead.
 #CHUNK_BIBLIOGRAPHY_MODE=skip         # skip | citations_only | domain_facts
 
-# For publisher PDFs with selectable text: born_digital switches the backend and
-# repairs ligature gaps ("di ff usion"). Try it before reaching for OCR settings.
-#CONVERTER_PROFILE=default            # default | born_digital
+# auto checks each PDF for a text layer and skips OCR when it has one. Pin
+# fast (never OCR) or ocr (always) only when every input is of one kind; lean
+# is fast plus equations decoded to LaTeX, a model call per equation.
+#CONVERTER_PROFILE=auto               # auto | fast | lean | ocr
 
 
 # -- 6. Local embedding models (memory) ----------------------------------

CHANGELOG.md

@@ -5,113 +5,91 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- **`ontocast --env-file FILE`** (repeatable): load settings files in order; later files and
+  shell exports override earlier ones.
+- **`ontocast config check FILE...`**: classify variables as unknown, invalid, redundant, or
+  pinned; exit 1 on unknown or invalid.
+- **Model presets** for GPT-5.6, GPT-6, Gemini 3.x, and current Ollama catalog models.
+- **`LLM_REASONING_EFFORT=max`**.
+
+### Changed
+
+- **Default model** is `gpt-5.6-luna` (was `gpt-5.4`); cached LLM entries for the old default
+  are not reused.
+- **Claude presets** use provider API IDs; legacy `claude-4.x-*-latest` aliases removed.
+- **Gemini 2.x and 1.5 presets** removed; other Gemini names still pass through with a warning.
+
+### Fixed
+
+- **`temperature`** omitted for models that reject it (OpenAI GPT-5.5+ unless
+  `LLM_REASONING_EFFORT=none`; Claude Opus 4.7+, Sonnet 5+, Fable/Mythos), including GPT-6.
+- **`gpt-4.1` / `gpt-4.1-mini`** preset IDs (was `gpt-41` / `gpt-41-mini`).
+- **`WEB_SEARCH_ALLOWED_DOMAINS` / `WEB_SEARCH_BLOCKED_DOMAINS`** accept comma-separated lists
+  and empty values without failing startup.
+- **Removed `CONVERTER_PROFILE` values** `default` and `born_digital` dropped from shipped env
+  examples.
+
 ## [0.6.5]
 
 ### Added
 
-- **Contributor License Agreement.** Outside contributors accept `CLA.md` once, by commenting on a
-  pull request; the `cla` status check tracks acceptances (write access and bots are exempt).
-- **`plot-graph --format`** selects any of `svg`, `png`, `pdf` (default `svg,png`).
-- **`ontocast.config.env_names`:** environment-variable names of every settings field.
-- **More input formats:** Word, Excel, HTML, Markdown, CSV, AsciiDoc and images
-  convert through Docling alongside PDF and PowerPoint;
-  `CONVERTER_SUPPORTED_EXTENSIONS` narrows the set, and `ontocast process` warns
-  about each file it skips by suffix.
-- **`GET /ontologies`** lists the current version of each catalog ontology in the
-  request's tenant and project.
-- **Startup warnings:** `serve` and `process` name any dataset, collection or table
-  setting replaced by the tenant/project-derived name; a raised
-  `ONTOLOGY_CONTEXT_MAX_TRIPLES` that the induced-subgraph cap overrides is reported.
-- **`llm/ontology_selection`** in `budget.counters` counts the per-unit ontology
-  selection calls of `selected_single_ontology` mode.
-- **`ToolBox.ensure_vector_store`** prepares the vector store for a mode on demand.
+- **Contributor License Agreement** for outside contributors (one-time PR acceptance; `cla` check).
+- **`plot-graph --format`:** `svg`, `png`, `pdf` (default `svg,png`).
+- **`ontocast.config.env_names`:** env var for every settings field.
+- **Docling inputs:** Word, Excel, HTML, Markdown, CSV, AsciiDoc, and images; optional
+  `CONVERTER_SUPPORTED_EXTENSIONS`; skipped files warned on `process`.
+- **`GET /ontologies`:** current catalog ontology versions for the request tenant/project.
+- **Startup warnings** for tenant/project storage overrides and for
+  `ONTOLOGY_CONTEXT_MAX_TRIPLES` capped by induced-subgraph limits.
+- **`llm/ontology_selection`** budget counter in `selected_single_ontology` mode.
+- **`ToolBox.ensure_vector_store`** prepares a vector store on demand.
 
 ### Changed
 
-- **PDF conversion picks its settings per document.** `CONVERTER_PROFILE` defaults to
-  `auto`: a PDF with a text layer converts with OCR off and the fast table model
-  (`fast`); one whose pages are images only keeps OCR on (`ocr`, Docling's defaults).
-  `lean` adds equations decoded to LaTeX. New settings `CONVERTER_TABLE_MODE` and
-  `CONVERTER_DO_FORMULA_ENRICHMENT`; a profile sets only the fields not set
-  explicitly. Converter cache entries are rebuilt.
-- **`plot` extra** requires `pygraphviz>=2.0,<3`, whose wheels bundle Graphviz.
-- **`docs` extra:** `properdocs` replaces `mkdocs`; `mkdocs-jupyter` and the
-  `griffe<2` pin are dropped.
-- **`plot-graph`** no longer writes `graph.preview.png` (a remote mermaid.ink call).
-- **`strip_provenance`:** an unrecognised value returns `400` (it was read as `false`).
-- **`FUSEKI_URI` alone selects Fuseki;** `FUSEKI_AUTH` is optional. Previously the
-  URI without auth fell back to the in-memory store. A `401`/`403` while creating a
-  dataset now stops startup with `FusekiAccessError` (it was logged and ignored).
-- **`ToolBox.initialize()`** without `ontology_context_mode` prepares what
-  `ONTOLOGY_CONTEXT_MODE` asks for, including the vector index.
-- **`Config.in_memory()`** leaves the vector backend on `auto`, so enabling LanceDB
-  on the result takes effect.
-- **Graph evaluation** (`POST /match/evaluate`, `match-graphs`): a precision,
-  recall or F1 with a zero denominator is `null` (was `0.0`), and entity metrics
-  count subjects and objects that are not vocabulary (predicates were counted).
-- **Section labels from content density:** acknowledgements need two gratitude or
-  funding cues, and an excluded density label no longer spreads to the following
-  unlabelled segments. Fewer methods chunks are dropped as acknowledgements.
-- **LLM cache key** includes `json_mode` when `LLM_JSON_MODE` is on; entries
-  written with it off keep their keys.
-- **Fixed ontology mode over HTTP:** a request that names no
-  `ontology_context_fixed_ontology_id` uses `ONTOLOGY_CONTEXT_FIXED_ONTOLOGY_ID`
-  (every such request returned `400`).
-- **`plot-graph`:** the left-to-right pipeline figure uses larger labels and
-  tighter spacing, so it stays legible at page width.
+- **`CONVERTER_PROFILE`** defaults to `auto` (text PDF → fast OCR off; scan → OCR on); profiles
+  `lean`, `fast`, `ocr`; new `CONVERTER_TABLE_MODE` and `CONVERTER_DO_FORMULA_ENRICHMENT`.
+- **`plot` extra** requires `pygraphviz>=2.0,<3` (bundled Graphviz).
+- **`docs` extra:** ProperDocs replaces MkDocs.
+- **`plot-graph`** no longer writes remote preview PNG; pipeline figure layout improved.
+- **`strip_provenance`:** invalid values return `400`.
+- **Fuseki:** `FUSEKI_URI` alone selects Fuseki (`FUSEKI_AUTH` optional); dataset access errors
+  fail startup.
+- **`ToolBox.initialize()`** / **`Config.in_memory()`** honor configured ontology context and
+  vector backend (`auto` + LanceDB).
+- **Match evaluate** (`POST /match/evaluate`, `match-graphs`): zero-denominator scores are
+  `null`; entity metrics exclude vocabulary terms from subject/object counts.
+- **Section labelling:** stricter acknowledgements; excluded density labels do not spread.
+- **LLM cache key** includes `json_mode` when `LLM_JSON_MODE` is on.
+- **Fixed ontology over HTTP** uses `ONTOLOGY_CONTEXT_FIXED_ONTOLOGY_ID` when the request omits
+  an ontology id.
 
 ### Removed
 
-- **`CONVERTER_PROFILE=born_digital` and `=default`.** Both now fail validation with
-  the replacement: `fast` (or `auto`) and `ocr` (the previous default).
-- **`suthing` dropped from the `server` extra.** Nothing in the package imports
-  it; installing `ontocast[server]` no longer pulls it in.
+- **`CONVERTER_PROFILE`** values `born_digital` and `default` (use `auto`, `fast`, or `ocr`).
+- **`suthing`** from the `server` extra.
 
 ### Fixed
 
-- **Section-label matching** compiles each heading pattern and keyword once. The
-  catalog outgrows `re`'s cache, so schema detection recompiled it for every heading.
-- **`GET /info`** `input_types` lists what `/process` accepts on this install (it
-  advertised `text`, `markdown` and `jsonl`, and PDF without the `doc-processing`
-  extra; JSONL is read only by `ontocast process`).
-- **LangChain tools:** `ontocast_delete_ontology` no longer claims to delete the
-  seed file (it keeps it; the ontology reloads on the next start), and
-  `ontocast_convert_document` names the formats it converts.
-- **Vector-search context error** names both ways to enable a vector store,
-  `QDRANT_URI` or `LANCEDB_ENABLED=true`.
-- **CLI help:** `--section-schema-id` lists every schema (`patent`, `standard`,
-  `news` were missing); `--summarize-sections` says summaries are written per
-  content unit.
-- **Ontology version bumps** see class and property additions and deletions; they
-  were never detected, so no update produced a major bump.
-- **Section exclusion log** names each dropped label with its size and labelling tier.
-- **Converter availability:** without the `doc-processing` extra no converted format
-  is accepted or advertised (PDF and PPTX were, then failed on import).
-- **`plot-graph`** runs without LLM credentials or storage services.
-- **`VECTOR_STORE_BACKEND=lancedb`** without `LANCEDB_ENABLED` gets the BM25 tool
-  (it failed on first search).
-- **A vector-mode request on the startup scope** prepares the vector index instead
-  of returning `409` when the server started in another mode.
-- **LangChain `ontocast_extract`** is offered only when `docling-core` is installed.
-- **Per-tenant requests** reuse their scope's compiled graph; it was recompiled on
-  every request with `?tenant=` or `?project=`.
-- **A blank `tenant` or `project`** returns `400` on every route; outside `/flush`
-  it returned `500`.
-- **`POST /match/entities` and `match-graphs`** default `similarity_threshold` and
-  `embedding_model` to `AGG_SIMILARITY_THRESHOLD` / `AGG_EMBEDDING_MODEL` (they
-  hard-coded `0.80` and an unprefixed model name that loaded a second copy).
+- **Section labels:** compile patterns once; exclusion log includes label, size, and tier.
+- **`GET /info`** and **`/process`** accept lists match installed extras and formats.
+- **LangChain tools:** corrected delete/convert descriptions; **`ontocast_extract`** only with
+  Docling installed.
+- **Vector store:** clearer enablement errors; LanceDB backend gets BM25 without
+  `LANCEDB_ENABLED`; vector-mode requests prepare the index instead of `409`.
+- **CLI help:** all section schemas listed; **`--summarize-sections`** documents per-unit output.
+- **Ontology versioning** detects class/property additions and deletions for major bumps.
+- **`plot-graph`** runs without LLM or storage credentials.
+- **Tenancy:** blank `tenant`/`project` → `400`; scoped requests reuse the compiled graph.
+- **Match APIs** default threshold and embedding model from aggregation settings.
 
 ### Documentation
 
-- Docs are built with ProperDocs (`properdocs.yml`, `properdocs build` / `serve`)
-  and reorganized into Getting started, Concepts, Guides, Reference and Internals,
-  with a new theme and landing page.
-- The configuration reference is generated from the settings models, one entry per
-  environment variable; setting descriptions rewritten to state behaviour only.
-- Pipeline and per-unit loop diagrams redrawn in the new palette and served as SVG;
-  the loop diagrams state the real convergence rule and the facts loop's exits.
-- Docs no longer claim OntoCast reads a `.env` file (it reads the environment).
-- `demo/README.md` sample paths fixed; public callables fully annotated.
+- **ProperDocs** site with reorganized nav; configuration reference generated from settings.
+- **Pipeline diagrams** updated (SVG); docs describe environment-based config, not `.env` auto-load.
 
 ## [0.6.4] - 2026-09-16
 

README.md

@@ -67,9 +67,9 @@ without a server:
 ontocast process --input-path ./papers --output-dir ./out
 ```
 
-To keep settings in a file, copy [`.env.example.minimal`](.env.example.minimal)
-to `.env` and load it into your shell with `set -a; source .env; set +a`:
-OntoCast does not read the file itself. Step by step:
+To keep settings in a file, copy [`.env.example.minimal`](.env.example.minimal),
+edit it, and pass it with `ontocast --env-file my.env serve` (repeatable; later
+files win). Step by step:
 [Quick start](https://growgraph.github.io/ontocast/getting_started/quickstart/).
 
 ## Your own ontologies

docs/getting_started/quickstart.md

@@ -34,14 +34,16 @@ To use another provider, install its extra and set three variables:
 
 !!! tip "Keeping settings in a file"
     The repository ships `.env.example.minimal`, the settings worth a decision,
-    and `.env.example`, all of them. Copy one to `.env` and edit it. OntoCast
-    does not read the file itself, so load it into the environment of the
+    and `.env.example`, all of them. Copy one, edit it, and pass it to the
     command you run:
 
     ```bash
-    set -a; source .env; set +a
+    ontocast --env-file my.env serve
     ```
 
+    The flag is repeatable, so keys and project settings can live in separate
+    files; see [Configuring OntoCast](../guides/configuration.md#layering-settings-files).
+
 ## 3. Start the server
 
 ```bash