@researai/deepscientist 1.5.17 → 1.6.0

package/src/skills/science/references/packages/xtb.md

@@ -0,0 +1,88 @@
+# xTB Extended Tight-Binding Quantum Chemistry
+
+## Catalog
+
+- Package id: `xtb`
+- Domains: `quantum_chemistry`, `computational_chemistry`
+- Tags: `quantum-chemistry`, `semiempirical`, `tight-binding`, `molecular-modeling`, `computational-chemistry`
+- Knowledge URL: https://github.com/skilled-scipkg/xtb
+- Source archive URL: https://github.com/skilled-scipkg/xtb/archive/refs/heads/main.zip
+- Upstream project URL: https://github.com/grimme-lab/xtb
+- Homepage: https://xtb-docs.readthedocs.io/
+- Catalog source: FermiLink skilled-scipkg, commit `93f089a333a43089fb1a08a73c37d05fd6683214`
+
+## When To Consider
+
+xTB is a semiempirical extended tight-binding quantum chemistry package for fast molecular energies, structures, frequencies, and conformational analyses across large systems with broad element coverage.
+
+## DeepScientist Runtime Rule
+
+This card is package knowledge and routing context only. It does not mean the
+solver, Python module, CLI binary, compiled backend, license server, dataset, or
+HPC module is installed in the active environment. Before computed work, use
+`bash_exec(...)` to perform an import, executable, version, and smoke-test check
+appropriate for `xtb`.
+
+## Package Check
+
+For Python-facing environments, start with an import/version check and then a
+minimal package-specific smoke test:
+
+```bash
+python - <<'PY'
+import importlib, json, pathlib
+package_id = 'xtb'
+result = {"package_id": package_id, "import": "failed", "version": None, "smoke": "not_run"}
+try:
+    module = importlib.import_module(package_id.replace('-', '_').split('_jl')[0])
+    result["import"] = "passed"
+    result["version"] = getattr(module, "__version__", None)
+except Exception as exc:
+    result["error"] = repr(exc)
+pathlib.Path("validation/environment").mkdir(parents=True, exist_ok=True)
+pathlib.Path(f"validation/environment/{package_id}_doctor.json").write_text(json.dumps(result, indent=2), encoding="utf-8")
+PY
+```
+
+Record the result with `artifact.science(...)` as `science.package_check`. Use
+`status="passed"` only when the environment can run at least a minimal smoke
+path. Use `status="failed"` or `status="blocked"` when the check explains why
+execution cannot proceed.
+
+Generated import or executable names are starting points. If `xtb` uses
+a different Python module, CLI binary, environment module, container, or wrapper
+script, adjust the check before concluding the solver is unavailable.
+
+## Expected Science Nodes
+
+- `science.package_check` for import/executable/version/smoke-test evidence
+- `science.computational_run` for solver execution, simulation, fitting, or numerical computation
+- `science.dataset_analysis` when the task primarily analyzes existing data
+- `science.parameter_sweep` when varying parameters, inputs, models, or solver settings
+- `science.validation_result` for convergence, units, schema, controls, or correctness checks
+- `science.claim` only after evidence paths or related nodes support the claim
+
+## Evidence Path Conventions
+
+- `simulations/inputs/` for generated or selected solver inputs
+- `simulations/logs/` for stdout, stderr, scheduler logs, or solver logs
+- `simulations/outputs/` for structured run outputs
+- `analyses/scripts/`, `analyses/logs/`, and `analyses/outputs/` for dataset analysis
+- `validation/environment/` for package checks
+- `validation/runs/` for convergence, unit, schema, or correctness sidecars
+- `figures/` for derived visualizations
+
+## Validation Checklist
+
+- Record package version, executable path, backend, module state, or container image when relevant.
+- Preserve input files and parameters that define the scientific state.
+- Capture units, coordinate conventions, timestep/mesh/basis/model settings, seeds, and convergence criteria when applicable.
+- Validate output schema and important physical or statistical invariants before recording a computed claim.
+- Link claims to run, analysis, sweep, and validation nodes rather than relying on prose.
+
+## Common Pitfalls
+
+- Do not treat the package card or knowledge URL as runtime availability.
+- Do not weaken solver tolerances, physical models, dataset filters, or convergence criteria to make a run pass unless the change is explicitly part of the scientific question.
+- Do not call a value `computed` unless the corresponding run or analysis happened in the current quest and evidence paths are recorded.
+- Do not copy package knowledge-base material into the quest without preserving its source and license context.

package/src/skills/science/references/packages/yt.md

