scientific-computing-system 1.6.2__py3-none-any.whl

cds/cli/_parser.py

@@ -0,0 +1,156 @@
+"""Argument-parser construction for the ``cds`` CLI."""
+
+from __future__ import annotations
+
+import argparse
+
+from cds.cli._handlers import (
+    _cmd_benchmark,
+    _cmd_calc,
+    _cmd_constants,
+    _cmd_dashboard,
+    _cmd_hypothesis,
+    _cmd_info,
+    _cmd_integrate,
+    _cmd_modules,
+    _cmd_plot,
+    _cmd_prompt,
+    _cmd_sample,
+    _cmd_stats,
+    _cmd_version,
+)
+
+_DOMAIN_CHOICES = ["physics", "cosmology", "mathematics", "biology", "chemistry", "general_science"]
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Construct the top-level ``cds`` argument parser and its subcommands."""
+    parser = argparse.ArgumentParser(
+        prog="cds",
+        description="Cognitive Discovery System — computational science platform.",
+    )
+    parser.add_argument("--version", "-v", action="store_true", help="Show System version and exit")
+
+    sub = parser.add_subparsers(dest="command")
+
+    p_version = sub.add_parser("version", help="Show System version.")
+    p_version.set_defaults(func=_cmd_version)
+
+    p_hyp = sub.add_parser(
+        "hypothesis", help="Generate scientific hypotheses for a research question."
+    )
+    p_hyp.add_argument("question", help="The core research question or problem")
+    p_hyp.add_argument(
+        "--domain",
+        "-d",
+        default="general_science",
+        choices=_DOMAIN_CHOICES,
+        help="Scientific domain focus",
+    )
+    p_hyp.add_argument("--num", "-n", type=int, default=3, help="Number of hypotheses to propose")
+    p_hyp.add_argument("--output", "-o", help="Save results as JSON")
+    p_hyp.add_argument("--show-prompt", action="store_true", help="Print the exact prompt template")
+    p_hyp.add_argument("--dry-run", action="store_true", help="Do not run generation logic")
+    p_hyp.set_defaults(func=_cmd_hypothesis)
+
+    p_prompt = sub.add_parser("prompt", help="Print a ready-to-use prompt for a custom generator.")
+    p_prompt.add_argument("question", help="Research question")
+    p_prompt.add_argument(
+        "--domain",
+        "-d",
+        default="general_science",
+        choices=_DOMAIN_CHOICES,
+        help="Scientific domain focus",
+    )
+    p_prompt.add_argument(
+        "--num", "-n", type=int, default=3, help="Number of hypotheses to propose"
+    )
+    p_prompt.set_defaults(func=_cmd_prompt)
+
+    p_info = sub.add_parser("info", help="Show System info, module status, and System health.")
+    p_info.set_defaults(func=_cmd_info)
+
+    sub.add_parser("dashboard", help="Launch the interactive System dashboard.").set_defaults(
+        func=_cmd_dashboard
+    )
+    sub.add_parser("benchmark", help="Run built-in benchmarks to verify performance.").set_defaults(
+        func=_cmd_benchmark
+    )
+    sub.add_parser("constants", help="List available physical constants.").set_defaults(
+        func=_cmd_constants
+    )
+
+    p_plot = sub.add_parser(
+        "plot",
+        help="Plot a series of numbers (ASCII terminal, or PNG with --file if cds[plot] installed).",
+    )
+    p_plot.add_argument("values", help="Comma-separated list of numbers (e.g. '1,5,3,8')")
+    p_plot.add_argument("--title", "-t", default="CLI Plot", help="Title of the plot")
+    p_plot.add_argument(
+        "--file",
+        "-f",
+        default=None,
+        help="Save a PNG via optional matplotlib (requires cds[plot]); omit for ASCII",
+    )
+    p_plot.add_argument(
+        "--kind",
+        "-k",
+        default="series",
+        choices=["series", "hist", "acf"],
+        help="Chart type when using --file (default: series)",
+    )
+    p_plot.set_defaults(func=_cmd_plot)
+
+    p_calc = sub.add_parser("calc", help="Quick physics calculations.")
+    p_calc.add_argument("formula", help="Formula: ke, gravity, wave, gas")
+    p_calc.set_defaults(func=_cmd_calc)
+
+    p_stats = sub.add_parser(
+        "stats", help="Descriptive statistics for a comma-separated number list."
+    )
+    p_stats.add_argument("values", help="Comma-separated numbers (e.g. '1,2,3,4')")
+    p_stats.set_defaults(func=_cmd_stats)
+
+    p_sample = sub.add_parser("sample", help="Draw samples from a probability distribution.")
+    p_sample.add_argument(
+        "dist",
+        choices=["uniform", "gaussian", "exponential", "poisson"],
+        help="Distribution name",
+    )
+    p_sample.add_argument("-n", type=int, default=5, help="Number of samples (default 5)")
+    p_sample.add_argument("--seed", type=int, default=None, help="RNG seed")
+    p_sample.add_argument("--a", type=float, default=0.0, help="uniform lower bound")
+    p_sample.add_argument("--b", type=float, default=1.0, help="uniform upper bound")
+    p_sample.add_argument("--mu", type=float, default=0.0, help="gaussian mean")
+    p_sample.add_argument("--sigma", type=float, default=1.0, help="gaussian stdev")
+    p_sample.add_argument("--lam", type=float, default=1.0, help="rate λ for exponential/poisson")
+    p_sample.set_defaults(func=_cmd_sample)
+
+    p_int = sub.add_parser(
+        "integrate", help="Numerically integrate a built-in function over [a, b]."
+    )
+    p_int.add_argument(
+        "integrand",
+        choices=["sin", "cos", "exp", "x2", "unit"],
+        help="Integrand name",
+    )
+    p_int.add_argument("--a", type=float, default=0.0, help="Lower limit (default 0)")
+    p_int.add_argument("--b", type=float, default=1.0, help="Upper limit (default 1)")
+    p_int.add_argument("-n", type=int, default=1000, help="Number of panels (default 1000)")
+    p_int.add_argument(
+        "--method",
+        choices=["simpson", "trap"],
+        default="simpson",
+        help="Quadrature rule (default simpson)",
+    )
+    p_int.set_defaults(func=_cmd_integrate)
+
+    sub.add_parser(
+        "modules", help="List all scientific modules available in the System."
+    ).set_defaults(func=_cmd_modules)
+
+    return parser
+
+
+# Historical private name kept as an alias for backwards compatibility.
+_build_parser = build_parser

cds/cli/_style.py

@@ -0,0 +1,117 @@
+"""ANSI colour helpers and ASCII table rendering for the CDS CLI."""
+
+from __future__ import annotations
+
+import sys
+
+_RESET = "\033[0m"
+_STYLES: dict[str, str] = {
+    "bold": "\033[1m",
+    "dim": "\033[2m",
+    "italic": "\033[3m",
+    "red": "\033[31m",
+    "green": "\033[32m",
+    "yellow": "\033[33m",
+    "blue": "\033[34m",
+    "magenta": "\033[35m",
+    "cyan": "\033[36m",
+    "bold green": "\033[1;32m",
+    "bold blue": "\033[1;34m",
+    "bold cyan": "\033[1;36m",
+    "bold magenta": "\033[1;35m",
+    "bold red": "\033[1;31m",
+    "bold yellow": "\033[1;33m",
+}
+
+
+def _supports_color() -> bool:
+    """Return True when stdout looks like an interactive colour terminal."""
+    return sys.stdout.isatty()
+
+
+def _wrap(style: str, text: str) -> str:
+    """Wrap ``text`` in the ANSI codes for ``style`` if stdout is a TTY."""
+    if not _supports_color():
+        return text
+    code = _STYLES.get(style, "")
+    if not code:
+        return text
+    return f"{code}{text}{_RESET}"
+
+
+def _print(*args: object) -> None:
+    """Print helper routed through stdout (so tests can capture via capsys)."""
+    print(*args)
+
+
+def _render(markup: str) -> str:
+    """Render rich-style ``[style]...[/]`` markup into ANSI-coloured text.
+
+    Only the tag shapes actually used by this CLI are supported:
+    ``[bold]``, ``[italic]``, ``[dim]``, ``[red]``, ``[green]``, ``[yellow]``,
+    ``[blue]``, ``[cyan]``, ``[magenta]`` and a few combined ``[bold green]``
+    variants. Unknown tags are stripped to their inner text. Nesting is not
+    supported (the CLI never nests them).
+    """
+    out: list[str] = []
+    i = 0
+    n = len(markup)
+    while i < n:
+        open_idx = markup.find("[", i)
+        if open_idx == -1:
+            out.append(markup[i:])
+            break
+        out.append(markup[i:open_idx])
+        close_idx = markup.find("]", open_idx)
+        if close_idx == -1:
+            out.append(markup[open_idx:])
+            break
+        tag = markup[open_idx + 1 : close_idx]
+        # Closing tag [/] ends the current styled run.
+        if tag.startswith("/"):
+            out.append(_RESET if _supports_color() else "")
+            i = close_idx + 1
+            continue
+        # Combined forms like "bold green" are looked up directly.
+        code = _STYLES.get(tag)
+        if code is None and " " in tag:
+            # ``[bold green]`` style — already in the table; fall back to first word.
+            code = _STYLES.get(tag.split()[0], "")
+        out.append(code if (_supports_color() and code is not None) else "")
+        i = close_idx + 1
+    return "".join(out)
+
+
+def _format_table(title: str, headers: list[str], rows: list[list[str]]) -> str:
+    """Render ``headers``/``rows`` as a bordered ASCII table with a title.
+
+    A tiny reimplementation of the ``rich.Table`` output the CLI used to
+    produce: top/bottom title rule, a header row underlined with ``-``, and
+    each data row on its own line. Columns are sized to the widest cell.
+    """
+    cols = len(headers)
+    widths = [len(h) for h in headers]
+    for row in rows:
+        for c, cell in enumerate(row[:cols]):
+            widths[c] = max(widths[c], len(cell))
+
+    def _border(left: str, fill: str, right: str) -> str:
+        return left + fill + right
+
+    sep = _border("+", "+".join("-" * (w + 2) for w in widths), "+")
+
+    lines: list[str] = []
+    if title:
+        lines.append(_wrap("bold", title))
+    lines.append(sep)
+    header_cells = " | ".join(h.ljust(widths[c]) for c, h in enumerate(headers))
+    lines.append(f"| {header_cells} |")
+    lines.append(sep)
+    for row in rows:
+        cells = " | ".join(
+            str(row[c]).ljust(widths[c]) if c < len(row) else "".ljust(widths[c])
+            for c in range(cols)
+        )
+        lines.append(f"| {cells} |")
+    lines.append(sep)
+    return "\n".join(lines)

cds/core/__init__.py

@@ -0,0 +1,5 @@
+"""Core data models for CDS."""
+
+from cds.core.models import Domain, Hypothesis, HypothesisStatus
+
+__all__ = ["Domain", "Hypothesis", "HypothesisStatus"]

cds/core/_numeric.py

@@ -0,0 +1,92 @@
+"""Central numeric constants for CDS solvers and numerical kernels.
+
+These replace scattered magic numbers (``1e-15`` near-zero guards, ``1e-7``
+finite-difference steps, ``0.01`` learning rates, ``-1e9`` masking sentinels)
+with named, documented constants. The values mirror the literals they replace
+so behavior is unchanged; only readability and consistency improve.
+
+Notes
+-----
+- ``EPSILON`` is derived from :func:`math.ulp` rather than hardcoded, so it
+  reflects the actual machine epsilon on the running interpreter.
+- Module-local algorithm constants (e.g. the Lanczos ``cof`` coefficients and
+  ``_MAXIT`` / ``_EPS`` / ``_FPMIN`` in ``stats.hypothesis_tests``) stay where
+  they are: they are intrinsic to a specific Numerical-Recipes routine, not
+  shared tuning knobs.
+"""
+
+from __future__ import annotations
+
+import math
+
+# Machine epsilon of the running interpreter (~2.220446e-16 on CPython/IEEE-754).
+# Use this instead of the legacy hardcoded ``1e-15`` singularity guards.
+EPSILON: float = math.ulp(1.0)
+
+# Near-zero threshold for singularity / divide-by-zero guards
+# (pivot checks, zero-vector guards, variance floors). Kept at ``1e-15`` to
+# preserve the exact behavior of the original guards.
+NEAR_ZERO: float = 1e-15
+
+# Default step size for central finite-difference gradient estimates.
+DEFAULT_FD_STEP: float = 1e-7
+
+# Generic convergence tolerance for iterative solvers (gradient descent,
+# Adam, golden-section line search).
+DEFAULT_TOLERANCE: float = 1e-8
+
+# Newton-Raphson root-finding tolerance (``abs(f(x)) < tol``).
+NEWTON_TOLERANCE: float = 1e-10
+
+# Base step for the Newton-Raphson numerical derivative.
+NEWTON_DERIVATIVE_STEP: float = 1e-5
+
+# RK45 adaptive integrator defaults.
+RK45_DEFAULT_ATOL: float = 1e-6
+RK45_DEFAULT_RTOL: float = 1e-3
+RK45_DEFAULT_DT: float = 0.01
+
+# Adaptive-step shrink / grow factors for the RK45 controller.
+RK45_STEP_SHRINK: float = 0.1
+RK45_STEP_SAFETY: float = 0.9
+RK45_STEP_GROW: float = 10.0
+
+# Loop-termination epsilon for ODE time stepping (``while t < t_end - eps``).
+LOOP_EPSILON: float = 1e-12
+
+# Near-minimum positive float (Numerical Recipes ``FPMIN``), used to avoid
+# underflow in continued-fraction / series evaluations.
+NEAR_MIN_FLOAT: float = 1e-300
+
+# Adam-family optimizer defaults (Kingma & Ba 2015). Unifies the defaults
+# previously split between ``optimization.minimize`` (lr=0.01) and
+# ``nlp.optim`` (lr=1e-3) — both now read ``ADAM_DEFAULT_LR``.
+ADAM_DEFAULT_LR: float = 1e-3
+ADAM_DEFAULT_BETAS: tuple[float, float] = (0.9, 0.999)
+ADAM_DEFAULT_EPS: float = 1e-8
+
+# SGD learning rate default.
+SGD_DEFAULT_LR: float = 0.01
+
+# MLP / plain gradient-descent learning rate default.
+GD_DEFAULT_LR: float = 0.01
+
+# Layer normalization variance-floor epsilon.
+LAYERNORM_EPS: float = 1e-5
+
+# Sampling temperature divide-by-zero guard.
+SAMPLING_TEMPERATURE_EPS: float = 1e-8
+
+# Softmax sampling divide-by-zero guard (legacy ``1e-8``).
+SOFTMAX_TEMPERATURE_EPS: float = 1e-8
+
+# Masked-fill sentinel replacing the legacy ``-1e9`` literal in NLP attention
+# masks. ``-inf`` propagates to a true zero after softmax; ``-1e9`` only
+# underflows to ~0, leaving a small residual probability.
+NEG_INF_MASK: float = float("-inf")
+
+# Entanglement (concurrence) detection threshold.
+CONCURRENCE_THRESHOLD: float = 1e-9
+
+# Plotting normalization floor (avoids division by zero on flat signals).
+PLOT_NORMALIZATION_FLOOR: float = 1e-10

cds/core/models.py

@@ -0,0 +1,166 @@
+"""Core data models for CDS.
+
+The data models here are plain :mod:`dataclasses` — no third-party validation
+library. Field constraints that previously relied on ``pydantic`` (the
+``[0.0, 1.0]`` confidence range, enum coercion of ``domain``) are enforced in
+``Hypothesis.__post_init__``, which raises :class:`ValueError` on violations.
+This keeps the whole ``cds`` package zero-dependency at runtime while
+preserving the construction contract the test suite pins down.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any
+
+
+class Domain(str, Enum):
+    """Broad scientific domains supported by CDS."""
+
+    PHYSICS = "physics"
+    COSMOLOGY = "cosmology"
+    MATHEMATICS = "mathematics"
+    BIOLOGY = "biology"
+    CHEMISTRY = "chemistry"
+    GENERAL_SCIENCE = "general_science"
+
+
+class HypothesisStatus(str, Enum):
+    """Lifecycle states for a Hypothesis."""
+
+    NEW = "new"
+    REFINED = "refined"
+    CRITIQUED = "critiqued"
+    TESTABLE = "testable"
+    VALIDATED = "validated"
+    REJECTED = "rejected"
+    ARCHIVED = "archived"
+
+
+@dataclass
+class Hypothesis:
+    """A scientific hypothesis with metadata and traceability.
+
+    Attributes:
+        id: Unique identifier.
+        statement: The core hypothesis statement.
+        domain: Scientific domain; accepts a :class:`Domain` or its string value.
+        research_question: The research question this hypothesis addresses.
+        rationale: Optional reasoning behind the hypothesis.
+        assumptions: Preconditions assumed to hold.
+        predictions: Testable consequences of the hypothesis.
+        status: Current point in the hypothesis lifecycle.
+        confidence: Subjective belief in the hypothesis, in the closed
+            interval ``[0.0, 1.0]``.
+        created_at: Timezone-aware UTC timestamp of creation.
+        tags: Free-form categorical tags.
+        sources: References or retrieval sources backing the hypothesis.
+        metadata: Arbitrary string-keyed/string-valued extra information.
+    """
+
+    id: str
+    statement: str
+    domain: Domain
+    research_question: str
+    rationale: str | None = None
+    assumptions: list[str] = field(default_factory=list)
+    predictions: list[str] = field(default_factory=list)
+    status: HypothesisStatus = HypothesisStatus.NEW
+    confidence: float = 0.5
+    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    tags: list[str] = field(default_factory=list)
+    sources: list[str] = field(default_factory=list)
+    metadata: dict[str, str] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        """Coerce ``domain`` to its enum and validate ``confidence`` range.
+
+        Mirrors the coercion/validation pydantic performed previously: a
+        bare string like ``"physics"`` is accepted and converted to
+        :class:`Domain.PHYSICS`; ``confidence`` must lie in ``[0.0, 1.0]``.
+        Unknown values raise ``ValueError`` (matching the old
+        ``ValidationError`` behaviour).
+        """
+        # Coerce string values into the enum members so callers can pass either
+        # ``Domain.PHYSICS`` or the bare string ``"physics"``. This mirrors the
+        # coercion pydantic performed previously; an unknown value raises
+        # ValueError, matching the old ValidationError behaviour.
+        if not isinstance(self.domain, Domain):
+            try:
+                self.domain = Domain(self.domain)
+            except ValueError as exc:
+                raise ValueError(f"{self.domain!r} is not a valid Domain") from exc
+
+        # The closed interval [0.0, 1.0] is the only constraint on confidence.
+        # Out-of-range values raise ValueError, matching the former pydantic
+        # ``ge=0.0, le=1.0`` contract that the test suite pins down.
+        if not 0.0 <= self.confidence <= 1.0:
+            raise ValueError(f"confidence must be in [0.0, 1.0], got {self.confidence}")
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize this hypothesis to a JSON-friendly dict.
+
+        Mirrors the previous ``pydantic`` ``model_dump(mode="json")`` output:
+        enums become their string ``value`` and ``created_at`` is rendered as
+        an ISO-8601 string, so the result is directly :func:`json.dumps`-able.
+        """
+        return {
+            "id": self.id,
+            "statement": self.statement,
+            "domain": self.domain.value,
+            "research_question": self.research_question,
+            "rationale": self.rationale,
+            "assumptions": list(self.assumptions),
+            "predictions": list(self.predictions),
+            "status": self.status.value,
+            "confidence": self.confidence,
+            "created_at": self.created_at.isoformat(),
+            "tags": list(self.tags),
+            "sources": list(self.sources),
+            "metadata": dict(self.metadata),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Hypothesis:
+        """Rebuild a :class:`Hypothesis` from :meth:`to_dict` output.
+
+        Completes the JSON round trip: enum strings are coerced back into
+        their :class:`Domain` / :class:`HypothesisStatus` members and
+        ``created_at`` is parsed from its ISO-8601 rendering. Missing
+        optional keys fall back to the same defaults as the constructor, so
+        partially-specified records load cleanly. Unknown ``status`` values
+        raise ``ValueError``.
+        """
+        payload = dict(data)  # copy so we never mutate the caller's dict
+        created_at = payload.get("created_at")
+        if isinstance(created_at, str):
+            payload["created_at"] = datetime.fromisoformat(created_at)
+        status = payload.get("status")
+        if status is not None and not isinstance(status, HypothesisStatus):
+            payload["status"] = HypothesisStatus(status)
+        return cls(**payload)
+
+    def to_markdown(self) -> str:
+        """Render this hypothesis as a structured Markdown document."""
+        lines = [
+            f"# Hypothesis: {self.id}",
+            "",
+            f"**Statement**: {self.statement}",
+            "",
+            f"**Domain**: {self.domain.value}",
+            f"**Research Question**: {self.research_question}",
+            f"**Status**: {self.status.value} | **Confidence**: {self.confidence:.2f}",
+            "",
+        ]
+        if self.rationale:
+            lines += ["## Rationale", self.rationale, ""]
+        if self.assumptions:
+            lines += ["## Assumptions"] + [f"- {a}" for a in self.assumptions] + [""]
+        if self.predictions:
+            preds = [f"- {p}" for p in self.predictions]
+            lines += ["## Predictions / Testable Consequences"] + preds + [""]
+        if self.tags:
+            lines += [f"**Tags**: {', '.join(self.tags)}"]
+        return "\n".join(lines)

cds/data_analysis/__init__.py

@@ -0,0 +1,30 @@
+"""Data loading, analysis and visualization helpers."""
+
+from cds.data_analysis.dataset import DataSet
+from cds.data_analysis.loader import DataTable, load_csv
+from cds.data_analysis.transform import moving_average, normalize, z_score
+from cds.data_analysis.viz import plot_bar, plot_line
+
+__all__ = [
+    "load_csv",
+    "DataTable",
+    "DataSet",
+    "normalize",
+    "z_score",
+    "moving_average",
+    "plot_bar",
+    "plot_line",
+]
+
+
+def __getattr__(name: str):  # type: ignore[no-untyped-def]
+    """Lazily expose the optional pandas bridge.
+
+    ``pandas_io`` imports pandas at call time, so it is only resolved on first
+    access — keeping the core import zero-dependency.
+    """
+    if name in {"to_dataframe", "from_dataframe"}:
+        from cds.data_analysis import pandas_io
+
+        return getattr(pandas_io, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")