diff --git a/AGENTS.md b/AGENTS.md
index 09f375e..39bafe8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -48,11 +48,11 @@ restating commands, and `pages.yml` calls `site`, so the local and CI commands a
same text; `test-fast` is local-only. Arm wall times on the host that
last refreshed them are generated in
[docs/_generated/gate-measurements.md](docs/_generated/gate-measurements.md); never
-hand-edit those numbers. There is no types arm: `mypy` is configured in
-`pyproject.toml` but has never been a gate and reports 89 errors (mostly missing
-third-party stubs). See [development](docs/development.md).
+hand-edit those numbers. There is no types arm: use the version-bound
+`python scripts/check_types.py` diagnostic, which retains all configured mypy
+rules and package modules. See [development](docs/development.md) for its scope.
-`pytest` enforces the 80% coverage gate declared in `pyproject.toml`. Live-provider
+`pytest` enforces the 90.01% coverage gate declared in `pyproject.toml`. Live-provider
tests are opt-in via `uv run python -m pytest --run-real-api -m real_api` and need
credentials. A checkout whose `.venv` has not been synced cannot run the suite
offline; see [`TODO.md`](TODO.md).
@@ -88,8 +88,8 @@ conventions to follow when changing Symposium.
- Unit tests for functions, integration tests for end-to-end workflows, and
live-provider tests only behind the opt-in `real_api` marker.
-- Coverage regression gate: `--cov-fail-under=80` in `pyproject.toml`; raising
- it is tracked in `TODO.md`.
+- Coverage regression gate: `fail_under = 90.01` with `precision = 2` in
+ `pyproject.toml`; retain historical measurements without restamping them.
- Mocking is expected where it keeps tests deterministic: realistic fixtures
and edge cases instead of live calls.
- `ruff check` and `ruff format --check` are the lint and format gates; CI runs
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6986853..d2661f5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,33 @@
All notable changes to the Symposium package.
+## [Unreleased] — 2026-11-13 (offline correctness qualification)
+
+- Treat HTTP 402 as terminal before OpenRouter's retry-text classification.
+- Count presenter/profile/project completion only after all requested reports are
+ persisted; retain completed/partial files and fail incomplete or empty CLI work.
+- Consolidate configured provider creation in `APIClient.from_config`, preserving
+ explicit config selection, overrides and Perplexity background workflows.
+- Preserve ISO timestamp instants and reject invalid timestamps in the legacy
+ calendar exporter; publish through an owned temporary file and atomic replacement
+ without deleting an existing destination on failure.
+- Reject non-object JSON report/data roots and malformed provider options/keys;
+ retain the existing `Participant` record schema and private credential boundaries.
+- Reject public PDF pages without indirect identity and invalid snapshot timestamp
+ types before publication output creation.
+- Qualify the 90.01% coverage floor with precision 2 using retained coverage from
+ 902 passing offline tests (5,013/5,547 statements, 90.37%); keep the original
+ fractional-precision failure and dated generated measurements as historical evidence.
+- Replace the future branch-publication reset/amend recipe with an ordinary
+ fetched-parent commit. Disposable local proof covers staged bytes, CRLF,
+ identical-tree no-op and stale-push rejection; no hosted publication occurred.
+- Qualify all 51 package modules with version-bound local typing while preserving
+ all 64 original runtime versions; no parser pin or scientific artifact changed.
+- Add an explicitly version-bound complete-package typing command, consumed
+ plotting declarations and temporary CSR/community signature corrections.
+ Preserve installed package files, numerical versions, checked modules and
+ error rules; use WordCloud's actual array conversion at the plotting boundary.
+
## [Unreleased] — 2026-11-12 (gate and documentation)
### Participant figure legibility
diff --git a/TODO.md b/TODO.md
index 911b95e..a80be54 100644
--- a/TODO.md
+++ b/TODO.md
@@ -285,25 +285,26 @@ The three originally-deferred Majors (M1 coverage, M2 run.py orchestration, M3 l
were substantially addressed in the 2026-08-01 completion pass (see Completed/Closed below).
What remains below are the residual / aspirational follow-ups not fully closed.
-### R1 — Push coverage from 89.76% to the documented >90% target
-- **Status:** the full arm recorded 776 passed, 9 skipped and 89.76% coverage at `b43415b`
- ([gate measurements](docs/_generated/gate-measurements.md)); the regression gate in
- `pyproject.toml` is still `--cov-fail-under=80`. The per-module figures (~74%
- `cli/analyze.py` etc.) predate the coverage uplift and are not reproduced by any current
- record, so they are no longer restated here.
-- **Suggested fix:** add the remaining edge-case tests (error paths, empty inputs) to climb
- above 90%, then raise `--cov-fail-under` to match. Owner: maintainer; no external blocker,
- only unmeasured headroom.
-
-### R2 — Consolidate the `APIClient.create` wiring that now lives in the CLI
-- **Status:** the menu duplication is gone — every `run.py` operation delegates to
- `SymposiumRunner.create_api_client` / `load_config` (`run.py:44-56`). The same
- `Config(...)` + `APIClient.create(...)` construction (provider plus
- `get_api_config`/`get_api_key`) is now repeated six times:
- `src/symposium/cli/analyze.py:40,75,118,153` and `src/symposium/cli/generate.py:19,56`.
-- **Suggested fix:** one helper (on `Config`, or a small factory beside `APIClient.create`)
- that both the CLI commands and `run.py` call, so provider/key handling cannot drift between
- the two entry points. Owner: maintainer.
+### R1 — Greater-than-90% coverage target (qualified 2026-11-13)
+- **Measured:** the admitted full offline run passed 902 tests, deselected nine
+ paid-provider tests, and covered 5,013 of 5,547 statements (90.373174689%).
+ Its initial exit was 1 because the fractional 90.01 floor used zero display
+ precision. The separate source-bound reporting run reused that coverage database
+ without rerunning tests and exited 0 with precision 2 and floor 90.01.
+- **Guard:** `[tool.coverage.report]` now declares `fail_under = 90.01` and
+ `precision = 2`. The existing generated 776-test/89.76% record remains historical;
+ it was not rewritten. Later focused annotation checks are not a fresh full-suite
+ coverage measurement. This closes the measured target/guard obligation, not
+ scientific, hosted or release acceptance.
+
+### R2 — Configured-provider construction (qualified 2026-11-13)
+- **Completed:** `APIClient.from_config` serves all six CLI construction sites and
+ the interactive runner; the redundant runner factory is removed.
+- The admitted offline suite covers explicit config-file selection, environment
+ precedence, explicit key/options overrides, conflicting provider options and
+ forced Perplexity for participant background work. See
+ [the API contract](docs/api_guide.md). No paid-provider authentication or
+ availability is claimed.
---
@@ -397,20 +398,21 @@ All items below were implemented in this pass (commits `669643f`, `98ae63d`, `a6
✓ `82ea73a`
### Open / deferred
-- None from this pass. (Pre-existing R1/R2 residuals in the Major section above
- remain open; R3 is done.)
-- [ ] **Mypy is still far from clean** (re-measured 2026-11-12):
- `uv run --no-sync mypy src/symposium` reports **89 errors in 26 files**. Most are
- missing third-party stubs (`pandas-stubs`, `types-networkx`, and no `py.typed` for
- `sklearn.feature_extraction.text`), which `mypy --install-types` or dev-dependency
- additions would settle. The rest are real annotations, e.g.
- `src/symposium/core/api.py:108` (a `str | None` returned as `str`),
- `src/symposium/core/__init__.py:40` (a `str | Path` passed to a `Path` parameter)
- and `src/symposium/generation/profiles.py:157` (unannotated `results`). Add
- `mypy src/symposium` to the `lint` arm only after it passes. Owner: maintainer.
-- Heavy suites (Julia/LaTeX) do not apply — this is a Python repo; the current full
- suite result is the generated gate measurement (776 passed, 9 skipped, 89.76%,
- gate 80%), not the 188-test figure from this pass.
+- None from this documentation pass. R1/R2 now have separate 2026-11-13 offline
+ qualification records above; R3 remains done.
+- [ ] **Complete package typing remains open.** The 2026-11-12 baseline was 89
+ errors in 26 files. Subsequent source repairs and a separately authorized Python
+ 3.12 typing environment preserve all 64 existing dependency versions; the first
+ post-stub run reported 27 errors in seven files across all 51 package modules.
+ This is a diagnostic result, not a passing gate. `adjustText` and `wordcloud`
+ remain untyped, and the selected sklearn/SciPy and NetworkX stubs disagree at
+ sparse-matrix and community-partition boundaries. Do not change scientific
+ computations, fabricate stubs or suppress imports to obtain a pass.
+ Add `mypy src/symposium` to `lint` only after complete qualification with a
+ compatible reproducible dependency set. Owner: maintainer.
+- Heavy suites (Julia/LaTeX) do not apply to this Python repo. The generated
+ 776-test/89.76%/80%-gate record and the 188-test figure remain historical, not
+ current qualification. See the later source-bound R1 observation above.
---
diff --git a/docs/api_guide.md b/docs/api_guide.md
index 8771949..0548016 100644
--- a/docs/api_guide.md
+++ b/docs/api_guide.md
@@ -1,8 +1,9 @@
# Provider API and configuration
The public organizer workflow requires no LLM API. The optional research workflows
-use `APIClient.create(provider, api_key=None, **kwargs)` from
-[`core.api`](../src/symposium/core/api.py). Supported provider identifiers are
+use `APIClient.from_config(config, provider=None, api_key=None, **kwargs)` from
+[`core.api`](../src/symposium/core/api.py). `APIClient.create` remains the direct
+factory for callers supplying provider settings themselves. Supported identifiers are
`perplexity` and `openrouter`; returned providers expose
`get_response(prompt, system_prompt=None, **kwargs)`. Calling that method can incur
charges and sends its supplied content to the provider.
@@ -46,17 +47,49 @@ print(config.get("api.provider"))
```
`load_env=False` skips the dotenv file; it does not disable existing environment
-overrides. `get_api_config(provider)` and `get_api_key(provider)` supply the factory
-inputs. Never dump a complete configuration or environment into public logs.
+overrides. Construct a configured provider without duplicating that resolution:
+
+```python
+from symposium.core.api import APIClient
+from symposium.core.config import Config
+
+client = APIClient.from_config(Config(config_file="config.json"))
+```
+
+An explicit `provider` selects the provider; an explicit non-`None` `api_key` and
+keyword options override resolved settings. The factory copies provider options,
+removes their credential entry, and rejects a conflicting `provider` option rather
+than allowing it to override selection. CLI handlers and the interactive runner use
+this boundary. Participant background research explicitly selects Perplexity,
+including combined background/curriculum workflows.
+
+`get_api_config(provider)` requires an object with string keys.
+`get_api_key(provider)` accepts strings or null; malformed values raise a
+field-identifying `ValueError` without disclosing their contents. Empty/null keys
+retain the existing lookup precedence. Malformed legacy key files retain the
+warning-and-`None` behavior. Never dump complete configuration or credentials.
+
+JSON report/data readers require an object at the top level; arrays, null and scalar
+roots raise `ValueError`. Participant loaders return the existing
+`dict[str, Participant]` schema, including integer `row_index`, without copying the
+records. Read-only participant helpers accept `Mapping[str, object]`.
## Errors and limits
-Both providers map HTTP 402 to `PaymentRequiredError`. Callers must retain completed
-work and stop payment-failed processing. OpenRouter's application retry decorator
-retries errors whose text includes `rate` or `timeout`, bounded by five attempts and
-300 seconds. Its stored `max_retries` and `retry_delay` settings do not alter those
-decorator bounds. Perplexity has no equivalent application backoff wrapper; underlying
-SDK behavior is separate. There is no automatic provider failover.
+Both providers map HTTP 402 to `PaymentRequiredError`. OpenRouter treats that
+exception as terminal before inspecting retry text, including messages containing
+`rate` or `timeout`. Other matching errors retain the application retry bound of
+five attempts and 300 seconds. Stored `max_retries` and `retry_delay` do not change
+those decorator bounds. Perplexity has no equivalent application backoff wrapper;
+underlying SDK behavior is separate. There is no automatic provider failover.
+
+Presenter, profile and project batch mappings contain only records whose requested
+reports were fully persisted. Nonpayment failures are accumulated while other
+eligible records are attempted, then raise `BatchIncompleteError` with `requested`,
+`completed`, `failures` and `output_dir` evidence. Payment failure stops immediately.
+Completed and partial files remain on disk; partial records are not successes.
+Affected CLI requests fail for incomplete or empty work rather than reporting
+completion.
Token estimates and truncation are local heuristics, not proof that a provider's
context constraints are met. Returned prose and citations are unverified model
diff --git a/docs/development.md b/docs/development.md
index b98d57d..608e8db 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -43,9 +43,45 @@ benchmark. Refresh with `uv run --no-sync python scripts/gate_metrics.py refresh
re-renders the prose without measuring.
There is no types arm. `pyproject.toml` configures mypy and the dev extra ships it,
-but no gate has ever run it: `uv run --no-sync mypy src/symposium` reports 89 errors
-in 26 files, mostly missing third-party stubs (verified 2026-11-12). Adding the arm
-requires clearing those first; until then a passing type check is not claimed.
+but it has not joined a gate. The 2026-11-12 observation was 89 errors in 26 files.
+On 2026-11-13, source repairs and separately provisioned third-party stubs reduced
+the first post-stub diagnostic run to 27 errors in seven files, checking all 51
+package modules. That run still had missing `adjustText`/`wordcloud` typing and
+incompatible sparse/community declarations; it did not establish a passing check.
+That repository-specific diagnostic environment preserved all 64 existing
+dependency versions and is not a new locked development requirement.
+Add mypy to lint only after complete, reproducible qualification.
+
+`python scripts/check_types.py` checks the complete package using the existing
+mypy rules. It requires the exact diagnostic dependency versions recorded in
+`typings/bindings.json`; it never installs packages or changes runtime versions.
+Local `adjustText` and `wordcloud` declarations describe only the consumed APIs.
+The word-cloud renderer passes the real `to_array()` result to Matplotlib rather
+than pretending that WordCloud implements NumPy's dtype-taking array protocol.
+
+Upstream declaration corrections are generated in a temporary directory and
+passed through mypy's `--shadow-file`: CSR array/matrix vectorizer results,
+sparse-array consumer inputs and NetworkX mutable/frozen community sets.
+Installed package files remain unchanged.
+Both package versions and exact upstream declaration hashes must match; a mismatch
+requires new API review and qualification, not automatic rebinding. Temporary
+projections preserve the installed declarations and license text outside these
+narrow corrections. This diagnostic is not a new CI gate or scientific proof.
+
+On 2026-11-15, the complete-package command reported no issues in all 51 source
+files while preserving all 64 original runtime distribution versions. Real
+synthetic API checks exercised both sparse interfaces through LSA, NMF and LDA,
+mutable/frozen community sets, empty/nonempty label adjustment and the actual
+word-cloud renderer. Wrong-version and changed-declaration controls refused
+before projection. Earlier typing and formatting failures remain historical
+evidence; these software checks do not approve research inputs or publication.
+
+The coverage guard is `fail_under = 90.01` with `precision = 2`. The admitted
+2026-11-13 offline suite passed 902 tests with nine paid-provider tests deselected
+and measured 5,013/5,547 statements (90.37%). Its zero-precision threshold failure
+remains recorded; a separate reporting-only check reused the database and passed
+with the corrected precision. Do not rerun successful tests just to relabel that
+historical failure or hand-edit the generated gate measurements.
## Continuous integration
diff --git a/docs/organizing_publication.md b/docs/organizing_publication.md
index 8ad6682..77ffb5e 100644
--- a/docs/organizing_publication.md
+++ b/docs/organizing_publication.md
@@ -230,6 +230,11 @@ November 12, 2026 the repository's Pages source is the `gh-pages` branch at `/`
`main`, plus `.nojekyll` and a `.gitattributes` of `* -text` so the CRLF calendar and
every other file are committed byte for byte.
+Actual publication requires separate approval. Bind `PUBLISH_REMOTE` to the reviewed
+publication remote and `SOURCE_COMMIT` to the reviewed revision used for the approved
+build. The following continuation requires an existing `gh-pages` branch and a fresh
+private site directory; it is not a branch-initialization or force-push recipe.
+
```bash
SITE="$SYMPOSIUM_PRIVATE_DIR/pages-site" # must not exist yet
uv run python - "$SITE" <<'PY'
@@ -241,18 +246,40 @@ root = Path("data/public/2026")
build_site(verify_public_tree(root), Path(sys.argv[1]), assets_dir=root, artifacts_dir=root)
PY
touch "$SITE/.nojekyll"; printf '* -text\n' > "$SITE/.gitattributes"
-git -C "$SITE" init -q -b gh-pages && git -C "$SITE" add -A
-git -C "$SITE" commit -q -m "Publish the approved site built from main $(git rev-parse --short HEAD)"
-git -C "$SITE" fetch -q https://github.com/ActiveInferenceInstitute/Symposium.git gh-pages
-git -C "$SITE" reset --soft FETCH_HEAD && git -C "$SITE" commit -q --amend --no-edit
-git -C "$SITE" push https://github.com/ActiveInferenceInstitute/Symposium.git gh-pages
+(
+ set -eu
+ test ! -e "$SITE/.git"
+ git -C "$SITE" init -q -b gh-pages
+ git -C "$SITE" add -A
+ STAGED_TREE="$(git -C "$SITE" write-tree)"
+ git -C "$SITE" fetch -q "$PUBLISH_REMOTE" refs/heads/gh-pages
+ PUBLISHED="$(git -C "$SITE" rev-parse --verify 'FETCH_HEAD^{commit}')"
+ git -C "$SITE" update-ref refs/heads/gh-pages "$PUBLISHED" ""
+ test "$(git -C "$SITE" write-tree)" = "$STAGED_TREE"
+ if test "$STAGED_TREE" = "$(git -C "$SITE" rev-parse "$PUBLISHED^{tree}")"; then
+ printf '%s\n' 'Approved site unchanged; no commit or push required.'
+ else
+ git -C "$SITE" commit -q -m "Publish approved site built from main $SOURCE_COMMIT"
+ test "$(git -C "$SITE" rev-parse 'HEAD^')" = "$PUBLISHED"
+ test "$(git -C "$SITE" rev-parse 'HEAD^{tree}')" = "$STAGED_TREE"
+ git -C "$SITE" merge-base --is-ancestor "$PUBLISHED" HEAD
+ git -C "$SITE" push "$PUBLISH_REMOTE" HEAD:refs/heads/gh-pages
+ fi
+)
```
-The fetch and soft reset make the new snapshot a descendant of the published branch,
-so the push is an ordinary fast-forward. After the Pages build reports `built`, compare
-every published file with the local output byte for byte. To return to the workflow,
-set the Pages source back to GitHub Actions; the `pages.yml` deploy then replaces the
-branch-built site.
+The fresh branch is anchored at the fetched tip without changing the staged index.
+An ordinary new commit therefore has that tip as its parent and the captured staged
+tree as its tree. Identical trees require neither a commit nor a push. A concurrently
+advanced remote must reject an ordinary stale push; do not force, reset or amend
+around it.
+
+A disposable-local-remote proof on 2026-11-13 exercised changed and identical trees,
+exact parent/ancestry, committed CRLF calendar bytes, and stale-push rejection. It
+did not publish or verify a hosted site. After an authorized Pages build reports
+`built`, compare published files with the approved local output byte for byte.
+Returning Pages to GitHub Actions remains a separate owner-approved deployment
+change.
## Command-line workflow
diff --git a/pyproject.toml b/pyproject.toml
index 91cf413..6c05259 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -74,11 +74,15 @@ exclude = [
testpaths = ["tests"]
python_files = ["test_*.py"]
python_functions = ["test_*"]
-addopts = "--cov=src/symposium --cov-report=html --cov-report=term --cov-fail-under=80"
+addopts = "--cov=src/symposium --cov-report=html --cov-report=term"
markers = [
"real_api: tests that call live LLM provider APIs (opt-in via -m real_api; require API keys)",
]
+[tool.coverage.report]
+fail_under = 90.01
+precision = 2
+
[tool.ruff]
line-length = 100
target-version = "py312"
diff --git a/run.py b/run.py
index 4f0bfe9..72312fb 100755
--- a/run.py
+++ b/run.py
@@ -13,6 +13,7 @@
from pathlib import Path
from typing import Any, Dict
+from symposium.core.api import APIClient
from symposium.core.config import Config
from symposium.core.edition import Edition
@@ -45,16 +46,6 @@ def load_config(self) -> Dict[str, Any]:
"""Return the shared configuration used by the CLI and runner."""
return self.configuration.to_dict()
- def create_api_client(self, provider):
- """Apply configured credentials and model parameters consistently."""
- from symposium.core.api import APIClient
-
- options = dict(self.configuration.get_api_config(provider))
- options.pop("api_key", None)
- return APIClient.create(
- provider, api_key=self.configuration.get_api_key(provider), **options
- )
-
def display_header(self):
"""Display the main header."""
logger.info("Displaying header")
@@ -242,16 +233,18 @@ def analyze_participants(self):
if include_background:
logger.debug("Creating Perplexity API client (Sonar model) for background research")
- perplexity_client = self.create_api_client("perplexity")
+ perplexity_client = APIClient.from_config(self.configuration, provider="perplexity")
print(" 🔍 Using Perplexity Sonar for background research")
if include_analysis or include_curriculum:
logger.debug("Creating OpenRouter API client (Claude) for analysis and curricula")
- openrouter_client = self.create_api_client("openrouter")
+ openrouter_client = APIClient.from_config(self.configuration, provider="openrouter")
print(" 🤖 Using OpenRouter Claude for analysis and curricula")
# Use OpenRouter as primary client for analyzer (it does profile analysis)
primary_client = openrouter_client if openrouter_client else perplexity_client
+ if primary_client is None:
+ raise ValueError("The selected analysis requires a configured provider")
analyzer = ParticipantAnalyzer(primary_client, self.config.get("data", {}))
logger.debug("Participant analyzer created")
@@ -333,7 +326,7 @@ def generate_column_summaries(self):
try:
from symposium.analysis.participants import ParticipantAnalyzer
- client = self.create_api_client("openrouter")
+ client = APIClient.from_config(self.configuration, provider="openrouter")
analyzer = ParticipantAnalyzer(client, self.config.get("data", {}))
output_base = self.edition.output_dir / "column_summaries"
@@ -413,7 +406,7 @@ def research_single_participant(self):
# Create Perplexity API client (Sonar model for background research)
logger.info(f"Creating Perplexity API client (Sonar model) for {participant_name}")
- client = self.create_api_client("perplexity")
+ client = APIClient.from_config(self.configuration, provider="perplexity")
analyzer = ParticipantAnalyzer(client, self.config.get("data", {}))
print(" 🔍 Using Perplexity Sonar for research")
@@ -505,7 +498,7 @@ def generate_single_curriculum(self):
# Create OpenRouter API client (Claude for curriculum)
logger.info(f"Creating OpenRouter API client (Claude) for {participant_name}")
- client = self.create_api_client("openrouter")
+ client = APIClient.from_config(self.configuration, provider="openrouter")
analyzer = ParticipantAnalyzer(client, self.config.get("data", {}))
print(" 🤖 Using OpenRouter Claude for curriculum")
@@ -687,7 +680,7 @@ def test_api_connectivity(self):
for provider in providers:
try:
- client = self.create_api_client(provider)
+ client = APIClient.from_config(self.configuration, provider=provider)
response = client.get_response(
"Respond with 'test successful' if you receive this.",
"You are a helpful assistant.",
diff --git a/scripts/check_types.py b/scripts/check_types.py
new file mode 100644
index 0000000..edf9c7e
--- /dev/null
+++ b/scripts/check_types.py
@@ -0,0 +1,77 @@
+"""Check every package module with explicitly qualified third-party declarations."""
+
+from __future__ import annotations
+
+import hashlib
+import importlib.metadata as metadata
+import json
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def verify_versions(expected: dict[str, str]) -> dict[str, str]:
+ actual = {name: metadata.version(name) for name in expected}
+ mismatches = {
+ name: {"expected": version, "actual": actual[name]}
+ for name, version in expected.items()
+ if actual[name] != version
+ }
+ if mismatches:
+ raise ValueError("Unqualified typing runtime: " + json.dumps(mismatches, sort_keys=True))
+ return actual
+
+
+def project_stub(spec: dict[str, Any], destination: Path) -> tuple[str, str]:
+ source = Path(metadata.distribution(spec["distribution"]).locate_file(spec["path"]))
+ raw = source.read_bytes()
+ if hashlib.sha256(raw).hexdigest() != spec["sha256"]:
+ raise ValueError(f"Unqualified upstream declaration bytes: {source}")
+ text = raw.decode("utf-8")
+ for correction in spec["corrections"]:
+ if text.count(correction["old"]) != correction["count"]:
+ raise ValueError(f"Upstream declaration contract changed: {source}")
+ text = text.replace(correction["old"], correction["new"])
+ destination.write_text(text, encoding="utf-8")
+ return str(source), str(destination)
+
+
+def main() -> int:
+ manifest = json.loads((ROOT / "typings/bindings.json").read_text(encoding="utf-8"))
+ try:
+ versions = verify_versions(manifest["versions"])
+ with tempfile.TemporaryDirectory(prefix="symposium-types-") as directory:
+ temporary = Path(directory)
+ command = [
+ sys.executable,
+ "-B",
+ "-m",
+ "mypy",
+ "--config-file",
+ str(ROOT / "pyproject.toml"),
+ "--show-error-codes",
+ "--cache-dir",
+ str(temporary / "cache"),
+ ]
+ for index, spec in enumerate(manifest["projections"]):
+ source, shadow = project_stub(spec, temporary / f"upstream-{index}.pyi")
+ command.extend(["--shadow-file", source, shadow])
+ command.append(str(ROOT / "src"))
+ environment = os.environ.copy()
+ environment["MYPYPATH"] = str(ROOT / "typings")
+ print(
+ "Qualified typing dependencies: " + json.dumps(versions, sort_keys=True), flush=True
+ )
+ return subprocess.run(command, cwd=ROOT, env=environment, check=False).returncode
+ except (metadata.PackageNotFoundError, OSError, ValueError) as error:
+ print(f"Typing qualification refused: {error}", file=sys.stderr)
+ return 2
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/src/symposium/analysis/participants.py b/src/symposium/analysis/participants.py
index 47da742..66a5440 100644
--- a/src/symposium/analysis/participants.py
+++ b/src/symposium/analysis/participants.py
@@ -2,11 +2,13 @@
import logging
import time
+from collections.abc import Mapping
from pathlib import Path
from typing import Any, Dict, Optional
from symposium.core.api import BaseAPIProvider, PaymentRequiredError
from symposium.core.data_loader import DataLoader
+from symposium.core.participant_schema import Participant
logger = logging.getLogger(__name__)
@@ -25,7 +27,7 @@ def __init__(self, api_client: BaseAPIProvider, config: Optional[Dict[str, Any]]
self.config = config or {}
self.data_loader = DataLoader()
- def load_participant_data(self, csv_path: Path) -> Dict[str, Dict[str, Any]]:
+ def load_participant_data(self, csv_path: Path) -> dict[str, Participant]:
"""Load participant data from CSV file.
Args:
@@ -36,7 +38,7 @@ def load_participant_data(self, csv_path: Path) -> Dict[str, Dict[str, Any]]:
"""
return self.data_loader.load_participant_data(csv_path)
- def generate_background_research_prompt(self, participant_data: Dict[str, Any]) -> str:
+ def generate_background_research_prompt(self, participant_data: Mapping[str, object]) -> str:
"""Generate background research prompt for a participant.
Args:
@@ -132,7 +134,7 @@ def generate_background_research_prompt(self, participant_data: Dict[str, Any])
return prompt
- def generate_curriculum_prompt(self, participant_data: Dict[str, Any]) -> str:
+ def generate_curriculum_prompt(self, participant_data: Mapping[str, object]) -> str:
"""Generate personalized curriculum prompt for a participant.
Args:
@@ -237,7 +239,7 @@ def generate_curriculum_prompt(self, participant_data: Dict[str, Any]) -> str:
return prompt
def research_participant_background(
- self, participant_data: Dict[str, Any], system_prompt: Optional[str] = None
+ self, participant_data: Mapping[str, object], system_prompt: Optional[str] = None
) -> str:
"""Research a participant's background using internet search.
@@ -282,7 +284,7 @@ def research_participant_background(
return response
def generate_personalized_curriculum(
- self, participant_data: Dict[str, Any], system_prompt: Optional[str] = None
+ self, participant_data: Mapping[str, object], system_prompt: Optional[str] = None
) -> str:
"""Generate a personalized Active Inference curriculum.
@@ -307,7 +309,7 @@ def generate_personalized_curriculum(
return response
def analyze_participant_profile(
- self, participant_data: Dict[str, Any], system_prompt: Optional[str] = None
+ self, participant_data: Mapping[str, object], system_prompt: Optional[str] = None
) -> str:
"""Analyze a participant's profile for symposium participation.
@@ -404,7 +406,7 @@ def analyze_participant_profile(
return prompt
def analyze_participant(
- self, participant_data: Dict[str, Any], system_prompt: Optional[str] = None
+ self, participant_data: Mapping[str, object], system_prompt: Optional[str] = None
) -> str:
"""Analyze a participant's profile.
diff --git a/src/symposium/analysis/presenters.py b/src/symposium/analysis/presenters.py
index 3f7696a..bcdb539 100644
--- a/src/symposium/analysis/presenters.py
+++ b/src/symposium/analysis/presenters.py
@@ -6,7 +6,8 @@
import pandas as pd
-from symposium.core.api import BaseAPIProvider
+from symposium.core.api import BaseAPIProvider, PaymentRequiredError
+from symposium.core.batch import BatchIncompleteError
from symposium.core.data_loader import DataLoader
logger = logging.getLogger(__name__)
@@ -174,27 +175,41 @@ def analyze_all_presenters(
max_rows: Maximum rows to load per file
Returns:
- Dictionary mapping presenter names to analysis text
+ Fully persisted analyses. An incomplete batch raises BatchIncompleteError;
+ payment errors stop immediately. Existing and partial files are retained.
"""
from symposium.io.writers import ReportWriter
presenters = self.load_presenter_data(data_path, max_rows)
- results = {}
+ results: Dict[str, str] = {}
+ failures: Dict[str, str] = {}
for presenter_name, presenter_data in presenters.items():
try:
logger.info(f"Analyzing presenter: {presenter_name}")
analysis = self.analyze_presenter(presenter_data, domain_context)
- results[presenter_name] = analysis
# Save report
ReportWriter.save_presenter_report(
presenter_name, analysis, output_dir, "research_profile"
)
+ results[presenter_name] = analysis
+ except PaymentRequiredError:
+ logger.error(
+ "Payment stopped batch: %d/%d fully persisted; partial files retained in %s",
+ len(results),
+ len(presenters),
+ output_dir,
+ )
+ raise
except Exception as e:
logger.error(f"Error analyzing presenter {presenter_name}: {e}")
+ failures[presenter_name] = str(e)
continue
+ if failures:
+ raise BatchIncompleteError(len(presenters), results, failures, output_dir)
+
logger.info(f"Completed analysis for {len(results)} presenters")
return results
diff --git a/src/symposium/calendar/README.md b/src/symposium/calendar/README.md
index 0c9cb5c..24d2208 100644
--- a/src/symposium/calendar/README.md
+++ b/src/symposium/calendar/README.md
@@ -29,6 +29,20 @@ exporter.export_symposium_schedule(
)
```
+### Timestamp and publication guarantees
+
+`ScheduleExporter` accepts ISO datetime strings and `datetime` objects. `Z` and
+explicit offsets preserve their instant; naive values use the configured timezone.
+Invalid supplied timestamps raise `ValueError` instead of becoming the current time.
+
+Calendar serialization completes before publication. The exporter writes, flushes,
+syncs and closes its own same-directory temporary file before atomic replacement.
+A failed publication preserves an existing destination and cleans only that
+operation's temporary file.
+
+This legacy exporter is separate from approved-public calendar generation. These
+guarantees do not regenerate or requalify released calendars or books.
+
## Export Formats
### ICS (iCalendar)
diff --git a/src/symposium/calendar/exporter.py b/src/symposium/calendar/exporter.py
index 3213a63..2182cc2 100644
--- a/src/symposium/calendar/exporter.py
+++ b/src/symposium/calendar/exporter.py
@@ -1,9 +1,11 @@
"""Calendar export functionality for symposium schedules."""
import logging
+import os
import uuid
from datetime import datetime, timedelta
from pathlib import Path
+from tempfile import NamedTemporaryFile
from typing import Any, Dict, List, Optional
import pytz
@@ -65,7 +67,8 @@ def _structure_event(self, event: Dict[str, Any]) -> Optional[Dict[str, Any]]:
event: Raw event data
Returns:
- Structured event dictionary or None if invalid
+ Structured event dictionary or None for missing required fields.
+ Invalid timestamps raise ValueError instead of publishing invented times.
"""
try:
# Required fields validation
@@ -77,21 +80,13 @@ def _structure_event(self, event: Dict[str, Any]) -> Optional[Dict[str, Any]]:
logger.warning(f"Event missing start_time: {event}")
return None
- # Check if already structured (datetime objects)
- start_time = event["start_time"]
- if hasattr(start_time, "strftime"): # Already a datetime object
- start_dt = start_time
- else: # Need to parse string
- start_dt = self._parse_datetime(str(start_time))
-
+ start_dt = self._parse_datetime(event["start_time"])
end_time = event.get("end_time")
- if hasattr(end_time, "strftime"): # Already a datetime object
- end_dt = end_time
- else: # Need to parse string or calculate from duration
- if end_time:
- end_dt = self._parse_datetime(str(end_time))
- else:
- end_dt = start_dt + timedelta(hours=event.get("duration_hours", 1))
+ end_dt = (
+ self._parse_datetime(end_time)
+ if end_time
+ else start_dt + timedelta(hours=event.get("duration_hours", 1))
+ )
# Structure the event
structured = {
@@ -110,38 +105,21 @@ def _structure_event(self, event: Dict[str, Any]) -> Optional[Dict[str, Any]]:
return structured
+ except ValueError:
+ raise
except Exception as e:
logger.error(f"Error structuring event {event.get('title', 'Unknown')}: {e}")
return None
- def _parse_datetime(self, time_str: str) -> datetime:
- """Parse datetime string into timezone-aware datetime.
-
- Args:
- time_str: Time string in various formats
-
- Returns:
- Timezone-aware datetime object
- """
- # Try different datetime formats
- formats = [
- "%Y-%m-%d %H:%M:%S",
- "%Y-%m-%dT%H:%M:%S",
- "%Y-%m-%d %H:%M",
- "%Y-%m-%dT%H:%M",
- "%Y-%m-%d",
- ]
-
- for fmt in formats:
- try:
- dt = datetime.strptime(time_str, fmt)
- return self.timezone.localize(dt)
- except ValueError:
- continue
-
- # If no format matches, assume current time + offset
- logger.warning(f"Could not parse datetime: {time_str}")
- return datetime.now(self.timezone)
+ def _parse_datetime(self, time_str: str | datetime) -> datetime:
+ """Preserve ISO instants; interpret naive values in the configured timezone."""
+ try:
+ dt = time_str if isinstance(time_str, datetime) else datetime.fromisoformat(time_str)
+ except (TypeError, ValueError) as exc:
+ raise ValueError(f"Invalid event datetime: {time_str!r}") from exc
+ if dt.tzinfo is None:
+ return self.timezone.localize(dt)
+ return dt.astimezone(self.timezone)
def create_ics_calendar(
self,
@@ -241,29 +219,44 @@ def export_ics_file(
Returns:
Success status
"""
+ temporary_path: Path | None = None
try:
# Create calendar
cal = self.create_ics_calendar(events, calendar_name, description)
- # Ensure output directory exists
- output_path.parent.mkdir(parents=True, exist_ok=True)
-
# Convert to ICS format (this is where errors might occur)
ics_content = cal.to_ical()
- # Write to file
- with open(output_path, "wb") as f:
- f.write(ics_content)
+ output_path.parent.mkdir(parents=True, exist_ok=True)
+ with NamedTemporaryFile(
+ mode="wb",
+ dir=output_path.parent,
+ prefix=f".{output_path.name}.",
+ suffix=".tmp",
+ delete=False,
+ ) as temporary:
+ temporary_path = Path(temporary.name)
+ if temporary.write(ics_content) != len(ics_content):
+ raise OSError("Incomplete calendar write")
+ temporary.flush()
+ os.fsync(temporary.fileno())
+ os.replace(temporary_path, output_path)
+ temporary_path = None
logger.info(f"ICS calendar exported to {output_path}")
return True
except Exception as e:
logger.error(f"Error exporting ICS file: {e}")
- # Clean up partial file if it exists
- if output_path.exists():
- output_path.unlink()
return False
+ finally:
+ if temporary_path is not None:
+ try:
+ temporary_path.unlink(missing_ok=True)
+ except OSError as exc:
+ logger.warning(
+ "Could not remove calendar temporary file %s: %s", temporary_path, exc
+ )
def export_symposium_schedule(
self,
@@ -366,7 +359,7 @@ def validate_schedule(self, events: List[Dict[str, Any]]) -> Dict[str, Any]:
Returns:
Validation report dictionary
"""
- report = {
+ report: Dict[str, Any] = {
"total_events": len(events),
"valid_events": 0,
"warnings": [],
@@ -374,7 +367,7 @@ def validate_schedule(self, events: List[Dict[str, Any]]) -> Dict[str, Any]:
"conflicts": [],
}
- event_times = []
+ event_times: list[tuple[datetime, datetime]] = []
for event in events:
# Check required fields
@@ -387,7 +380,11 @@ def validate_schedule(self, events: List[Dict[str, Any]]) -> Dict[str, Any]:
continue
# Structure event to get datetime objects
- structured_event = self._structure_event(event)
+ try:
+ structured_event = self._structure_event(event)
+ except ValueError as exc:
+ report["errors"].append(f"Invalid event time for {event['title']}: {exc}")
+ continue
if not structured_event:
report["errors"].append(f"Event could not be structured: {event['title']}")
continue
diff --git a/src/symposium/cli/analyze.py b/src/symposium/cli/analyze.py
index b5973c5..9fd08c6 100644
--- a/src/symposium/cli/analyze.py
+++ b/src/symposium/cli/analyze.py
@@ -38,13 +38,7 @@ def analyze_presenters(args):
try:
# Setup configuration and API
config = Config(config_file=Path(args.config) if getattr(args, "config", None) else None)
- api_client = APIClient.create(
- provider=args.api_provider or config.get("api.provider"),
- **{
- **config.get_api_config(args.api_provider),
- "api_key": config.get_api_key(args.api_provider),
- },
- )
+ api_client = APIClient.from_config(config, provider=args.api_provider)
# Load domain context if provided
domain_context = None
@@ -56,6 +50,8 @@ def analyze_presenters(args):
results = analyzer.analyze_all_presenters(
Path(args.data_dir), Path(args.output_dir), domain_context, max_rows=args.max_rows
)
+ if not results:
+ raise ValueError("No eligible presenters; no reports were generated")
logger.info(f"✅ Successfully analyzed {len(results)} presenters")
logger.info(f"📁 Reports saved to {args.output_dir}")
@@ -73,12 +69,11 @@ def analyze_participants(args):
expected = _participant_count(args.csv_file)
# Setup configuration and API
config = Config(config_file=Path(args.config) if getattr(args, "config", None) else None)
- api_client = APIClient.create(
- provider=args.api_provider or config.get("api.provider"),
- **{
- **config.get_api_config(args.api_provider),
- "api_key": config.get_api_key(args.api_provider),
- },
+ api_client = APIClient.from_config(config, provider=args.api_provider)
+ background_client = (
+ APIClient.from_config(config, provider="perplexity")
+ if args.include_background_research
+ else None
)
# Analyze participants
@@ -88,6 +83,7 @@ def analyze_participants(args):
Path(args.output_dir),
include_background_research=args.include_background_research,
include_curriculum=args.include_curriculum,
+ perplexity_client=background_client,
)
_require_complete(results, expected)
@@ -116,10 +112,7 @@ def analyze_participant_backgrounds(args):
expected = _participant_count(args.csv_file)
# Setup configuration and API
config = Config(config_file=Path(args.config) if getattr(args, "config", None) else None)
- api_client = APIClient.create(
- provider="perplexity", # Force Perplexity for background research
- **{**config.get_api_config("perplexity"), "api_key": config.get_api_key("perplexity")},
- )
+ api_client = APIClient.from_config(config, provider="perplexity")
# Analyze participants with background research only
analyzer = ParticipantAnalyzer(api_client, config.to_dict().get("data", {}))
@@ -151,13 +144,7 @@ def generate_participant_curricula(args):
expected = _participant_count(args.csv_file)
# Setup configuration and API
config = Config(config_file=Path(args.config) if getattr(args, "config", None) else None)
- api_client = APIClient.create(
- provider=args.api_provider or config.get("api.provider"),
- **{
- **config.get_api_config(args.api_provider),
- "api_key": config.get_api_key(args.api_provider),
- },
- )
+ api_client = APIClient.from_config(config, provider=args.api_provider)
# Analyze participants with curricula only
analyzer = ParticipantAnalyzer(api_client, config.to_dict().get("data", {}))
diff --git a/src/symposium/cli/generate.py b/src/symposium/cli/generate.py
index e87aa43..4649d04 100644
--- a/src/symposium/cli/generate.py
+++ b/src/symposium/cli/generate.py
@@ -17,13 +17,7 @@ def generate_profiles(args):
try:
# Setup configuration and API
config = Config(config_file=Path(args.config) if getattr(args, "config", None) else None)
- api_client = APIClient.create(
- provider=args.api_provider or config.get("api.provider"),
- **{
- **config.get_api_config(args.api_provider),
- "api_key": config.get_api_key(args.api_provider),
- },
- )
+ api_client = APIClient.from_config(config, provider=args.api_provider)
# Load domain context if provided
domain_context = None
@@ -38,6 +32,8 @@ def generate_profiles(args):
domain_context,
include_methods=args.include_methods,
)
+ if not results:
+ raise ValueError("No eligible researchers; no profiles were generated")
logger.info(f"✅ Successfully generated profiles for {len(results)} researchers")
logger.info(f"📁 Profiles saved to {args.output_dir}")
@@ -54,13 +50,7 @@ def generate_projects(args):
try:
# Setup configuration and API
config = Config(config_file=Path(args.config) if getattr(args, "config", None) else None)
- api_client = APIClient.create(
- provider=args.api_provider or config.get("api.provider"),
- **{
- **config.get_api_config(args.api_provider),
- "api_key": config.get_api_key(args.api_provider),
- },
- )
+ api_client = APIClient.from_config(config, provider=args.api_provider)
# Generate projects
generator = ProjectGenerator(api_client, config.to_dict().get("data", {}))
@@ -76,6 +66,8 @@ def generate_projects(args):
catechisms_dir=catechisms_dir,
collaborators_file=collaborators_file,
)
+ if not results:
+ raise ValueError("No eligible participant profiles; no proposals were generated")
logger.info(f"✅ Successfully generated proposals for {len(results)} participants")
logger.info(f"📁 Proposals saved to {args.output_dir}")
diff --git a/src/symposium/core/__init__.py b/src/symposium/core/__init__.py
index d345978..d1e4c0a 100644
--- a/src/symposium/core/__init__.py
+++ b/src/symposium/core/__init__.py
@@ -1,7 +1,6 @@
"""Core functionality for the symposium package."""
from pathlib import Path
-from typing import Any, Dict
from symposium.core.api import (
APIClient,
@@ -13,6 +12,7 @@
from symposium.core.config import Config
from symposium.core.data_loader import DataLoader
from symposium.core.logging_utils import setup_logging
+from symposium.core.participant_schema import Participant
__all__ = [
"APIClient",
@@ -28,7 +28,7 @@
# Convenience function for loading participant data
-def load_participant_data(csv_path: str | Path) -> Dict[str, Dict[str, Any]]:
+def load_participant_data(csv_path: str | Path) -> dict[str, Participant]:
"""Load participant data from Public_Participant_Information.csv format.
Args:
@@ -37,4 +37,4 @@ def load_participant_data(csv_path: str | Path) -> Dict[str, Dict[str, Any]]:
Returns:
Dictionary mapping participant names to their complete data
"""
- return DataLoader.load_participant_data(csv_path)
+ return DataLoader.load_participant_data(Path(csv_path))
diff --git a/src/symposium/core/api.py b/src/symposium/core/api.py
index 8f3afd8..5555eb5 100644
--- a/src/symposium/core/api.py
+++ b/src/symposium/core/api.py
@@ -3,10 +3,13 @@
import logging
import os
from abc import ABC, abstractmethod
-from typing import Optional
+from typing import Any, Optional
import backoff
from openai import APIStatusError, OpenAI
+from openai.types.chat import ChatCompletionMessageParam
+
+from symposium.core.config import Config
logger = logging.getLogger(__name__)
@@ -90,7 +93,7 @@ def get_response(self, prompt: str, system_prompt: Optional[str] = None, **kwarg
Exception: For other API errors
"""
try:
- messages = []
+ messages: list[ChatCompletionMessageParam] = []
if system_prompt:
messages.append({"role": "system", "content": system_prompt})
messages.append({"role": "user", "content": prompt})
@@ -105,7 +108,10 @@ def get_response(self, prompt: str, system_prompt: Optional[str] = None, **kwarg
if not response or not response.choices:
raise ValueError("Empty response from Perplexity API")
- return response.choices[0].message.content
+ content = response.choices[0].message.content
+ if not content:
+ raise ValueError("Empty response from Perplexity API")
+ return content
except APIStatusError as exc:
if exc.status_code == 402:
@@ -140,10 +146,8 @@ def __init__(self, api_key: str, **kwargs):
max_tries=5,
max_time=300,
giveup=lambda e: (
- not (
- isinstance(e, Exception)
- and ("rate" in str(e).lower() or "timeout" in str(e).lower())
- )
+ isinstance(e, PaymentRequiredError)
+ or not ("rate" in str(e).lower() or "timeout" in str(e).lower())
),
)
def _get_response_with_retry(
@@ -223,6 +227,32 @@ def get_response(self, prompt: str, system_prompt: Optional[str] = None, **kwarg
class APIClient:
"""Factory class for creating API provider instances."""
+ @staticmethod
+ def from_config(
+ config: Config,
+ provider: str | None = None,
+ *,
+ api_key: str | None = None,
+ **overrides: Any,
+ ) -> BaseAPIProvider:
+ """Construct one explicitly selected provider from resolved configuration.
+
+ Config owns file/environment precedence. An explicit provider or key
+ overrides that selection. Credentials are removed from copied options,
+ so they cannot collide with the factory's explicit api_key argument.
+ """
+ selected = provider if provider is not None else config.get("api.provider")
+ if not isinstance(selected, str) or selected.lower() not in ("perplexity", "openrouter"):
+ raise ValueError("Unsupported provider; choose 'perplexity' or 'openrouter'")
+ selected = selected.lower()
+ options = dict(config.get_api_config(selected))
+ options.pop("api_key", None)
+ options.update(overrides)
+ if "provider" in options:
+ raise ValueError("Provider options must not override provider selection")
+ key = api_key if api_key is not None else config.get_api_key(selected)
+ return APIClient.create(provider=selected, api_key=key, **options)
+
@staticmethod
def create(provider: str, api_key: Optional[str] = None, **kwargs) -> BaseAPIProvider:
"""Create an API provider instance.
@@ -247,10 +277,8 @@ def create(provider: str, api_key: Optional[str] = None, **kwargs) -> BaseAPIPro
elif provider == "openrouter":
api_key = os.getenv("OPENROUTER_API_KEY")
- if api_key is None:
- raise ValueError(
- f"API key for {provider} not provided and not found in environment"
- )
+ if not api_key:
+ raise ValueError(f"API key for {provider} not provided and not found in environment")
if provider == "perplexity":
return PerplexityProvider(api_key, **kwargs)
diff --git a/src/symposium/core/batch.py b/src/symposium/core/batch.py
new file mode 100644
index 0000000..98598d1
--- /dev/null
+++ b/src/symposium/core/batch.py
@@ -0,0 +1,25 @@
+"""Failure evidence for batches that retain completed and partial output files."""
+
+from collections.abc import Mapping
+from pathlib import Path
+
+
+class BatchIncompleteError(RuntimeError):
+ """A batch finished its attempts but not all requested outputs persisted."""
+
+ def __init__(
+ self,
+ requested: int,
+ completed: Mapping[str, object],
+ failures: Mapping[str, str],
+ output_dir: Path,
+ ) -> None:
+ self.requested = requested
+ self.completed = dict(completed)
+ self.failures = dict(failures)
+ self.output_dir = output_dir
+ super().__init__(
+ f"Batch incomplete: {len(completed)}/{requested} fully persisted; "
+ f"failed: {', '.join(failures)}. Completed and partial files were preserved "
+ f"under {output_dir}"
+ )
diff --git a/src/symposium/core/config.py b/src/symposium/core/config.py
index 2cf9c0a..6171cc6 100644
--- a/src/symposium/core/config.py
+++ b/src/symposium/core/config.py
@@ -193,11 +193,19 @@ def get_api_config(self, provider: Optional[str] = None) -> Dict[str, Any]:
Returns:
API configuration dictionary
+
+ Raises:
+ ValueError: If the provider settings are not an object with string keys.
"""
if provider is None:
provider = self.get("api.provider")
- return self.get(f"api.{provider}", {})
+ api_config: object = self.get(f"api.{provider}", {})
+ if not isinstance(api_config, dict) or any(not isinstance(key, str) for key in api_config):
+ raise ValueError(
+ f"Configuration field 'api.{provider}' must be an object with string keys"
+ )
+ return api_config
def get_api_key(self, provider: Optional[str] = None) -> Optional[str]:
"""Get API key for a provider.
@@ -207,12 +215,19 @@ def get_api_key(self, provider: Optional[str] = None) -> Optional[str]:
Returns:
API key or None if not found
+
+ Raises:
+ ValueError: If a configured API key is neither a string nor None.
"""
if provider is None:
provider = self.get("api.provider")
# Try config first, then environment, then legacy key file
- api_key = self.get(f"api.{provider}.api_key")
+ api_key: object = self.get(f"api.{provider}.api_key")
+ if api_key is not None and not isinstance(api_key, str):
+ raise ValueError(
+ f"Configuration field 'api.{provider}.api_key' must be a string or null"
+ )
if api_key:
return api_key
@@ -233,14 +248,19 @@ def _load_legacy_api_key(self, provider: str) -> Optional[str]:
provider: Provider name
Returns:
- API key or None if not found
+ API key or None if missing or invalid; loading failures are logged.
"""
key_file = Path("llm_keys.key")
if key_file.exists():
try:
with open(key_file, "r") as f:
- keys = json.load(f)
- return keys.get(provider)
+ keys: object = json.load(f)
+ if not isinstance(keys, dict):
+ raise ValueError("Legacy key file must be a JSON object")
+ api_key: object = keys.get(provider)
+ if api_key is not None and not isinstance(api_key, str):
+ raise ValueError(f"Legacy API key field '{provider}' must be a string or null")
+ return api_key
except Exception as e:
logger.warning(f"Could not load legacy key file: {e}")
return None
diff --git a/src/symposium/core/data_loader.py b/src/symposium/core/data_loader.py
index cb3aa45..e701086 100644
--- a/src/symposium/core/data_loader.py
+++ b/src/symposium/core/data_loader.py
@@ -2,11 +2,14 @@
import json
import logging
+from collections.abc import Mapping
from pathlib import Path
from typing import Any, Dict, Optional
import pandas as pd
+from symposium.core.participant_schema import Participant
+
logger = logging.getLogger(__name__)
@@ -32,7 +35,7 @@ def load_csv(filepath: Path, **kwargs) -> pd.DataFrame:
if not filepath.exists():
raise FileNotFoundError(f"CSV file not found: {filepath}")
- df = pd.read_csv(filepath, **kwargs)
+ df: pd.DataFrame = pd.read_csv(filepath, **kwargs)
logger.debug(f"Loaded CSV file: {filepath} ({len(df)} rows)")
return df
@@ -52,6 +55,7 @@ def load_json(filepath: Path) -> Dict[str, Any]:
Raises:
FileNotFoundError: If file doesn't exist
+ ValueError: If the JSON root is not an object
Exception: For other loading errors
"""
try:
@@ -59,7 +63,9 @@ def load_json(filepath: Path) -> Dict[str, Any]:
raise FileNotFoundError(f"JSON file not found: {filepath}")
with open(filepath, "r", encoding="utf-8") as f:
- data = json.load(f)
+ data: object = json.load(f)
+ if not isinstance(data, dict):
+ raise ValueError(f"JSON data in {filepath} must be a JSON object")
logger.debug(f"Loaded JSON file: {filepath}")
return data
@@ -115,7 +121,7 @@ def load_presenter_data(
Returns:
Dictionary mapping presenter names to their data
"""
- presenters = {}
+ presenters: dict[str, dict[str, str | Path | pd.DataFrame]] = {}
# Convert string to Path if needed
if isinstance(base_path, str):
@@ -192,7 +198,7 @@ def load_participant_profiles(base_path: Path) -> Dict[str, Dict[str, Any]]:
Returns:
Dictionary mapping participant names to their profiles
"""
- participants = {}
+ participants: dict[str, dict[str, object]] = {}
# Convert string to Path if needed
if isinstance(base_path, str):
@@ -286,7 +292,7 @@ def truncate_to_tokens(text: str, max_tokens: int) -> str:
return " ".join(words[:words_needed])
@staticmethod
- def load_participant_data(csv_path: Path) -> Dict[str, Dict[str, Any]]:
+ def load_participant_data(csv_path: Path) -> dict[str, Participant]:
"""Load consenting participants after validating schema and output names."""
from symposium.core.participant_schema import load_participants
@@ -294,7 +300,7 @@ def load_participant_data(csv_path: Path) -> Dict[str, Dict[str, Any]]:
@staticmethod
def get_column_summary(
- participant_data: Dict[str, Dict[str, Any]], column: str
+ participant_data: Mapping[str, Mapping[str, object]], column: str
) -> Dict[str, Any]:
"""Get summary statistics for a specific column across all participants.
@@ -339,7 +345,7 @@ def get_column_summary(
}
@staticmethod
- def format_participant_for_api(participant_data: Dict[str, Any]) -> str:
+ def format_participant_for_api(participant_data: Mapping[str, object]) -> str:
"""Format participant data for API consumption.
Args:
diff --git a/src/symposium/generation/profiles.py b/src/symposium/generation/profiles.py
index c5e0d30..59c8ca1 100644
--- a/src/symposium/generation/profiles.py
+++ b/src/symposium/generation/profiles.py
@@ -4,7 +4,8 @@
from pathlib import Path
from typing import Any, Dict, Optional
-from symposium.core.api import BaseAPIProvider
+from symposium.core.api import BaseAPIProvider, PaymentRequiredError
+from symposium.core.batch import BatchIncompleteError
from symposium.core.data_loader import DataLoader
logger = logging.getLogger(__name__)
@@ -143,7 +144,8 @@ def generate_all_profiles(
include_methods: Whether to generate methods documentation
Returns:
- Dictionary mapping researcher names to their profiles
+ Fully persisted profiles. An incomplete batch raises BatchIncompleteError;
+ payment errors stop immediately. Existing and partial files are retained.
"""
from symposium.analysis.presenters import PresenterAnalyzer
from symposium.io.writers import ReportWriter
@@ -154,33 +156,47 @@ def generate_all_profiles(
data_path, max_rows=self.config.get("max_rows_per_file", 10)
)
- results = {}
+ results: Dict[str, Dict[str, str]] = {}
+ failures: Dict[str, str] = {}
for researcher_name, researcher_data in presenters.items():
try:
logger.info(f"Generating profile for: {researcher_name}")
- results[researcher_name] = {}
# Generate research profile
profile = analyzer.analyze_presenter(researcher_data, domain_context)
- results[researcher_name]["profile"] = profile
ReportWriter.save_presenter_report(
researcher_name, profile, output_dir, "research_profile"
)
+ researcher_results = {"profile": profile}
# Generate methods documentation if requested
if include_methods:
methods = self.generate_research_methods(researcher_data, domain_context)
- results[researcher_name]["methods"] = methods
ReportWriter.save_presenter_report(
researcher_name, methods, output_dir, "research_methods"
)
+ researcher_results["methods"] = methods
+ results[researcher_name] = researcher_results
+
+ except PaymentRequiredError:
+ logger.error(
+ "Payment stopped batch: %d/%d fully persisted; partial files retained in %s",
+ len(results),
+ len(presenters),
+ output_dir,
+ )
+ raise
except Exception as e:
logger.error(f"Error generating profile for {researcher_name}: {e}")
+ failures[researcher_name] = str(e)
continue
+ if failures:
+ raise BatchIncompleteError(len(presenters), results, failures, output_dir)
+
logger.info(f"Completed profile generation for {len(results)} researchers")
return results
diff --git a/src/symposium/generation/projects.py b/src/symposium/generation/projects.py
index e1c25d2..f47856c 100644
--- a/src/symposium/generation/projects.py
+++ b/src/symposium/generation/projects.py
@@ -4,7 +4,8 @@
from pathlib import Path
from typing import Any, Dict, Optional
-from symposium.core.api import BaseAPIProvider
+from symposium.core.api import BaseAPIProvider, PaymentRequiredError
+from symposium.core.batch import BatchIncompleteError
from symposium.core.data_loader import DataLoader
from symposium.io.readers import ReportReader
@@ -188,7 +189,8 @@ def generate_all_projects(
collaborators_file: Optional file with collaborators list
Returns:
- Dictionary mapping participant names to proposals
+ Fully persisted proposals. An incomplete batch raises BatchIncompleteError;
+ payment errors stop immediately. Existing and partial files are retained.
"""
from symposium.io.writers import ReportWriter
@@ -202,7 +204,8 @@ def generate_all_projects(
# Load participant profiles
participants = self.data_loader.load_participant_profiles(profiles_dir)
- results = {}
+ results: Dict[str, str] = {}
+ failures: Dict[str, str] = {}
for participant_name, participant_data in participants.items():
try:
@@ -217,16 +220,27 @@ def generate_all_projects(
collaborators,
)
- results[participant_name] = proposal
-
# Save proposal
ReportWriter.save_project_proposal(
participant_name, proposal, output_dir, catechism_type
)
+ results[participant_name] = proposal
+ except PaymentRequiredError:
+ logger.error(
+ "Payment stopped batch: %d/%d fully persisted; partial files retained in %s",
+ len(results),
+ len(participants),
+ output_dir,
+ )
+ raise
except Exception as e:
logger.error(f"Error generating proposal for {participant_name}: {e}")
+ failures[participant_name] = str(e)
continue
+ if failures:
+ raise BatchIncompleteError(len(participants), results, failures, output_dir)
+
logger.info(f"Completed project generation for {len(results)} participants")
return results
diff --git a/src/symposium/io/readers.py b/src/symposium/io/readers.py
index 2b087d8..9eb3ee3 100644
--- a/src/symposium/io/readers.py
+++ b/src/symposium/io/readers.py
@@ -40,11 +40,16 @@ def read_json(filepath: Path) -> Dict[str, Any]:
filepath: Path to JSON file
Returns:
- Parsed JSON data
+ Dictionary with JSON data
+
+ Raises:
+ ValueError: If the JSON root is not an object
"""
try:
with open(filepath, "r", encoding="utf-8") as f:
- data = json.load(f)
+ data: object = json.load(f)
+ if not isinstance(data, dict):
+ raise ValueError(f"JSON data in {filepath} must be a JSON object")
logger.debug(f"Read JSON file: {filepath}")
return data
except Exception as e:
@@ -63,7 +68,7 @@ def read_csv(filepath: Path, **kwargs) -> pd.DataFrame:
DataFrame with CSV data
"""
try:
- df = pd.read_csv(filepath, **kwargs)
+ df: pd.DataFrame = pd.read_csv(filepath, **kwargs)
logger.debug(f"Read CSV file: {filepath} ({len(df)} rows)")
return df
except Exception as e:
diff --git a/src/symposium/io/writers.py b/src/symposium/io/writers.py
index b4c1b26..7416d35 100644
--- a/src/symposium/io/writers.py
+++ b/src/symposium/io/writers.py
@@ -79,7 +79,7 @@ def save_json_report(content: str, filepath: Path, metadata: Optional[Dict[str,
filepath = Path(filepath)
filepath.parent.mkdir(parents=True, exist_ok=True)
- data = {"timestamp": datetime.now().isoformat(), "content": content}
+ data: dict[str, object] = {"timestamp": datetime.now().isoformat(), "content": content}
if metadata:
data["metadata"] = metadata
diff --git a/src/symposium/organizing/book_cover_facts.py b/src/symposium/organizing/book_cover_facts.py
index afba8d4..e59ad78 100644
--- a/src/symposium/organizing/book_cover_facts.py
+++ b/src/symposium/organizing/book_cover_facts.py
@@ -70,7 +70,11 @@ def parse_cover_doi(value: str | None) -> str | None:
def cover_metadata_rows(value: CoverMetadata) -> tuple[tuple[str, int], ...]:
"""Keep the same visible metadata order and Word half-point sizes in every cover."""
- rows = ((value.event_dates, 20), (value.website_url, 18), (value.contact_email, 18))
+ rows: tuple[tuple[str, int], ...] = (
+ (value.event_dates, 20),
+ (value.website_url, 18),
+ (value.contact_email, 18),
+ )
if value.doi:
rows += (("DOI: " + value.doi, 18),)
return tuple(row for row in rows if row[0])
diff --git a/src/symposium/organizing/book_design_docx.py b/src/symposium/organizing/book_design_docx.py
index 0c3ee2e..5bb16f3 100644
--- a/src/symposium/organizing/book_design_docx.py
+++ b/src/symposium/organizing/book_design_docx.py
@@ -3,6 +3,7 @@
from __future__ import annotations
import copy
+import io
import zipfile
from collections.abc import Sequence
from pathlib import Path
@@ -27,7 +28,9 @@ def _package_xml(element: ET.Element, namespace: str) -> bytes:
raise BookDesignError("Native DOCX package vocabulary has an unexpected namespace")
node.tag = node.tag[len(namespace) :]
root.set("xmlns", namespace[1:-1])
- return ET.tostring(root, encoding="utf-8", xml_declaration=True)
+ output = io.BytesIO()
+ ET.ElementTree(root).write(output, encoding="utf-8", xml_declaration=True)
+ return output.getvalue()
def _paragraph(
diff --git a/src/symposium/organizing/bridge.py b/src/symposium/organizing/bridge.py
index d5f9963..41e5e24 100644
--- a/src/symposium/organizing/bridge.py
+++ b/src/symposium/organizing/bridge.py
@@ -168,7 +168,10 @@ def validate_mapping(config: object) -> dict[str, Any]:
or len(set(mapping.values())) != len(fields)
):
raise PublicationError("Source field mapping must be complete, unique, and allowlisted")
- return json.loads(canonical_bytes(config))
+ detached = json.loads(canonical_bytes(config))
+ if not isinstance(detached, dict):
+ raise PublicationError("Invalid bridge mapping schema")
+ return detached
def pull_snapshot(
diff --git a/src/symposium/organizing/discovery.py b/src/symposium/organizing/discovery.py
index 74c52e5..1c0dba5 100644
--- a/src/symposium/organizing/discovery.py
+++ b/src/symposium/organizing/discovery.py
@@ -96,7 +96,7 @@ def _methods(catalog: Catalog, base: str) -> str:
commands = "".join(
f"
uv run {_escape(command)}" for command in workflow["commands"]
)
- repositories = "".join(
+ repository_links = "".join(
f'{_escape(key)}'
for key in workflow["repository_ids"]
)
@@ -104,7 +104,7 @@ def _methods(catalog: Catalog, base: str) -> str:
", ".join(credential_labels[key] for key in workflow["credential_ids"]) or "None"
)
workflows.append(
- f'''{_escape(workflow["title"])}
{_escape(workflow["summary"])}
Credential requirements: {_escape(credentials)}
'''
+ f'''{_escape(workflow["title"])}
{_escape(workflow["summary"])}
Credential requirements: {_escape(credentials)}
'''
)
repositories = []
for repository in catalog["repositories"]:
diff --git a/src/symposium/organizing/models.py b/src/symposium/organizing/models.py
index 83dc8f2..927f74c 100644
--- a/src/symposium/organizing/models.py
+++ b/src/symposium/organizing/models.py
@@ -295,7 +295,7 @@ def validate_bundle(value: object) -> PublicBundle:
except ValueError as exc:
raise PublicationError("Session timestamps must be ISO-8601 UTC") from exc
if (
- any(t.utcoffset() is None or t.utcoffset().total_seconds() != 0 for t in times)
+ any((offset := t.utcoffset()) is None or offset.total_seconds() != 0 for t in times)
or times[1] <= times[0]
):
raise PublicationError("Session needs an increasing explicit UTC interval")
diff --git a/src/symposium/organizing/projection.py b/src/symposium/organizing/projection.py
index 51e7ef9..760a10d 100644
--- a/src/symposium/organizing/projection.py
+++ b/src/symposium/organizing/projection.py
@@ -12,7 +12,10 @@
PublicationError,
PublicBundle,
PublicEvent,
+ PublicParticipant,
+ PublicPresentation,
PublicResource,
+ PublicSession,
content_hash,
public_id,
text_hash,
@@ -65,18 +68,24 @@ def cell_text(value: Any, *, depth: int = 0) -> str:
raise PublicationError(
"Typed datetime epoch is outside the supported range"
) from exc
- if value.get("type") == "dt" and isinstance(value.get("input"), str):
- return value["input"]
- if isinstance(value.get("name"), str):
- return value["name"]
- if isinstance(value.get("text"), str):
- return value["text"]
- if isinstance(value.get("root"), dict):
- return cell_text(value["root"].get("children", []), depth=depth + 1)
- if isinstance(value.get("children"), list):
- return "".join(cell_text(child, depth=depth + 1) for child in value["children"])
- if value.get("type") == "urlref" and isinstance(value.get("url"), str):
- return value["url"]
+ input_text = value.get("input")
+ if value.get("type") == "dt" and isinstance(input_text, str):
+ return input_text
+ name = value.get("name")
+ if isinstance(name, str):
+ return name
+ text = value.get("text")
+ if isinstance(text, str):
+ return text
+ root = value.get("root")
+ if isinstance(root, dict):
+ return cell_text(root.get("children", []), depth=depth + 1)
+ children = value.get("children")
+ if isinstance(children, list):
+ return "".join(cell_text(child, depth=depth + 1) for child in children)
+ url = value.get("url")
+ if value.get("type") == "urlref" and isinstance(url, str):
+ return url
raise PublicationError("Unsupported rich-cell value requires private review")
@@ -121,7 +130,7 @@ def project_snapshot(
tables = snapshot.get("tables")
if not isinstance(tables, dict) or set(tables) != {"presentations", "participants", "sessions"}:
raise PublicationError("Incomplete private source snapshot")
- public: dict[str, Any] = {
+ public: PublicBundle = {
"schema_version": 1,
"event": event,
"presentations": [],
@@ -158,7 +167,7 @@ def project_snapshot(
try:
values = _values(row, mapping["sources"]["presentations"]["fields"])
title, presenter = values["title"], values["presenter"]
- record = {
+ presentation: PublicPresentation = {
"id": public_id("talk", presenter, title),
"presenter": presenter,
"title": title,
@@ -168,7 +177,10 @@ def project_snapshot(
"pictures": [],
"abstract_sha256": text_hash(values["abstract"]),
}
- candidate = {**public, "presentations": [*public["presentations"], record]}
+ candidate: PublicBundle = {
+ **public,
+ "presentations": [*public["presentations"], presentation],
+ }
validate_bundle(candidate)
try:
media = _picture_urls(
@@ -183,7 +195,7 @@ def project_snapshot(
"reason": "Unrecognized picture attachment withheld; text remains published",
}
)
- if not record["abstract"].strip():
+ if not presentation["abstract"].strip():
ledger["warnings"].append(
{
"kind": "presentation",
@@ -191,17 +203,17 @@ def project_snapshot(
"reason": "No program abstract published yet; keep explicit pending state",
}
)
- public["presentations"].append(record)
+ public["presentations"].append(presentation)
ledger["included"].append(
{
"kind": "presentation",
"source_row": source_id,
- "public_id": record["id"],
+ "public_id": presentation["id"],
"approval": "published-program",
- "content_sha256": content_hash(record),
+ "content_sha256": content_hash(presentation),
}
)
- ledger["media"][record["id"]] = media
+ ledger["media"][presentation["id"]] = media
except (ValueError, TypeError, KeyError) as exc:
ledger["excluded"].append(
{
@@ -210,7 +222,7 @@ def project_snapshot(
"reason": type(exc).__name__ + ": " + str(exc),
}
)
- eligible: list[tuple[str, dict[str, Any]]] = []
+ eligible: list[tuple[str, PublicParticipant]] = []
for row in tables["participants"]["rows"]:
source_id = row["rowId"]
try:
@@ -230,20 +242,20 @@ def project_snapshot(
)
continue
values = _values(row, fields)
- record = {
+ participant_values = {
key: (values[key].strip() if values[key].strip() not in NULL_VALUES else "")
for key in PARTICIPANT_FIELDS
}
- if not record["name"]:
+ if not participant_values["name"]:
ledger["excluded"].append(
{"kind": "participant", "source_row": source_id, "reason": "Blank registration"}
)
continue
- if record["orcid"] and not re.fullmatch(
+ if participant_values["orcid"] and not re.fullmatch(
r"(?:https://orcid\.org/)?[0-9]{4}-[0-9]{4}-[0-9]{4}-[0-9]{3}[0-9X]",
- record["orcid"],
+ participant_values["orcid"],
):
- record["orcid"] = ""
+ participant_values["orcid"] = ""
ledger["warnings"].append(
{
"kind": "participant",
@@ -251,9 +263,21 @@ def project_snapshot(
"reason": "Non-identifier ORCID response omitted; original retained privately",
}
)
- record["id"] = public_id("person", record["name"].casefold())
- validate_bundle({**public, "participants": [record]})
- eligible.append((source_id, record))
+ participant: PublicParticipant = {
+ "id": public_id("person", participant_values["name"].casefold()),
+ "name": participant_values["name"],
+ "affiliations": participant_values["affiliations"],
+ "orcid": participant_values["orcid"],
+ "background": participant_values["background"],
+ "pragmatic_value": participant_values["pragmatic_value"],
+ "epistemic_value": participant_values["epistemic_value"],
+ "active_inference_application": participant_values["active_inference_application"],
+ "challenges": participant_values["challenges"],
+ "learning_needs": participant_values["learning_needs"],
+ "future_impact": participant_values["future_impact"],
+ }
+ validate_bundle({**public, "participants": [participant]})
+ eligible.append((source_id, participant))
except (ValueError, TypeError, KeyError) as exc:
ledger["excluded"].append(
{
@@ -262,9 +286,9 @@ def project_snapshot(
"reason": type(exc).__name__ + ": " + str(exc),
}
)
- names = Counter(record["name"].casefold() for _, record in eligible)
- for source_id, record in eligible:
- if names[record["name"].casefold()] > 1:
+ names = Counter(person["name"].casefold() for _, person in eligible)
+ for source_id, person in eligible:
+ if names[person["name"].casefold()] > 1:
ledger["excluded"].append(
{
"kind": "participant",
@@ -273,14 +297,14 @@ def project_snapshot(
}
)
continue
- public["participants"].append(record)
+ public["participants"].append(person)
ledger["included"].append(
{
"kind": "participant",
"source_row": source_id,
- "public_id": record["id"],
+ "public_id": person["id"],
"approval": "affirmative-registration-consent",
- "content_sha256": content_hash(record),
+ "content_sha256": content_hash(person),
}
)
for row in tables["sessions"]["rows"]:
@@ -301,16 +325,23 @@ def project_snapshot(
if parsed.utcoffset() is None:
raise PublicationError("Source timestamp has no timezone")
values[key] = parsed.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")
- record = {"id": public_id("session", values["title"], values["start_utc"]), **values}
- validate_bundle({**public, "sessions": [*public["sessions"], record]})
- public["sessions"].append(record)
+ session: PublicSession = {
+ "id": public_id("session", values["title"], values["start_utc"]),
+ "title": values["title"],
+ "presenter": values["presenter"],
+ "kind": values["kind"],
+ "start_utc": values["start_utc"],
+ "end_utc": values["end_utc"],
+ }
+ validate_bundle({**public, "sessions": [*public["sessions"], session]})
+ public["sessions"].append(session)
ledger["included"].append(
{
"kind": "session",
"source_row": source_id,
- "public_id": record["id"],
+ "public_id": session["id"],
"approval": "published-schedule",
- "content_sha256": content_hash(record),
+ "content_sha256": content_hash(session),
}
)
except (ValueError, TypeError, KeyError) as exc:
diff --git a/src/symposium/organizing/publication.py b/src/symposium/organizing/publication.py
index 27dee5a..09bf419 100644
--- a/src/symposium/organizing/publication.py
+++ b/src/symposium/organizing/publication.py
@@ -37,7 +37,8 @@ def _utc(value: str) -> datetime:
parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
except (ValueError, AttributeError) as exc:
raise PublicationError("Expected explicit UTC timestamp") from exc
- if parsed.utcoffset() is None or parsed.utcoffset().total_seconds() != 0:
+ offset = parsed.utcoffset()
+ if offset is None or offset.total_seconds() != 0:
raise PublicationError("Expected explicit UTC timestamp")
return parsed
@@ -176,9 +177,12 @@ def _check_pdf(raw: bytes, *, book_contact: bool = False) -> None:
raise PublicationError("Encrypted public PDF is not permitted")
if not 0 < len(reader.pages) <= 1000:
raise PublicationError("PDF page count exceeds its bound")
- page_ids = {
- (p.indirect_reference.idnum, p.indirect_reference.generation) for p in reader.pages
- }
+ page_ids: set[tuple[int, int]] = set()
+ for page in reader.pages:
+ reference = page.indirect_reference
+ if not isinstance(reference, IndirectObject):
+ raise PublicationError("PDF page has no indirect reference")
+ page_ids.add((reference.idnum, reference.generation))
pending = [(reader.trailer, 0, False)]
seen: set[tuple[int, int]] = set()
visits = 0
@@ -191,6 +195,8 @@ def _check_pdf(raw: bytes, *, book_contact: bool = False) -> None:
if isinstance(node, IndirectObject):
identity = (node.idnum, node.generation)
resolved = node.get_object()
+ if resolved is None:
+ raise PublicationError("Unresolved PDF indirect reference")
if action:
if not isinstance(resolved, DictionaryObject) or resolved.get("/S") not in {
"/URI",
@@ -369,7 +375,10 @@ def stage_public(
bundle = validate_bundle(bundle)
if type(max_age_seconds) is not int or not 0 < max_age_seconds <= 86400:
raise PublicationError("Snapshot age limit must be positive and at most one day")
- observed = _utc(snapshot.get("observed_at"))
+ observed_at = snapshot.get("observed_at")
+ if not isinstance(observed_at, str):
+ raise PublicationError("Expected explicit UTC timestamp")
+ observed = _utc(observed_at)
if (
"snapshot_date_utc" in bundle["event"]
and bundle["event"]["snapshot_date_utc"]
diff --git a/src/symposium/organizing/review.py b/src/symposium/organizing/review.py
index 9cc5a73..9fa077e 100644
--- a/src/symposium/organizing/review.py
+++ b/src/symposium/organizing/review.py
@@ -7,7 +7,7 @@
from pathlib import Path
from typing import TypedDict
-from .models import PublicBundle, PublicLink, PublicPicture, content_hash
+from .models import PublicBundle, content_hash
from .publication import verify_public_tree
@@ -61,17 +61,17 @@ class UpdateReport(TypedDict):
def _content_readiness(bundle: PublicBundle) -> ReadinessReport:
- abstracts = sorted(
+ abstracts: list[PublicReference] = sorted(
(
- {"id": talk["id"], "name": talk["presenter"]}
+ PublicReference(id=talk["id"], name=talk["presenter"])
for talk in bundle["presentations"]
if not talk["abstract"].strip()
),
key=lambda item: item["id"],
)
- sessions = sorted(
+ sessions: list[PublicReference] = sorted(
(
- {"id": session["id"], "name": session["presenter"]}
+ PublicReference(id=session["id"], name=session["presenter"])
for session in bundle["sessions"]
if not session["title"].strip()
),
@@ -100,8 +100,8 @@ def readiness(public_dir: Path) -> ReadinessReport:
def _changes(
- previous: Sequence[Mapping[str, str | list[PublicPicture] | list[PublicLink] | int]],
- candidate: Sequence[Mapping[str, str | list[PublicPicture] | list[PublicLink] | int]],
+ previous: Sequence[Mapping[str, object]],
+ candidate: Sequence[Mapping[str, object]],
label: str,
) -> RecordChanges:
before = {str(row["id"]): row for row in previous}
diff --git a/src/symposium/organizing/site.py b/src/symposium/organizing/site.py
index 8360f77..24b543f 100644
--- a/src/symposium/organizing/site.py
+++ b/src/symposium/organizing/site.py
@@ -127,14 +127,14 @@ def build_site(
else ""
)
actions = "".join(
- _link(event.get(key, ""), label, "button" if index == 0 else "")
- for index, (key, label) in enumerate(
+ _link(url, label, "button" if index == 0 else "")
+ for index, (url, label) in enumerate(
[
- ("participant_registration_url", "Register to participate"),
- ("presenter_registration_url", "Presenter registration"),
- ("program_url", "Official program"),
- ("community_url", "Join the community"),
- ("donate_url", "Support the Institute"),
+ (event["participant_registration_url"], "Register to participate"),
+ (event["presenter_registration_url"], "Presenter registration"),
+ (event["program_url"], "Official program"),
+ (event["community_url"], "Join the community"),
+ (event["donate_url"], "Support the Institute"),
]
)
)
@@ -157,30 +157,33 @@ def build_site(
{_escape(p.get("contribution_type", "Presentation"))}{_escape(p["title"])}
{_escape(p["presenter"])}{'Abstract pending' if not p["abstract"].strip() else ""}{"Read abstract" if p["abstract"].strip() else "View presentation details"}
{_escape(p["abstract"] if p["abstract"].strip() else "No program abstract has been published for this presentation yet.")}
{"".join(images[p["id"]])}
''')
participant_rows = []
- fields = [
- ("background", "Background"),
- ("pragmatic_value", "Pragmatic value"),
- ("epistemic_value", "Epistemic value"),
- ("active_inference_application", "Applications of Active Inference"),
- ("challenges", "Challenges"),
- ("learning_needs", "Learning needs"),
- ("future_impact", "Future impact"),
- ]
- for p in bundle.get("participants", []):
- affiliations = p.get("affiliations", [])
+ for participant in bundle["participants"]:
+ affiliations = participant["affiliations"]
if isinstance(affiliations, list):
affiliations = "; ".join(affiliations)
- content = "".join(
- f'{label}
{_escape(p[key])}
'
- for key, label in fields
- if p.get(key)
+ profile_content = "".join(
+ f'{label}
{_escape(value)}
'
+ for value, label in (
+ (participant["background"], "Background"),
+ (participant["pragmatic_value"], "Pragmatic value"),
+ (participant["epistemic_value"], "Epistemic value"),
+ (
+ participant["active_inference_application"],
+ "Applications of Active Inference",
+ ),
+ (participant["challenges"], "Challenges"),
+ (participant["learning_needs"], "Learning needs"),
+ (participant["future_impact"], "Future impact"),
+ )
+ if value
)
- orcid = p.get("orcid", "")
+ orcid = participant["orcid"]
brief = _link(
- downloads.get(f"participants/{p['id']}.md", ""), "Participant brief · Markdown"
+ downloads.get(f"participants/{participant['id']}.md", ""),
+ "Participant brief · Markdown",
)
participant_rows.append(
- f'{_escape(p["name"])}
{_escape(affiliations)}Explore profile
{content}{_link(orcid if orcid.startswith("https://") else "https://orcid.org/" + orcid, "ORCID") if orcid else ""}
{brief}
'
+ f'{_escape(participant["name"])}
{_escape(affiliations)}Explore profile
{profile_content}{_link(orcid if orcid.startswith("https://") else "https://orcid.org/" + orcid, "ORCID") if orcid else ""}
{brief}
'
)
sessions = []
for s in bundle.get("sessions", []):
diff --git a/src/symposium/organizing/visualization_charts.py b/src/symposium/organizing/visualization_charts.py
index 0ccba45..c63a930 100644
--- a/src/symposium/organizing/visualization_charts.py
+++ b/src/symposium/organizing/visualization_charts.py
@@ -101,7 +101,12 @@ def topic_distribution(topics: TopicWeights, total: int) -> Figure:
"""Show complementary two-topic LDA weights in one dimension without endpoint labels."""
figure, axis = plt.subplots(figsize=(11, 5), layout="constrained")
if topics.weights.size:
- axis.hist(topics.weights[:, 0], bins=np.linspace(0, 1, 16), color=BLUE, edgecolor="white")
+ axis.hist(
+ topics.weights[:, 0],
+ bins=[float(edge) for edge in np.linspace(0, 1, 16)],
+ color=BLUE,
+ edgecolor="white",
+ )
axis.set(
xlim=(0, 1), xlabel="Topic 1 weight (Topic 2 = 1 − Topic 1)", ylabel="Participants"
)
@@ -168,7 +173,7 @@ class NetworkSummary:
def participant_network(features: TextFeatures) -> NetworkSummary:
"""Enlarge connected text edges; group isolated nodes without unreadable labels."""
- graph = nx.Graph()
+ graph: nx.Graph[str] = nx.Graph()
graph.add_nodes_from(features.ids)
edges = tuple(
(str(features.ids[i]), str(features.ids[j]), float(features.cosine[i, j]))
@@ -181,7 +186,7 @@ def participant_network(features: TextFeatures) -> NetworkSummary:
str(identifier) for identifier in features.ids if graph.degree(identifier) == 0
)
# Small subgraph views can iterate a hash-dependent node set. Keep source order.
- connected = nx.Graph()
+ connected: nx.Graph[str] = nx.Graph()
connected.add_nodes_from(identifier for identifier in features.ids if graph.degree(identifier))
connected.add_weighted_edges_from(edges)
figure, axes = plt.subplots(
diff --git a/src/symposium/visualization/embeddings.py b/src/symposium/visualization/embeddings.py
index 56b7049..4181827 100644
--- a/src/symposium/visualization/embeddings.py
+++ b/src/symposium/visualization/embeddings.py
@@ -14,6 +14,7 @@
import matplotlib.pyplot as plt
import seaborn as sns
from adjustText import adjust_text
+from sklearn.base import BaseEstimator
from sklearn.decomposition import PCA, TruncatedSVD
from sklearn.feature_extraction.text import TfidfVectorizer
from wordcloud import WordCloud
@@ -56,6 +57,7 @@ def perform_tfidf_and_reduction(
max_doc_freq = 0.90 if n_docs >= 3 else 1.0
# TF-IDF vectorization with improved parameters
+ vectorizer: TfidfVectorizer | None
vectorizer = TfidfVectorizer(
max_features=10000, # Increased for better representation
stop_words="english",
@@ -78,6 +80,8 @@ def perform_tfidf_and_reduction(
)
n_components = max_components
+ reducer: BaseEstimator
+
if method.lower() == "pca":
# Enhanced PCA with whitening
# Ensure we have at least 1 component
@@ -379,7 +383,7 @@ def create_word_cloud(
# Plot with enhanced styling
plt.figure(figsize=(24, 12))
- plt.imshow(wordcloud, interpolation="bilinear")
+ plt.imshow(wordcloud.to_array(), interpolation="bilinear")
plt.axis("off")
plt.title(title, fontsize=24, fontweight="bold", pad=20)
plt.tight_layout()
diff --git a/src/symposium/visualization/networks.py b/src/symposium/visualization/networks.py
index b1b203f..60e6219 100644
--- a/src/symposium/visualization/networks.py
+++ b/src/symposium/visualization/networks.py
@@ -1,6 +1,7 @@
"""Network analysis and visualization tools."""
import logging
+from collections.abc import Hashable, Mapping
from pathlib import Path
from typing import Any, Dict, List, Optional
@@ -10,6 +11,7 @@
matplotlib.use("Agg")
import matplotlib.pyplot as plt
import networkx as nx
+from numpy.typing import NDArray
from sklearn.feature_extraction.text import TfidfVectorizer
from sklearn.metrics.pairwise import cosine_similarity
@@ -61,7 +63,7 @@ def create_similarity_network(
similarity_matrix = cosine_similarity(term_matrix.T)
# Create graph
- g = nx.Graph()
+ g: "nx.Graph[str]" = nx.Graph()
# Add nodes
for term in top_terms:
@@ -128,6 +130,7 @@ def plot_network(
plt.figure(figsize=(20, 20))
# Choose layout
+ pos: Mapping[Hashable, NDArray[np.float32] | NDArray[np.float64]]
if layout == "spring":
pos = nx.spring_layout(graph, k=2, iterations=50, seed=self.random_state)
elif layout == "circular":
@@ -208,9 +211,10 @@ def analyze_communities(self, graph: nx.Graph) -> Dict[str, Any]:
communities = list(nx.community.greedy_modularity_communities(graph))
# Calculate community metrics
+ community_details: list[dict[str, object]] = []
analysis = {
"n_communities": len(communities),
- "communities": [],
+ "communities": community_details,
"modularity": nx.community.modularity(graph, communities),
}
@@ -225,7 +229,7 @@ def analyze_communities(self, graph: nx.Graph) -> Dict[str, Any]:
"density": nx.density(community_subgraph),
"avg_clustering": nx.average_clustering(community_subgraph),
}
- analysis["communities"].append(community_info)
+ community_details.append(community_info)
logger.info(
f"Found {len(communities)} communities with modularity {analysis['modularity']:.3f}"
diff --git a/tests/README.md b/tests/README.md
index 58c7950..bc4bfb9 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -4,14 +4,15 @@ Use Python 3.12+ and the committed uv lock. The development pin is 3.12.
```bash
uv sync --locked --extra dev --python 3.12
-./gate.sh test # full suite with the 80% coverage gate
+./gate.sh test # full suite with the 90.01% coverage gate
./gate.sh test-fast # package-module suites only, --no-cov
```
-The pytest configuration enables line coverage, terminal/HTML reports and an 80%
-regression gate. These settings do not establish complete coverage or scientific,
-visual, native-render or deployment correctness. Inspect the actual result and
-retained failures for the revision being tested.
+The pytest configuration enables line coverage, terminal/HTML reports and a 90.01%
+regression floor with two-decimal reporting precision. The precision is required
+for that fractional floor. These settings do not establish complete coverage or
+scientific, visual, native-render or deployment correctness. Inspect the actual
+result and retained failures for the revision being tested.
## Focused checks
diff --git a/tests/conftest.py b/tests/conftest.py
index 9c12779..ae48a9e 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -1,5 +1,6 @@
"""Test configuration and fixtures for symposium package tests."""
+import json
import shutil
import tempfile
from pathlib import Path
@@ -51,6 +52,58 @@ def mock_api_client():
return client
+@pytest.fixture
+def offline_api_requests(monkeypatch, tmp_path):
+ """Exercise the real SDK/configuration path without opening network connections."""
+ import httpx
+ from openai import OpenAI
+
+ monkeypatch.chdir(tmp_path)
+ for name in (
+ "API_PROVIDER",
+ "PERPLEXITY_API_KEY",
+ "OPENROUTER_API_KEY",
+ "SYMPOSIUM_YEAR",
+ "SYMPOSIUM_DATA_DIR",
+ "SYMPOSIUM_OUTPUTS_DIR",
+ ):
+ monkeypatch.delenv(name, raising=False)
+ requests = []
+ clients = []
+
+ def respond(request):
+ requests.append(request)
+ payload = json.loads(request.content)
+ return httpx.Response(
+ 200,
+ json={
+ "id": "offline-completion",
+ "object": "chat.completion",
+ "created": 0,
+ "model": payload["model"],
+ "choices": [
+ {
+ "index": 0,
+ "finish_reason": "stop",
+ "message": {"role": "assistant", "content": "Offline provider response"},
+ }
+ ],
+ },
+ )
+
+ def create_client(**kwargs):
+ client = OpenAI(**kwargs, http_client=httpx.Client(transport=httpx.MockTransport(respond)))
+ clients.append(client)
+ return client
+
+ monkeypatch.setattr("symposium.core.api.OpenAI", create_client)
+ try:
+ yield requests
+ finally:
+ for client in clients:
+ client.close()
+
+
@pytest.fixture
def sample_presenter_data():
"""Create sample presenter data."""
diff --git a/tests/test_2026_workflows.py b/tests/test_2026_workflows.py
index a918f87..8393ef3 100644
--- a/tests/test_2026_workflows.py
+++ b/tests/test_2026_workflows.py
@@ -333,3 +333,38 @@ def create(**kwargs):
provider.get_response("Offline prompt", temperature=0.1, max_tokens=50)
assert requests[1]["temperature"] == 0.1
assert requests[1]["max_tokens"] == 50
+
+
+def test_runner_background_flow_uses_selected_config(tmp_path, monkeypatch, offline_api_requests):
+ selected = tmp_path / "selected.json"
+ selected.write_text(
+ json.dumps(
+ {
+ "edition": {"year": 2026},
+ "paths": {
+ "data_dir": str(tmp_path / "data"),
+ "outputs_dir": str(tmp_path / "outputs"),
+ },
+ "api": {
+ "provider": "openrouter",
+ "openrouter": {"api_key": "offline-router"},
+ "perplexity": {"api_key": "file-perplexity", "model": "selected-perplexity"},
+ },
+ }
+ )
+ )
+ (tmp_path / "config.json").write_text('{"api":{"provider":"invalid"}}')
+ expected_key = "environment-perplexity"
+ monkeypatch.setenv("PERPLEXITY_API_KEY", expected_key)
+ runner = load_runner().SymposiumRunner(config_file=selected)
+ runner.edition.participants_csv.parent.mkdir(parents=True)
+ runner.edition.participants_csv.write_text(registration(tmp_path).read_text())
+ monkeypatch.setattr("builtins.input", lambda prompt: "2")
+ runner.analyze_participants()
+ (request,) = offline_api_requests
+ assert request.url.host == "api.perplexity.ai"
+ assert request.headers["Authorization"] == f"Bearer {expected_key}"
+ assert json.loads(request.content)["model"] == "selected-perplexity"
+ (report,) = runner.edition.output_dir.rglob("*background_research.json")
+ assert json.loads(report.read_text())["content"] == "Offline provider response"
+ assert not list(runner.edition.output_dir.rglob("*profile_analysis*"))
diff --git a/tests/test_analysis/test_presenters.py b/tests/test_analysis/test_presenters.py
index 8ca04c0..10ca402 100644
--- a/tests/test_analysis/test_presenters.py
+++ b/tests/test_analysis/test_presenters.py
@@ -1,11 +1,15 @@
"""Tests for presenter analysis module."""
+import json
from unittest.mock import patch
import pandas as pd
import pytest
from symposium.analysis.presenters import PresenterAnalyzer
+from symposium.core.api import PaymentRequiredError
+from symposium.core.batch import BatchIncompleteError
+from symposium.io.writers import ReportWriter
class TestPresenterAnalyzer:
@@ -111,9 +115,68 @@ def test_analyze_all_presenters_api_error(self, analyzer, temp_dir, sample_prese
works_df = pd.DataFrame({"title": ["Paper 1"], "publication_year": [2023]})
works_df.to_csv(presenter_dir / "works-test.csv", index=False)
- # Mock API to raise exception
with patch.object(analyzer.api_client, "get_response", side_effect=Exception("API Error")):
- results = analyzer.analyze_all_presenters(temp_dir, temp_dir / "outputs")
-
- # Should continue processing despite errors
- assert results == {}
+ with pytest.raises(BatchIncompleteError) as exc:
+ analyzer.analyze_all_presenters(temp_dir, temp_dir / "outputs")
+ assert exc.value.completed == {}
+ assert set(exc.value.failures) == {"Test_Presenter"}
+ assert exc.value.requested == 1
+
+ @pytest.mark.parametrize("format_name", ["markdown", "json"])
+ def test_batch_counts_only_persisted_reports(
+ self, analyzer, sample_presenter_data, tmp_path, monkeypatch, format_name
+ ):
+ presenters = {
+ name: {**sample_presenter_data, "name": name} for name in ("First", "Second", "Later")
+ }
+ monkeypatch.setattr(analyzer, "load_presenter_data", lambda *a, **k: presenters)
+ method = f"save_{format_name}_report"
+ original = getattr(ReportWriter, method)
+
+ def save(content, filepath, *args, **kwargs):
+ if filepath.parent.name == "Second":
+ raise OSError("Synthetic storage failure")
+ return original(content, filepath, *args, **kwargs)
+
+ monkeypatch.setattr(ReportWriter, method, save)
+ output = tmp_path / "reports"
+ with pytest.raises(BatchIncompleteError) as exc:
+ analyzer.analyze_all_presenters(tmp_path, output)
+ assert exc.value.requested == 3
+ assert set(exc.value.completed) == {"First", "Later"}
+ assert set(exc.value.failures) == {"Second"}
+ assert exc.value.output_dir == output
+ for name in ("First", "Later"):
+ report = output / name / f"{name}_research_profile"
+ assert (
+ json.loads(report.with_suffix(".json").read_text())["content"]
+ == "Mock API response"
+ )
+ assert "Mock API response" in report.with_suffix(".md").read_text()
+ partial = output / "Second" / "Second_research_profile"
+ assert partial.with_suffix(".md").exists() is (format_name == "json")
+ assert not partial.with_suffix(".json").exists()
+
+ def test_payment_stops_after_preserving_completed_presenter(
+ self, analyzer, sample_presenter_data, tmp_path, monkeypatch
+ ):
+ presenters = {
+ name: {**sample_presenter_data, "name": name} for name in ("First", "Second", "Later")
+ }
+ monkeypatch.setattr(analyzer, "load_presenter_data", lambda *a, **k: presenters)
+ analyzer.api_client.get_response.side_effect = [
+ "Persisted presenter",
+ PaymentRequiredError("Cannot generate without credits", "openrouter"),
+ "Must not be requested",
+ ]
+ output = tmp_path / "reports"
+ with pytest.raises(PaymentRequiredError):
+ analyzer.analyze_all_presenters(tmp_path, output)
+ assert analyzer.api_client.get_response.call_count == 2
+ first = output / "First" / "First_research_profile"
+ assert (
+ json.loads(first.with_suffix(".json").read_text())["content"] == "Persisted presenter"
+ )
+ assert "Persisted presenter" in first.with_suffix(".md").read_text()
+ assert not (output / "Second").exists()
+ assert not (output / "Later").exists()
diff --git a/tests/test_calendar/test_exporter.py b/tests/test_calendar/test_exporter.py
index cb149d7..80358c4 100644
--- a/tests/test_calendar/test_exporter.py
+++ b/tests/test_calendar/test_exporter.py
@@ -1,10 +1,12 @@
"""Tests for calendar export functionality."""
-from datetime import datetime
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
import icalendar
import pytest
+import symposium.calendar.exporter as exporter_module
from symposium.calendar.exporter import ScheduleExporter
@@ -123,14 +125,13 @@ def test_parse_datetime_various_formats(self):
assert result.month == 6
assert result.day == 15
- def test_parse_datetime_invalid(self):
- """Test parsing invalid datetime."""
+ @pytest.mark.parametrize(
+ "value", ["invalid_datetime", "2025-02-30T09:00:00", "2025-06-15T09:00:00+25:00", ""]
+ )
+ def test_parse_datetime_invalid(self, value):
exporter = ScheduleExporter()
- result = exporter._parse_datetime("invalid_datetime")
-
- assert result is not None
- # Should return current time if parsing fails
- assert isinstance(result, datetime)
+ with pytest.raises(ValueError):
+ exporter._parse_datetime(value)
def test_parse_schedule_data_dict_format(self, sample_schedule_data):
"""Test parsing schedule data in dictionary format."""
@@ -312,3 +313,136 @@ def test_parse_schedule_data_invalid_format(self, exporter):
events = exporter.parse_schedule_data("invalid format")
assert len(events) == 0
+
+ @pytest.mark.parametrize(
+ "value,utc_hour",
+ [
+ ("2025-06-15T13:00:00Z", 13),
+ ("2025-06-15T09:00:00-04:00", 13),
+ ("2025-06-15T15:00:00+02:00", 13),
+ ("2025-06-15 09:00:00", 13),
+ ("2025-06-15T09:00:00", 13),
+ ("2025-06-15 09:00", 13),
+ ("2025-06-15T09:00", 13),
+ ("2025-06-15", 4),
+ (datetime(2025, 6, 15, 9), 13),
+ (datetime(2025, 6, 15, 13, tzinfo=timezone.utc), 13),
+ ],
+ )
+ def test_export_round_trips_instants_and_naive_timezone(self, tmp_path, value, utc_hour):
+ exporter = ScheduleExporter({"timezone": "America/New_York"})
+ output = tmp_path / "schedule.ics"
+ output.write_bytes(b"previous calendar\r\n")
+ assert exporter.export_symposium_schedule(
+ [{"title": "Synthetic event", "start_time": value}], output
+ )
+ calendar = icalendar.Calendar.from_ical(output.read_bytes())
+ events = [component for component in calendar.walk() if component.name == "VEVENT"]
+ assert len(events) == 1
+ expected = datetime(2025, 6, 15, utc_hour, tzinfo=timezone.utc)
+ assert events[0].decoded("dtstart").astimezone(timezone.utc) == expected
+ assert events[0].decoded("dtend").astimezone(timezone.utc) == expected + timedelta(hours=1)
+ assert str(events[0]["summary"]) == "Synthetic event"
+ assert set(tmp_path.iterdir()) == {output}
+
+ @pytest.mark.parametrize("field", ["start_time", "end_time"])
+ def test_invalid_timestamp_rejects_whole_publication(self, exporter, tmp_path, field):
+ output = tmp_path / "schedule.ics"
+ original = b"previous calendar\r\n"
+ output.write_bytes(original)
+ invalid = {
+ "title": "Invalid event",
+ "start_time": "2025-06-15T09:00:00Z",
+ "end_time": "2025-06-15T10:00:00Z",
+ field: "not-a-timestamp",
+ }
+ schedule = [
+ {"title": "Valid event", "start_time": "2025-06-15T08:00:00Z"},
+ invalid,
+ ]
+ assert not exporter.export_symposium_schedule(schedule, output)
+ assert output.read_bytes() == original
+ assert set(tmp_path.iterdir()) == {output}
+ report = exporter.validate_schedule(schedule)
+ assert report["valid_events"] == 1
+ assert len(report["errors"]) == 1
+
+ @pytest.mark.parametrize(
+ "failure",
+ [
+ "construction",
+ "serialization",
+ "creation",
+ "write",
+ "short_write",
+ "flush",
+ "close",
+ "sync",
+ "replace",
+ ],
+ )
+ def test_failed_publication_preserves_existing_bytes_and_other_temps(
+ self, exporter, sample_schedule_data, tmp_path, monkeypatch, failure
+ ):
+ output = tmp_path / "schedule.ics"
+ original = b"previous calendar\r\n\x00"
+ output.write_bytes(original)
+ unrelated = tmp_path / ".schedule.ics.someone-else.tmp"
+ unrelated.write_bytes(b"not owned by this export")
+ events = exporter.parse_schedule_data(sample_schedule_data)
+ owned_temps = []
+
+ def fail(*args, **kwargs):
+ raise OSError("Synthetic publication failure")
+
+ if failure == "construction":
+ monkeypatch.setattr(exporter, "create_ics_calendar", fail)
+ elif failure == "serialization":
+ monkeypatch.setattr(icalendar.Calendar, "to_ical", fail)
+ elif failure == "creation":
+ monkeypatch.setattr(exporter_module, "NamedTemporaryFile", fail)
+ elif failure in ("write", "short_write", "flush", "close"):
+ create_temporary = exporter_module.NamedTemporaryFile
+
+ class BrokenTemporary:
+ def __init__(self, **kwargs):
+ self.file = create_temporary(**kwargs)
+ self.name = self.file.name
+ owned_temps.append(Path(self.name))
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, *args):
+ result = self.file.__exit__(*args)
+ if failure == "close":
+ raise OSError("Synthetic close failure")
+ return result
+
+ def write(self, content):
+ if failure in ("write", "short_write"):
+ self.file.write(content[:7])
+ if failure == "short_write":
+ return 7
+ raise OSError("Synthetic partial write")
+ return self.file.write(content)
+
+ def flush(self):
+ if failure == "flush":
+ raise OSError("Synthetic flush failure")
+ return self.file.flush()
+
+ def fileno(self):
+ return self.file.fileno()
+
+ monkeypatch.setattr(exporter_module, "NamedTemporaryFile", BrokenTemporary)
+ elif failure == "sync":
+ monkeypatch.setattr(exporter_module.os, "fsync", fail)
+ else:
+ monkeypatch.setattr(exporter_module.os, "replace", fail)
+
+ assert not exporter.export_ics_file(events, output)
+ assert output.read_bytes() == original
+ assert unrelated.read_bytes() == b"not owned by this export"
+ assert all(not path.exists() for path in owned_temps)
+ assert set(tmp_path.iterdir()) == {output, unrelated}
diff --git a/tests/test_cli/test_analyze_generate.py b/tests/test_cli/test_analyze_generate.py
index bd42f5b..225a27d 100644
--- a/tests/test_cli/test_analyze_generate.py
+++ b/tests/test_cli/test_analyze_generate.py
@@ -8,8 +8,14 @@
import argparse
import json
+import os
+import subprocess
+import sys
+from pathlib import Path
from unittest.mock import Mock
+import pytest
+
def _args(**kwargs):
defaults = {
@@ -172,3 +178,198 @@ def test_generate_participant_curricula_handler(tmp_path, monkeypatch):
assert not (out / "Alice" / "Alice_profile_analysis.md").exists()
assert (out / "Alice" / "Alice_curriculum.md").exists()
+
+
+@pytest.mark.parametrize(
+ "handler_name",
+ [
+ "analyze_presenters",
+ "analyze_participants",
+ "analyze_participant_backgrounds",
+ "generate_participant_curricula",
+ "generate_profiles",
+ "generate_projects",
+ ],
+)
+def test_handlers_honor_selected_config_and_forced_provider(
+ tmp_path, monkeypatch, offline_api_requests, handler_name
+):
+ from symposium.cli import analyze, generate
+
+ data = tmp_path / "presenters"
+ data.mkdir()
+ _presenter_dir(data, "Alice")
+ profiles = tmp_path / "profiles"
+ _profile_json(profiles / "Alice")
+ csv_path = _participant_csv(tmp_path)
+ domain = tmp_path / "domain.md"
+ domain.write_text("Synthetic domain")
+ templates = tmp_path / "templates"
+ templates.mkdir()
+ (templates / "KarmaGAPGrants.md").write_text("Synthetic questions")
+ selected = tmp_path / "selected.json"
+ selected.write_text(
+ json.dumps(
+ {
+ "api": {
+ "provider": "openrouter",
+ "openrouter": {"api_key": "file-router", "model": "selected-router"},
+ "perplexity": {"api_key": "file-perplexity", "model": "selected-perplexity"},
+ }
+ }
+ )
+ )
+ (tmp_path / "config.json").write_text('{"api":{"provider":"invalid"}}')
+ monkeypatch.setenv("OPENROUTER_API_KEY", "environment-router")
+ monkeypatch.setenv("PERPLEXITY_API_KEY", "environment-perplexity")
+ output = tmp_path / "reports"
+ args = _args(
+ config=str(selected),
+ data_dir=str(data),
+ csv_file=str(csv_path),
+ profiles_dir=str(profiles),
+ domain_file=str(domain),
+ catechisms_dir=str(templates),
+ output_dir=str(output),
+ )
+ module = generate if handler_name in ("generate_profiles", "generate_projects") else analyze
+ getattr(module, handler_name)(args)
+ (request,) = offline_api_requests
+ forced = handler_name == "analyze_participant_backgrounds"
+ assert request.url.host == ("api.perplexity.ai" if forced else "openrouter.ai")
+ key = "environment-perplexity" if forced else "environment-router"
+ model = "selected-perplexity" if forced else "selected-router"
+ assert request.headers["Authorization"] == f"Bearer {key}"
+ assert json.loads(request.content)["model"] == model
+ (report,) = output.rglob("*.json")
+ assert json.loads(report.read_text())["content"] == "Offline provider response"
+
+
+def test_combined_participant_background_uses_perplexity(tmp_path, offline_api_requests):
+ from symposium.cli import analyze
+
+ selected = tmp_path / "selected.json"
+ selected.write_text(
+ json.dumps(
+ {
+ "api": {
+ "provider": "openrouter",
+ "openrouter": {"api_key": "offline-router"},
+ "perplexity": {"api_key": "offline-perplexity"},
+ }
+ }
+ )
+ )
+ output = tmp_path / "reports"
+ analyze.analyze_participants(
+ _args(
+ config=str(selected),
+ csv_file=str(_participant_csv(tmp_path)),
+ output_dir=str(output),
+ include_background_research=True,
+ )
+ )
+ assert [request.url.host for request in offline_api_requests] == [
+ "openrouter.ai",
+ "api.perplexity.ai",
+ ]
+ for kind in ("profile_analysis", "background_research"):
+ report = output / "Alice" / f"Alice_{kind}.json"
+ assert json.loads(report.read_text())["content"] == "Offline provider response"
+
+
+@pytest.mark.parametrize("flow", ["presenters", "profiles", "projects"])
+@pytest.mark.parametrize("failure", ["payment", "persistence", "empty"])
+def test_real_cli_exit_rejects_incomplete_work_and_preserves_files(tmp_path, flow, failure):
+ data = tmp_path / "inputs"
+ data.mkdir()
+ if failure != "empty":
+ for name in ("Alice", "Bob"):
+ if flow == "projects":
+ _profile_json(data / name)
+ else:
+ _presenter_dir(data, name)
+ output = tmp_path / "reports"
+ if flow == "projects":
+ domain = tmp_path / "domain.md"
+ domain.write_text("Synthetic domain")
+ (tmp_path / "KarmaGAPGrants.md").write_text("Synthetic questions")
+ arguments = [
+ "generate",
+ "projects",
+ "--profiles-dir",
+ str(data),
+ "--domain-file",
+ str(domain),
+ "--catechisms-dir",
+ str(tmp_path),
+ ]
+ else:
+ arguments = [
+ "analyze" if flow == "presenters" else "generate",
+ flow,
+ "--data-dir",
+ str(data),
+ ]
+ arguments.extend(["--output-dir", str(output)])
+ script = """
+import runpy
+import sys
+from types import SimpleNamespace
+from symposium.core.api import APIClient, PaymentRequiredError
+from symposium.io.writers import ReportWriter
+
+failure = sys.argv.pop(1)
+calls = 0
+writes = 0
+
+def response(*args, **kwargs):
+ global calls
+ calls += 1
+ if failure == "payment" and calls == 2:
+ raise PaymentRequiredError("Cannot generate without credits", "openrouter")
+ return "Persisted offline response"
+
+APIClient.create = staticmethod(lambda **kwargs: SimpleNamespace(get_response=response))
+original_save = ReportWriter.save_json_report
+
+def save_json(*args, **kwargs):
+ global writes
+ writes += 1
+ if failure == "persistence" and writes == 2:
+ raise OSError("Synthetic storage failure")
+ return original_save(*args, **kwargs)
+
+ReportWriter.save_json_report = staticmethod(save_json)
+sys.argv[0] = "symposium"
+runpy.run_module("symposium", run_name="__main__")
+"""
+ environment = dict(os.environ)
+ for key in (
+ "API_PROVIDER",
+ "PERPLEXITY_API_KEY",
+ "OPENROUTER_API_KEY",
+ "SYMPOSIUM_YEAR",
+ "SYMPOSIUM_DATA_DIR",
+ "SYMPOSIUM_OUTPUTS_DIR",
+ ):
+ environment.pop(key, None)
+ environment["PYTHONPATH"] = str(Path(__file__).resolve().parents[2] / "src")
+ result = subprocess.run(
+ [sys.executable, "-c", script, failure, *arguments],
+ cwd=tmp_path,
+ env=environment,
+ capture_output=True,
+ text=True,
+ timeout=30,
+ )
+ assert result.returncode == 1, result.stdout + result.stderr
+ reports = list(output.rglob("*.json"))
+ markdown = list(output.rglob("*.md"))
+ if failure == "empty":
+ assert reports == markdown == []
+ else:
+ assert len(reports) == 1
+ assert json.loads(reports[0].read_text())["content"] == "Persisted offline response"
+ assert "Persisted offline response" in reports[0].with_suffix(".md").read_text()
+ assert len(markdown) == (2 if failure == "persistence" else 1)
diff --git a/tests/test_core/test_api.py b/tests/test_core/test_api.py
index 58cb019..44880dc 100644
--- a/tests/test_core/test_api.py
+++ b/tests/test_core/test_api.py
@@ -1,11 +1,12 @@
"""Tests for API client module."""
+import json
import os
from unittest.mock import Mock, patch
import httpx
import pytest
-from openai import APIStatusError
+from openai import APIStatusError, OpenAI
from symposium.core.api import (
APIClient,
@@ -13,6 +14,7 @@
PaymentRequiredError,
PerplexityProvider,
)
+from symposium.core.config import Config
class TestAPIClient:
@@ -301,26 +303,135 @@ def test_openrouter_non_402_error_passes_through(self, mock_openai):
with pytest.raises(APIStatusError):
provider.get_response("test prompt")
- @patch("symposium.core.api.OpenAI")
- def test_payment_error_no_retry(self, mock_openai):
- """Test that payment errors don't trigger retry logic."""
- mock_client = Mock()
- request = httpx.Request("POST", "https://api.openrouter.ai/api/v1/chat/completions")
- response = httpx.Response(
- status_code=402,
- request=request,
- json={"error": {"message": "Insufficient credits", "code": 402}},
- )
- api_error = APIStatusError(message="Insufficient credits", response=response, body=None)
-
- mock_client.chat.completions.create.side_effect = api_error
- mock_openai.return_value = mock_client
-
- provider = OpenRouterProvider("test_key")
-
- # Should raise PaymentRequiredError immediately (no retries)
- with pytest.raises(PaymentRequiredError):
- provider.get_response("test prompt")
-
- # Verify it was only called once (no retries)
- assert mock_client.chat.completions.create.call_count == 1
+ @pytest.mark.parametrize(
+ "message",
+ [
+ "Insufficient credits",
+ "Cannot generate without credits",
+ "Payment rate exceeded",
+ "Payment timeout",
+ ],
+ )
+ def test_payment_error_no_retry(self, message, monkeypatch):
+ """A real SDK 402 response is terminal even when its text looks retryable."""
+ attempts = []
+
+ def respond(request):
+ attempts.append(request)
+ return httpx.Response(402, json={"error": {"message": message, "code": 402}})
+
+ monkeypatch.setattr("backoff._sync.time.sleep", lambda delay: None)
+ with OpenAI(
+ api_key="offline-key",
+ base_url="https://openrouter.invalid/api/v1",
+ max_retries=0,
+ http_client=httpx.Client(transport=httpx.MockTransport(respond)),
+ ) as client:
+ monkeypatch.setattr("symposium.core.api.OpenAI", lambda **kwargs: client)
+ provider = OpenRouterProvider("offline-key")
+ with pytest.raises(PaymentRequiredError) as exc:
+ provider.get_response("Synthetic payment regression")
+ assert exc.value.message == message
+ assert len(attempts) == 1
+
+
+@pytest.mark.parametrize("content", [None, ""])
+@patch("symposium.core.api.OpenAI")
+def test_perplexity_rejects_missing_content(mock_openai, content):
+ response = Mock()
+ response.choices = [Mock(message=Mock(content=content))]
+ mock_openai.return_value.chat.completions.create.return_value = response
+ with pytest.raises(ValueError):
+ PerplexityProvider("offline-key").get_response("Synthetic empty response")
+
+
+@pytest.mark.parametrize(
+ "file_provider,environment_provider,explicit_provider,environment_keys,explicit_key,expected",
+ [
+ (None, None, None, False, None, "perplexity"),
+ ("openrouter", None, None, False, None, "openrouter"),
+ ("perplexity", "openrouter", None, True, None, "openrouter"),
+ ("openrouter", "openrouter", "perplexity", True, None, "perplexity"),
+ ("openrouter", None, None, True, "explicit-key", "openrouter"),
+ ],
+)
+def test_configured_provider_uses_selected_credentials_and_options(
+ tmp_path,
+ monkeypatch,
+ offline_api_requests,
+ file_provider,
+ environment_provider,
+ explicit_provider,
+ environment_keys,
+ explicit_key,
+ expected,
+):
+ api = {
+ name: {
+ "api_key": f"file-{name}",
+ "model": f"selected-{name}",
+ "temperature": 0.2,
+ "max_tokens": 123,
+ }
+ for name in ("perplexity", "openrouter")
+ }
+ if file_provider is not None:
+ api["provider"] = file_provider
+ selected_file = tmp_path / "selected.json"
+ selected_file.write_text(json.dumps({"api": api}))
+ (tmp_path / "config.json").write_text('{"api":{"provider":"invalid"}}')
+ if environment_provider is not None:
+ monkeypatch.setenv("API_PROVIDER", environment_provider)
+ if environment_keys:
+ for name in ("perplexity", "openrouter"):
+ monkeypatch.setenv(f"{name.upper()}_API_KEY", f"environment-{name}")
+ config = Config(config_file=selected_file, load_env=False)
+ before = config.to_dict()
+ provider = APIClient.from_config(config, provider=explicit_provider, api_key=explicit_key)
+ assert provider.get_response("Synthetic configured request") == "Offline provider response"
+ (request,) = offline_api_requests
+ host = "api.perplexity.ai" if expected == "perplexity" else "openrouter.ai"
+ assert request.url.host == host
+ key = explicit_key or f"{'environment' if environment_keys else 'file'}-{expected}"
+ assert request.headers["Authorization"] == f"Bearer {key}"
+ payload = json.loads(request.content)
+ assert payload["model"] == f"selected-{expected}"
+ assert payload["temperature"] == 0.2
+ assert payload["max_tokens"] == 123
+ assert config.to_dict() == before
+
+
+def test_configured_provider_explicit_options_do_not_mutate_config(offline_api_requests):
+ config = Config(load_env=False)
+ config.set("api.perplexity.api_key", "configured-key")
+ config.set("api.perplexity.model", "configured-model")
+ provider = APIClient.from_config(
+ config, api_key="explicit-key", model="explicit-model", max_tokens=17
+ )
+ provider.get_response("Synthetic option override")
+ (request,) = offline_api_requests
+ assert request.headers["Authorization"] == "Bearer explicit-key"
+ assert json.loads(request.content)["model"] == "explicit-model"
+ assert json.loads(request.content)["max_tokens"] == 17
+ assert config.get_api_key("perplexity") == "configured-key"
+ assert config.get("api.perplexity.model") == "configured-model"
+
+
+@pytest.mark.parametrize("provider", ["perplexity", "openrouter"])
+def test_configured_provider_rejects_missing_or_empty_key(provider, offline_api_requests):
+ config = Config(load_env=False)
+ with pytest.raises(ValueError):
+ APIClient.from_config(config, provider=provider)
+ config.set(f"api.{provider}.api_key", "configured-key")
+ with pytest.raises(ValueError):
+ APIClient.from_config(config, provider=provider, api_key="")
+ assert offline_api_requests == []
+
+
+def test_configured_provider_rejects_conflicting_provider_option(offline_api_requests):
+ config = Config(load_env=False)
+ config.set("api.perplexity.api_key", "offline-key")
+ config.set("api.perplexity.provider", "openrouter")
+ with pytest.raises(ValueError):
+ APIClient.from_config(config, provider="perplexity")
+ assert offline_api_requests == []
diff --git a/tests/test_core/test_config.py b/tests/test_core/test_config.py
index 1b3c382..2c07801 100644
--- a/tests/test_core/test_config.py
+++ b/tests/test_core/test_config.py
@@ -42,6 +42,28 @@ def test_get_api_config(self):
api_config = config.get_api_config("perplexity")
assert api_config["model"] == "sonar"
+ @pytest.mark.parametrize("settings", [None, False, 0, "synthetic-secret", ["synthetic-secret"]])
+ def test_get_api_config_rejects_non_object(self, tmp_path, settings):
+ config_file = tmp_path / "config.json"
+ config_file.write_text(json.dumps({"api": {"custom": settings}}), encoding="utf-8")
+ config = Config(config_file=config_file, load_env=False)
+
+ with pytest.raises(ValueError, match="api.custom") as error:
+ config.get_api_config("custom")
+ assert "synthetic-secret" not in str(error.value)
+
+ def test_get_api_config_rejects_non_string_keys(self):
+ config = Config(load_env=False)
+ config.set("api.custom", {1: "synthetic-secret"})
+
+ with pytest.raises(ValueError, match="api.custom") as error:
+ config.get_api_config("custom")
+ assert "synthetic-secret" not in str(error.value)
+
+ def test_get_api_config_missing_provider(self):
+ config = Config(load_env=False)
+ assert config.get_api_config("custom") == {}
+
def test_get_api_key(self):
"""Test getting API key."""
config = Config(load_env=False)
@@ -55,6 +77,78 @@ def test_get_api_key_from_environment(self):
# Must read the exact key we injected, proving env vars are actually consumed.
assert config.get_api_key("perplexity") == "env_perplexity_key"
+ @pytest.mark.parametrize(
+ "key", [False, 0, 17, [], ["synthetic-secret"], {"token": "synthetic-secret"}]
+ )
+ def test_get_api_key_rejects_non_string(self, tmp_path, monkeypatch, key):
+ monkeypatch.chdir(tmp_path)
+ config_file = tmp_path / "config.json"
+ config_file.write_text(json.dumps({"api": {"custom": {"api_key": key}}}), encoding="utf-8")
+ config = Config(config_file=config_file, load_env=False)
+
+ with pytest.raises(ValueError, match="api.custom.api_key") as error:
+ config.get_api_key("custom")
+ assert "synthetic-secret" not in str(error.value)
+
+ @pytest.mark.parametrize("provider", ["perplexity", "openrouter"])
+ @pytest.mark.parametrize("empty_key", [None, ""])
+ def test_get_api_key_preserves_precedence(self, tmp_path, monkeypatch, provider, empty_key):
+ monkeypatch.chdir(tmp_path)
+ env_name = f"{provider.upper()}_API_KEY"
+ monkeypatch.setenv(env_name, "environment-key")
+ (tmp_path / "llm_keys.key").write_text(
+ json.dumps({provider: "legacy-key"}), encoding="utf-8"
+ )
+ config = Config(load_env=False)
+ config.set(f"api.{provider}.api_key", "configured-key")
+ assert config.get_api_key(provider) == "configured-key"
+
+ config.set(f"api.{provider}.api_key", empty_key)
+ assert config.get_api_key(provider) == "environment-key"
+ monkeypatch.delenv(env_name)
+ assert config.get_api_key(provider) is None
+
+ @pytest.mark.parametrize(
+ "keys",
+ [
+ ["synthetic-secret"],
+ "synthetic-secret",
+ None,
+ {"legacy": False},
+ {"legacy": 0},
+ {"legacy": []},
+ {"legacy": ["synthetic-secret"]},
+ {"legacy": {"token": "synthetic-secret"}},
+ ],
+ )
+ def test_legacy_api_key_rejects_malformed_values(self, tmp_path, monkeypatch, caplog, keys):
+ monkeypatch.chdir(tmp_path)
+ (tmp_path / "llm_keys.key").write_text(json.dumps(keys), encoding="utf-8")
+ config = Config(load_env=False)
+
+ assert config.get_api_key("legacy") is None
+ assert caplog.records
+ assert "synthetic-secret" not in caplog.text
+
+ @pytest.mark.parametrize(
+ "keys,expected",
+ [
+ ({"legacy": "legacy-key"}, "legacy-key"),
+ ({"legacy": ""}, ""),
+ ({"legacy": None}, None),
+ ({}, None),
+ ],
+ )
+ def test_legacy_api_key_preserves_valid_values(
+ self, tmp_path, monkeypatch, caplog, keys, expected
+ ):
+ monkeypatch.chdir(tmp_path)
+ (tmp_path / "llm_keys.key").write_text(json.dumps(keys), encoding="utf-8")
+ config = Config(load_env=False)
+
+ assert config.get_api_key("legacy") == expected
+ assert not caplog.records
+
def test_load_real_configuration(self):
"""Test loading default configuration without external side effects."""
config = Config(load_env=False)
diff --git a/tests/test_core/test_data_loader.py b/tests/test_core/test_data_loader.py
index c578c31..322eea4 100644
--- a/tests/test_core/test_data_loader.py
+++ b/tests/test_core/test_data_loader.py
@@ -31,6 +31,15 @@ def test_load_json_not_found(self, temp_dir):
with pytest.raises(FileNotFoundError):
DataLoader.load_json(temp_dir / "nonexistent.json")
+ @pytest.mark.parametrize("content", ["[]", "null", "42", "true", '"text"'])
+ def test_load_json_rejects_non_object(self, tmp_path, content):
+ path = tmp_path / "input.json"
+ path.write_text(content, encoding="utf-8")
+
+ with pytest.raises(ValueError, match="JSON object") as error:
+ DataLoader.load_json(path)
+ assert str(path) in str(error.value)
+
def test_load_markdown(self, sample_markdown_file):
"""Test loading markdown file."""
content = DataLoader.load_markdown(sample_markdown_file)
@@ -78,3 +87,18 @@ def test_load_presenter_data(self, temp_dir):
assert "Test_Presenter" in presenters
assert "topics" in presenters["Test_Presenter"]
assert "works" in presenters["Test_Presenter"]
+
+
+@pytest.mark.parametrize("as_string", [False, True])
+def test_public_participant_loader_accepts_path_and_string(tmp_path, as_string):
+ from symposium.core import load_participant_data
+
+ csv_path = tmp_path / "participants.csv"
+ csv_path.write_text(
+ "share_publicly,name,background\nYes,Allowed,Research\nNo,Withheld,Private\n",
+ encoding="utf-8",
+ )
+ result = load_participant_data(str(csv_path) if as_string else csv_path)
+ assert set(result) == {"Allowed"}
+ assert result["Allowed"]["background"] == "Research"
+ assert result == DataLoader.load_participant_data(csv_path)
diff --git a/tests/test_generation/test_profiles.py b/tests/test_generation/test_profiles.py
index 1be2155..ea0d0a3 100644
--- a/tests/test_generation/test_profiles.py
+++ b/tests/test_generation/test_profiles.py
@@ -1,11 +1,15 @@
"""Tests for profile generation module."""
+import json
from unittest.mock import patch
import pandas as pd
import pytest
+from symposium.core.api import PaymentRequiredError
+from symposium.core.batch import BatchIncompleteError
from symposium.generation.profiles import ProfileGenerator
+from symposium.io.writers import ReportWriter
class TestProfileGenerator:
@@ -85,3 +89,81 @@ def test_generate_all_profiles_methods_only(self, generator, temp_dir, sample_pr
assert "profile" in results["Test_Researcher"]
assert "methods" not in results["Test_Researcher"]
mock_save.assert_called_once()
+
+ @pytest.mark.parametrize("report_type", ["research_profile", "research_methods"])
+ @pytest.mark.parametrize("format_name", ["markdown", "json"])
+ def test_batch_requires_every_selected_report_format(
+ self, generator, sample_presenter_data, tmp_path, monkeypatch, report_type, format_name
+ ):
+ presenters = {
+ name: {**sample_presenter_data, "name": name} for name in ("First", "Second", "Later")
+ }
+ monkeypatch.setattr(
+ generator.data_loader, "load_presenter_data", lambda *a, **k: presenters
+ )
+ method = f"save_{format_name}_report"
+ original = getattr(ReportWriter, method)
+
+ def save(content, filepath, *args, **kwargs):
+ if filepath.stem == f"Second_{report_type}":
+ raise OSError("Synthetic storage failure")
+ return original(content, filepath, *args, **kwargs)
+
+ monkeypatch.setattr(ReportWriter, method, save)
+ output = tmp_path / "reports"
+ with pytest.raises(BatchIncompleteError) as exc:
+ generator.generate_all_profiles(tmp_path, output, include_methods=True)
+ assert exc.value.requested == 3
+ assert set(exc.value.completed) == {"First", "Later"}
+ assert set(exc.value.failures) == {"Second"}
+ for name in ("First", "Later"):
+ for kind in ("research_profile", "research_methods"):
+ report = output / name / f"{name}_{kind}"
+ assert (
+ json.loads(report.with_suffix(".json").read_text())["content"]
+ == "Mock API response"
+ )
+ assert "Mock API response" in report.with_suffix(".md").read_text()
+ partial = output / "Second" / f"Second_{report_type}"
+ assert partial.with_suffix(".md").exists() is (format_name == "json")
+ assert not partial.with_suffix(".json").exists()
+ profile = output / "Second" / "Second_research_profile.json"
+ assert profile.exists() is (report_type == "research_methods")
+ if profile.exists():
+ assert json.loads(profile.read_text())["content"] == "Mock API response"
+
+ @pytest.mark.parametrize("include_methods", [False, True])
+ def test_payment_stops_after_preserving_complete_profile(
+ self, generator, sample_presenter_data, tmp_path, monkeypatch, include_methods
+ ):
+ presenters = {
+ name: {**sample_presenter_data, "name": name} for name in ("First", "Second", "Later")
+ }
+ monkeypatch.setattr(
+ generator.data_loader, "load_presenter_data", lambda *a, **k: presenters
+ )
+ responses = ["Persisted profile"]
+ if include_methods:
+ responses.append("Persisted methods")
+ responses.extend(
+ [PaymentRequiredError("Cannot generate without credits", "openrouter"), "Not requested"]
+ )
+ generator.api_client.get_response.side_effect = responses
+ output = tmp_path / "reports"
+ with pytest.raises(PaymentRequiredError):
+ generator.generate_all_profiles(tmp_path, output, include_methods=include_methods)
+ assert generator.api_client.get_response.call_count == (3 if include_methods else 2)
+ profile = output / "First" / "First_research_profile.json"
+ assert json.loads(profile.read_text())["content"] == "Persisted profile"
+ methods = output / "First" / "First_research_methods.json"
+ assert methods.exists() is include_methods
+ if include_methods:
+ assert json.loads(methods.read_text())["content"] == "Persisted methods"
+ assert not (output / "Second").exists()
+ assert not (output / "Later").exists()
+
+ def test_empty_batch_creates_no_reports(self, generator, tmp_path):
+ output = tmp_path / "reports"
+ assert generator.generate_all_profiles(tmp_path, output) == {}
+ assert not output.exists()
+ generator.api_client.get_response.assert_not_called()
diff --git a/tests/test_generation/test_projects.py b/tests/test_generation/test_projects.py
index 33f2d25..6d5fe63 100644
--- a/tests/test_generation/test_projects.py
+++ b/tests/test_generation/test_projects.py
@@ -1,10 +1,14 @@
"""Tests for project generation module."""
+import json
from unittest.mock import patch
import pytest
+from symposium.core.api import PaymentRequiredError
+from symposium.core.batch import BatchIncompleteError
from symposium.generation.projects import ProjectGenerator
+from symposium.io.writers import ReportWriter
class TestProjectGenerator:
@@ -128,3 +132,79 @@ def test_generate_all_projects(self, generator, temp_dir):
assert "Test_Participant" in results
assert results["Test_Participant"] == expected_response
mock_save.assert_called_once()
+
+ @pytest.mark.parametrize("format_name", ["markdown", "json"])
+ def test_batch_counts_only_persisted_proposals(
+ self, generator, tmp_path, monkeypatch, format_name
+ ):
+ participants = {
+ name: {"name": name, "profile": "Synthetic researcher"}
+ for name in ("First", "Second", "Later")
+ }
+ monkeypatch.setattr(
+ generator.data_loader, "load_participant_profiles", lambda *a, **k: participants
+ )
+ domain = tmp_path / "domain.md"
+ domain.write_text("Synthetic domain")
+ (tmp_path / "KarmaGAPGrants.md").write_text("Synthetic proposal questions")
+ method = f"save_{format_name}_report"
+ original = getattr(ReportWriter, method)
+
+ def save(content, filepath, *args, **kwargs):
+ if filepath.parent.name == "Second":
+ raise OSError("Synthetic storage failure")
+ return original(content, filepath, *args, **kwargs)
+
+ monkeypatch.setattr(ReportWriter, method, save)
+ output = tmp_path / "reports"
+ with pytest.raises(BatchIncompleteError) as exc:
+ generator.generate_all_projects(tmp_path, output, domain, catechisms_dir=tmp_path)
+ assert exc.value.requested == 3
+ assert set(exc.value.completed) == {"First", "Later"}
+ assert set(exc.value.failures) == {"Second"}
+ for name in ("First", "Later"):
+ report = output / name / f"{name}_project_proposal_KarmaGAP"
+ assert (
+ json.loads(report.with_suffix(".json").read_text())["content"]
+ == "Mock API response"
+ )
+ assert "Mock API response" in report.with_suffix(".md").read_text()
+ partial = output / "Second" / "Second_project_proposal_KarmaGAP"
+ assert partial.with_suffix(".md").exists() is (format_name == "json")
+ assert not partial.with_suffix(".json").exists()
+
+ def test_payment_stops_after_preserving_completed_proposal(
+ self, generator, tmp_path, monkeypatch
+ ):
+ participants = {
+ name: {"name": name, "profile": "Synthetic researcher"}
+ for name in ("First", "Second", "Later")
+ }
+ monkeypatch.setattr(
+ generator.data_loader, "load_participant_profiles", lambda *a, **k: participants
+ )
+ domain = tmp_path / "domain.md"
+ domain.write_text("Synthetic domain")
+ (tmp_path / "KarmaGAPGrants.md").write_text("Synthetic proposal questions")
+ generator.api_client.get_response.side_effect = [
+ "Persisted proposal",
+ PaymentRequiredError("Cannot generate without credits", "openrouter"),
+ "Must not be requested",
+ ]
+ output = tmp_path / "reports"
+ with pytest.raises(PaymentRequiredError):
+ generator.generate_all_projects(tmp_path, output, domain, catechisms_dir=tmp_path)
+ assert generator.api_client.get_response.call_count == 2
+ first = output / "First" / "First_project_proposal_KarmaGAP"
+ assert json.loads(first.with_suffix(".json").read_text())["content"] == "Persisted proposal"
+ assert "Persisted proposal" in first.with_suffix(".md").read_text()
+ assert not (output / "Second").exists()
+ assert not (output / "Later").exists()
+
+ def test_empty_batch_creates_no_proposals(self, generator, tmp_path):
+ domain = tmp_path / "domain.md"
+ domain.write_text("Synthetic domain")
+ output = tmp_path / "reports"
+ assert generator.generate_all_projects(tmp_path, output, domain) == {}
+ assert not output.exists()
+ generator.api_client.get_response.assert_not_called()
diff --git a/tests/test_io/test_readers.py b/tests/test_io/test_readers.py
index ebecefa..fadd4b9 100644
--- a/tests/test_io/test_readers.py
+++ b/tests/test_io/test_readers.py
@@ -23,6 +23,16 @@ def test_read_json(tmp_path):
assert ReportReader.read_json(p) == {"k": "v", "n": 1}
+@pytest.mark.parametrize("content", ["[]", "null", "42", "true", '"text"'])
+def test_read_json_rejects_non_object(tmp_path, content):
+ path = tmp_path / "input.json"
+ path.write_text(content, encoding="utf-8")
+
+ with pytest.raises(ValueError, match="JSON object") as error:
+ ReportReader.read_json(path)
+ assert str(path) in str(error.value)
+
+
def test_read_csv(tmp_path):
p = tmp_path / "a.csv"
pd.DataFrame({"a": [1, 2], "b": ["x", "y"]}).to_csv(p, index=False)
diff --git a/tests/test_organizing_publication.py b/tests/test_organizing_publication.py
index 56a604b..b163e05 100644
--- a/tests/test_organizing_publication.py
+++ b/tests/test_organizing_publication.py
@@ -408,6 +408,26 @@ def test_pdf_real_parse_public_text_links_and_metadata(inputs, tmp_path):
assert verify_public_tree(tmp_path / "public") == inputs[0]
+def test_pdf_page_without_indirect_reference_is_rejected(inputs, tmp_path):
+ import io
+
+ from pypdf import PdfWriter
+ from pypdf.generic import ArrayObject, DictionaryObject, NameObject
+
+ writer = PdfWriter()
+ page = writer.add_blank_page(width=612, height=792)
+ pages = writer.root_object["/Pages"]
+ pages[NameObject("/Kids")] = ArrayObject([DictionaryObject(page)])
+ output = io.BytesIO()
+ writer.write(output)
+ artifacts = tmp_path / "artifacts"
+ artifacts.mkdir()
+ (artifacts / "book.pdf").write_bytes(output.getvalue())
+ with pytest.raises(PublicationError, match="PDF page has no indirect reference"):
+ write_artifact_index(inputs[0], artifacts)
+ assert not (artifacts / "artifact_index.json").exists()
+
+
@pytest.mark.parametrize(
"fault",
[
@@ -548,3 +568,16 @@ def test_snapshot_capture_retains_explicit_utc_contract(inputs, tmp_path):
apply=True,
as_of="2026-10-26T01:30:01Z",
)
+
+
+@pytest.mark.parametrize("fault", ["missing", "null", "nontext"])
+def test_snapshot_capture_requires_string_timestamp_before_output(inputs, tmp_path, fault):
+ bundle, snapshot, ledger = inputs
+ if fault == "missing":
+ del snapshot["observed_at"]
+ else:
+ snapshot["observed_at"] = None if fault == "null" else b"2026-10-26T12:00:00Z"
+ output = tmp_path / "rejected-timestamp"
+ with pytest.raises(PublicationError, match="Expected explicit UTC timestamp"):
+ stage_public(bundle, snapshot, ledger, output, apply=True, as_of=NOW)
+ assert not output.exists()
diff --git a/typings/adjustText/__init__.pyi b/typings/adjustText/__init__.pyi
new file mode 100644
index 0000000..650cb23
--- /dev/null
+++ b/typings/adjustText/__init__.pyi
@@ -0,0 +1,14 @@
+"""Consumed adjustText 1.4.0 interface; guarded by scripts/check_types.py."""
+
+from matplotlib.artist import Artist
+from matplotlib.axes import Axes
+from matplotlib.text import Text
+
+def adjust_text(
+ texts: list[Text],
+ *,
+ ax: Axes | None = ...,
+ arrowprops: dict[str, object] | None = ...,
+ time_lim: float | None = ...,
+ iter_lim: int | None = ...,
+) -> tuple[list[Text], list[Artist]] | None: ...
diff --git a/typings/bindings.json b/typings/bindings.json
new file mode 100644
index 0000000..8c31153
--- /dev/null
+++ b/typings/bindings.json
@@ -0,0 +1,76 @@
+{
+ "versions": {
+ "mypy": "2.4.1",
+ "adjustText": "1.4.0",
+ "wordcloud": "1.9.6",
+ "scikit-learn": "1.9.1",
+ "scikit-learn-stubs": "0.0.3",
+ "scipy": "1.18.1",
+ "scipy-stubs": "1.18.1.1",
+ "networkx": "3.7",
+ "types-networkx": "3.6.1.20261108"
+ },
+ "projections": [
+ {
+ "distribution": "scikit-learn-stubs",
+ "path": "sklearn-stubs/feature_extraction/text.pyi",
+ "sha256": "402d47bae27cad1b8c944213b982d7b85bed47dfe48db38a8d740db96adf3327",
+ "corrections": [
+ {
+ "old": ") -> ndarray | spmatrix: ...",
+ "new": ") -> sp.csr_array | sp.csr_matrix: ...",
+ "count": 1
+ },
+ {
+ "old": "def transform(self, raw_documents: list[str] | ndarray | Iterable) -> spmatrix: ...",
+ "new": "def transform(self, raw_documents: list[str] | ndarray | Iterable) -> sp.csr_array | sp.csr_matrix: ...",
+ "count": 2
+ },
+ {
+ "old": "def transform(self, X: MatrixLike, copy: bool = True) -> spmatrix: ...",
+ "new": "def transform(self, X: MatrixLike, copy: bool = True) -> sp.csr_array | sp.csr_matrix: ...",
+ "count": 1
+ },
+ {
+ "old": "def fit_transform(self, raw_documents: list[str] | ndarray | Iterable, y: None | ndarray = None) -> spmatrix: ...",
+ "new": "def fit_transform(self, raw_documents: list[str] | ndarray | Iterable, y: None | ndarray = None) -> sp.csr_array | sp.csr_matrix: ...",
+ "count": 1
+ }
+ ]
+ },
+ {
+ "distribution": "scikit-learn-stubs",
+ "path": "sklearn-stubs/_typing.pyi",
+ "sha256": "360afaed47bd08d88a7d3685a0033f10bb00e643e0e7bc5136b35669be656dde",
+ "corrections": [
+ {
+ "old": "from scipy.sparse import spmatrix",
+ "new": "from scipy.sparse import sparray, spmatrix",
+ "count": 1
+ },
+ {
+ "old": "MatrixLike: typing_extensions.TypeAlias = np.ndarray | pd.DataFrame | spmatrix",
+ "new": "MatrixLike: typing_extensions.TypeAlias = np.ndarray | pd.DataFrame | sparray | spmatrix",
+ "count": 1
+ }
+ ]
+ },
+ {
+ "distribution": "types-networkx",
+ "path": "networkx-stubs/algorithms/community/quality.pyi",
+ "sha256": "68483c610172a90e90fad8555a42e076021975e3b9257406f491f9008e411fae",
+ "corrections": [
+ {
+ "old": "from collections.abc import Iterable",
+ "new": "from collections.abc import Iterable, Set as AbstractSet",
+ "count": 1
+ },
+ {
+ "old": "communities: Iterable[set[Incomplete]]",
+ "new": "communities: Iterable[AbstractSet[Incomplete]]",
+ "count": 1
+ }
+ ]
+ }
+ ]
+}
diff --git a/typings/wordcloud/__init__.pyi b/typings/wordcloud/__init__.pyi
new file mode 100644
index 0000000..860ea78
--- /dev/null
+++ b/typings/wordcloud/__init__.pyi
@@ -0,0 +1,29 @@
+"""Consumed wordcloud 1.9.6 interface; guarded by scripts/check_types.py."""
+
+from typing import Literal, Self
+
+import numpy as np
+from numpy.typing import NDArray
+
+class WordCloud:
+ def __init__(
+ self,
+ *,
+ width: int = ...,
+ height: int = ...,
+ background_color: str | None = ...,
+ max_words: int = ...,
+ colormap: str | None = ...,
+ contour_width: float = ...,
+ contour_color: str = ...,
+ min_font_size: int = ...,
+ max_font_size: int | None = ...,
+ font_step: int = ...,
+ prefer_horizontal: float = ...,
+ relative_scaling: float | Literal["auto"] = ...,
+ normalize_plurals: bool = ...,
+ stopwords: set[str] | None = ...,
+ ) -> None: ...
+ def generate(self, text: str) -> Self: ...
+ def to_array(self, copy: bool | None = ...) -> NDArray[np.uint8]: ...
+ def __array__(self, copy: bool | None = ...) -> NDArray[np.uint8]: ...