@@ -0,0 +1,73 @@
+# yt Volumetric Simulation Analysis
+
+## Catalog
+
+- Package id: `yt`
+- Domains: `computational_science`
+- Tags: `scientific-visualization`, `simulation-analysis`, `volumetric-data`, `amr`, `computational-physics`
+- Knowledge URL: https://github.com/skilled-scipkg/yt
+- Source archive URL: https://github.com/skilled-scipkg/yt/archive/refs/heads/main.zip
+- Upstream project URL: https://github.com/yt-project/yt
+- Homepage: http://yt-project.org
+- Catalog source: FermiLink skilled-scipkg, commit `93f089a333a43089fb1a08a73c37d05fd6683214`
+
+## When To Consider
+
+yt is a Python library for physically meaningful analysis and visualization of volumetric simulation data across structured and unstructured meshes, particles, and adaptive mesh refinement datasets.
+
+## DeepScientist Runtime Rule
+
+This card is package knowledge and routing context only. It does not mean the
+solver, Python module, CLI binary, compiled backend, license server, dataset, or
+HPC module is installed in the active environment. Before computed work, use
+`bash_exec(...)` to perform an import, executable, version, and smoke-test check
+appropriate for `yt`.
+
+## Package Check
+
+Use a package-specific import, executable, or module check and save the result
+under `validation/environment/yt_doctor.json` before treating the
+runtime as usable.
+
+Record the result with `artifact.science(...)` as `science.package_check`. Use
+`status="passed"` only when the environment can run at least a minimal smoke
+path. Use `status="failed"` or `status="blocked"` when the check explains why
+execution cannot proceed.
+
+Generated import or executable names are starting points. If `yt` uses
+a different Python module, CLI binary, environment module, container, or wrapper
+script, adjust the check before concluding the solver is unavailable.
+
+## Expected Science Nodes
+
+- `science.package_check` for import/executable/version/smoke-test evidence
+- `science.computational_run` for solver execution, simulation, fitting, or numerical computation
+- `science.dataset_analysis` when the task primarily analyzes existing data
+- `science.parameter_sweep` when varying parameters, inputs, models, or solver settings
+- `science.validation_result` for convergence, units, schema, controls, or correctness checks
+- `science.claim` only after evidence paths or related nodes support the claim
+
+## Evidence Path Conventions
+
+- `simulations/inputs/` for generated or selected solver inputs
+- `simulations/logs/` for stdout, stderr, scheduler logs, or solver logs
+- `simulations/outputs/` for structured run outputs
+- `analyses/scripts/`, `analyses/logs/`, and `analyses/outputs/` for dataset analysis
+- `validation/environment/` for package checks
+- `validation/runs/` for convergence, unit, schema, or correctness sidecars
+- `figures/` for derived visualizations
+
+## Validation Checklist
+
+- Record package version, executable path, backend, module state, or container image when relevant.
+- Preserve input files and parameters that define the scientific state.
+- Capture units, coordinate conventions, timestep/mesh/basis/model settings, seeds, and convergence criteria when applicable.
+- Validate output schema and important physical or statistical invariants before recording a computed claim.
+- Link claims to run, analysis, sweep, and validation nodes rather than relying on prose.
+
+## Common Pitfalls
+
+- Do not treat the package card or knowledge URL as runtime availability.
+- Do not weaken solver tolerances, physical models, dataset filters, or convergence criteria to make a run pass unless the change is explicitly part of the scientific question.
+- Do not call a value `computed` unless the corresponding run or analysis happened in the current quest and evidence paths are recorded.
+- Do not copy package knowledge-base material into the quest without preserving its source and license context.

package/src/skills/science/references/science-task-brief-template.md

@@ -0,0 +1,71 @@
+# Science Task Brief Template
+
+SetupAgent may use this shape as startup context for natural-science tasks.
+It is inspired by FermiLink's `goal.md` discipline, but DeepScientist should
+not require the main agent to materialize a `goal.md` file.
+
+```markdown
+# Science Task Brief: <title>
+
+## Objective
+What scientific or engineering result should be produced.
+
+## What To Compute Or Analyze
+- Concrete calculations, simulations, dataset analyses, reproductions, or
+  optimizations.
+
+## Setup And Constraints
+- Physical parameters, package preferences, datasets, hardware, SSH/HPC,
+  privacy, units, budget, and runtime constraints.
+
+## Success Criteria
+- Quantitative convergence, correctness, reproducibility, comparison, or
+  validation checks.
+
+## Deliverables
+- Expected scripts, logs, outputs, figures, tables, reports, or data files.
+
+## Evidence Recording Plan
+- Expected `science.package_check`, `science.computational_run`,
+  `science.dataset_analysis`, `science.parameter_sweep`,
+  `science.validation_result`, and `science.claim` nodes.
+```
+
+## Scientific Code Optimization Brief
+
+Use this format when the task is performance optimization of scientific code:
+
+```markdown
+# Optimization Goal
+
+## Package
+<package_id or repo name>
+
+## Language
+<python|c|cpp|fortran|mixed>
+
+## Target
+Specific hot path and scientific semantics that must remain unchanged.
+
+## Editable Scope
+- explicit/path/to/file.py
+
+## Performance Metric
+Primary runtime or throughput metric and aggregation rule.
+
+## Correctness Constraints
+- numeric scientific invariants and tolerances
+- forbidden shortcuts or weakened solver settings
+
+## Representative Workloads
+- train-case: meaningful workload
+- test-case: held-out workload
+
+## Build
+```bash
+deterministic build or install commands
+```
+
+## Notes
+- deterministic thread, seed, MPI, launcher, and input-file constraints
+```