Research project demonstrating optimization algorithms with automated figure generation and publication-quality output. Exemplar roster: projects/AGENTS.md.
Use this template for code-driven computational research: algorithms in
src/, numerical experiments with deterministic seeds, automated
publication-quality figures, and a manuscript that reports the computed
results. It demonstrates the thin-orchestrator pattern
(scripts coordinate; src/ implements; tests enforce ≥90% coverage with no
mocks). If your project is primarily prose review, layout, or book-length
structure, see template_prose_project,
template_newspaper, or
template_textbook instead.
The publishing metadata and per-platform status below are compiled from
manuscript/config.yaml by infrastructure.publishing.status_report — do not
hand-edit between the markers; update the config and regenerate (see the legend).
Convergence Analysis of Gradient Descent Optimization · intended v3.0.0 (unreleased) · MIT · Daniel Ari Friedman
Intended release: v3.0.0 — unreleased. Last published release: v2.5.2. Recorded publication links refer to that release.
Concept DOI: 10.5281/zenodo.20417136 | Last published version DOI: 10.5281/zenodo.20931934 | Repository: docxology/template_code_project
Publishing surface — 20 platforms, 0 published for the intended release:
| Platform | Tier | Status | Reference | Credentials |
|---|---|---|---|---|
| zenodo | first-class | 📚 historical reference | 10.5281/zenodo.20417136 | ZENODO_API_TOKEN |
| github | first-class | 📚 historical reference | docxology/template_code_project | GITHUB_TOKEN |
| arxiv | first-class | ⚪ available | — | — |
| pypi | first-class | 📚 historical reference | https://test.pypi.org/project/template-code-project/2.5.2/ | PYPI_TOKEN, TESTPYPI_TOKEN |
| ipfs_pinata | first-class | 📚 historical reference | https://gateway.pinata.cloud/ipfs/QmSVZF1MisqWeX1C7vFUhcwCkYvZXBuq5TS9MzLFNJJykS | PINATA_JWT |
| ipfs_web3storage | first-class | ⚪ available | — | WEB3_STORAGE_TOKEN |
| software_heritage | first-class | 📚 historical reference | https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/docxology/template_code_project | — |
| github_pages | first-class | 📚 historical reference | https://docxology.github.io/template_code_project/ | GITHUB_TOKEN |
| cloudflare_pages | first-class | ⚪ available | — | CLOUDFLARE_API_TOKEN |
| netlify | first-class | 📚 historical reference | https://6a4440a789b44ad53f3af09b--tranquil-kleicha-0c9203.netlify.app | NETLIFY_AUTH_TOKEN |
| huggingface_hub | first-class | 📚 historical reference | https://huggingface.co/datasets/ActiveInference/template_code_project | HUGGINGFACE_TOKEN, HF_TOKEN |
| osf | first-class | 📚 historical reference | https://osf.io/mcv8j/ | OSF_TOKEN |
| amazon_kdp | documented | 🟡 planned | — | AMAZON_KDP_EMAIL, AMAZON_KDP_PASSWORD |
| google_play_books | documented | 🟡 planned | — | GOOGLE_PLAY_BOOKS_SERVICE_ACCOUNT_JSON |
| gumroad | documented | 🟡 planned | — | GUMROAD_ACCESS_TOKEN |
| leanpub | documented | 🟡 planned | — | LEANPUB_API_KEY |
| lulu | documented | 🟡 planned | — | LULU_CLIENT_KEY, LULU_CLIENT_SECRET |
| draft2digital | documented | 🟡 planned | — | DRAFT2DIGITAL_API_TOKEN |
| stripe | documented | 🟡 planned | — | STRIPE_SECRET_KEY, STRIPE_PUBLISHABLE_KEY |
| ingramspark | documented | 🟡 planned | — | INGRAMSPARK_CLIENT_ID, INGRAMSPARK_CLIENT_SECRET |
Keywords: optimization algorithms, gradient descent, convergence analysis, numerical methods, mathematical programming, reproducible research, infrastructure automation.
Status legend: ✅ published (durable identifier recorded in config.yaml) · 🔵 reserved (identifier reserved but not yet registered by final publication) · 📚 historical reference (last published release; not intended-version publication evidence) · ⚪ available (adapter implemented and locally verifiable) · 🟡 planned. This block is generated — edit manuscript/config.yaml, then regenerate with uv run python -m infrastructure.publishing.status_report --project <path> --write.
The 3 platforms still shown ⚪ available are not automatable to "published" with
current tooling/credentials, not an oversight: arXiv has no submission API
in this codebase (infrastructure.publishing.arxiv only prepares a local
tarball — a human must upload it via arxiv.org and the resulting arxiv URL
would then be added to publication.published_artifacts); Cloudflare
Pages needs a CLOUDFLARE_ACCOUNT_ID the configured API token cannot
auto-discover; IPFS (Web3.Storage) has no WEB3_STORAGE_TOKEN configured.
- Canonical renderer: docxology/template with
--project templates/template_code_project - Tracked outputs:
output/in this project andoutput/templates/template_code_project/in the monorepo; public output files above 50 MB stay out of git.
To regenerate this exemplar from the public monorepo:
git clone https://github.com/docxology/template
cd template
uv sync
./run.sh --project templates/template_code_project --pipeline --mode core
uv run python scripts/pipeline/stage_04_validate.py --project templates/template_code_project
uv run python scripts/pipeline/stage_05_copy.py --project templates/template_code_projectStandalone repositories are publication mirrors for source, DOI metadata, and tracked rendered artifacts. Use the monorepo above when you need the full shared infrastructure, pipeline stages, or cross-template validation.
# Run the analysis pipeline
uv run python projects/templates/template_code_project/scripts/optimization_analysis.py
# Run tests
uv run pytest projects/templates/template_code_project/tests/ -v
# View final deliverables (after scripts/pipeline/stage_05_copy.py)
ls -la output/templates/template_code_project/Test/coverage gate (authoritative per-project command). Exit code 0 alone is not proof — confirm tests collected > 0 and coverage ≥ 90%:
uv run pytest projects/templates/template_code_project/tests/ \
--cov=projects/templates/template_code_project/src --cov-fail-under=90
# live baseline: docs/_generated/COUNTS.mdCombined-PDF rendering & Mermaid. This project's convention is
Mermaid-for-all-diagrams. If a manuscript section embeds a mermaid
block, the combined PDF is built with mmdc, which needs a pinned
chrome-headless-shell (CI provisions it; a fresh clone does not):
npm ci
npx --no-install puppeteer browsers install chrome-headless-shell
export PATH="$PWD/node_modules/.bin:$PATH"Without it the PDF Rendering stage fails while slides still render — see
docs/troubleshooting.md.
Full end-to-end: uv run python scripts/runner/execute_pipeline.py --project templates/template_code_project --mode core.
Run uv sync at the repository root; that environment is what CI and ./run.sh use. pyproject.toml in this directory configures pytest/coverage for projects/templates/template_code_project/tests/ and records the same scientific stack for isolated runs. Root pyproject.toml has [tool.uv.workspace] with members = [], so this folder is not installed as a separate workspace package.
This exemplar includes two declarative overlays for advisory research controls:
domain_profile.yamldeclares the code-research domain, expected outputs, review gates, source policy, artifact expectations, and benchmark rubric weights.experiment_plan.yamldeclares the deterministic gradient-descent conditions, primary metric direction, expected figures and tables, baseline, and ablation condition.data/claim_ledger.yamlregisters manuscript numeric claims that are intentionally sourced from project code, captions, or generated artifacts rather than{{TOKEN}}variables.
These files are validation and benchmark inputs only. They do not fork project trees, mutate prompts, or run autonomous experiment agents.
The genuinely transferable lesson is not gradient descent. It is
reproducibility-by-construction: every numeric in the manuscript prose
is a {{TOKEN}} registered in one Python function
(src/template_code_project/core/manuscript_variables.py::generate_variables) and cross-checked by
one test (tests/core/test_manuscript_variables.py::test_all_manuscript_tokens_are_generated),
which fails CI on any token used in prose that the generator does not emit.
The deliverable PDF is therefore proof that the repo's invariants held
during build: configuration drift, deleted result, or out-of-sync narrative
cannot reach a green PDF without the gate flipping red first. A forker who
internalizes "every prose number is a token, every token is a single Python
function, every drift is a CI failure" gets that discipline for free —
regardless of whether their domain is optimization.
- Gradient descent optimization with convergence analysis
- Automated figure generation (convergence plots, stability analysis, performance benchmarks)
- Scientific validation (numerical stability assessment, performance benchmarking)
- Comprehensive reporting (HTML dashboard with analysis metrics)
- Performance monitoring (resource usage tracking with progress indicators)
- Data export (optimization results, analysis reports, performance metrics)
- Manuscript integration (figure registration and cross-referencing)
uv run python projects/templates/template_code_project/scripts/optimization_analysis.pyGenerates convergence plots, performs scientific validation, and saves all results.
uv run python projects/templates/template_code_project/scripts/build_dashboard.pyBuilds the HTML analysis dashboard from the outputs produced above (a separate
step — optimization_analysis.py does not build the dashboard itself; see
src/AGENTS.md for the module split).
uv run pytest projects/templates/template_code_project/tests/ -vTests optimization algorithms and numerical accuracy.
open projects/templates/template_code_project/output/figures/convergence_plot.png
cat projects/templates/template_code_project/output/data/optimization_results.csvgraph TD
A[scripts/optimization_analysis.py] --> B[src/template_code_project/analysis/]
B --> C[src/template_code_project/core/optimizer.py]
B --> D[Scientific Analysis]
B --> E[Generate Figures]
B --> F[Export Data]
B --> G[Create Dashboard]
AA[scripts/generate_api_docs.py] --> AB[API Documentation]
AA --> AC[Code Quality Report]
C --> H[Gradient Descent]
C --> I[Quadratic Functions]
C --> J[Convergence Analysis]
D --> K[Stability Assessment]
D --> L[Performance Benchmarking]
D --> M[Progress Monitoring]
E --> N[Convergence Plots]
E --> O[Stability Visualizations]
E --> P[Benchmark Charts]
G --> Q[HTML Dashboard]
G --> R[Analysis Reports]
F --> S[CSV Results]
F --> T[JSON Reports]
Shared instructions live in root AGENTS.md and
.agents/AGENTS.md. The following development
standards apply:
- Testing:
src/coverage is gated at 90% (suite contract indocs/testing_philosophy.md) - Documentation: AGENTS.md + README.md in each directory
- Type Safety: Full type hints on all public APIs
- Code Quality: Ruff format/check (CI parity), descriptive naming, proper imports
- Error Handling: Context preservation, informative messages
- Logging: Unified logging system throughout
When editing manuscript markdown:
manuscript/SYNTAX.md— citation, equation, figure, table, and section conventions specific to this project (label registries for all 6 figures and 8 equations).../../docs/guides/manuscript-semantics.md— repository-wide manuscript semantics.manuscript/AGENTS.md—{{TOKEN}}substitution protocol and section-modification workflow.
See AGENTS.md for technical documentation.
- Forward backlog:
TODO.md. - Copy-and-customize config:
manuscript/config.yaml.example. - Project validation:
uv run pytest projects/templates/template_code_project/tests/ --cov=projects/templates/template_code_project/src --cov-fail-under=90. - Repo drift validation:
uv run python scripts/audit/check_template_drift.py --strict.
Default CI builds this template's wheel and runs focused behavioral tests. Further hardening can add optimization stability across seeds and larger convergence sweeps. The complete suites and native/provider acceptance remain opt-in; see functional CI and hardening for commands and the evidence each lane establishes.