gemla 1.0.0__py3-none-any.whl

gemla/__init__.py

@@ -0,0 +1,9 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("gemla")
+except PackageNotFoundError:
+    # Fallback when running directly from source before installation.
+    __version__ = "0.1.0"
+
+__all__ = ["__version__"]

gemla/__version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

gemla/benchmarks/__init__.py

@@ -0,0 +1,19 @@
+from gemla.benchmarks.runner import (
+    BenchmarkCase,
+    BenchmarkRecord,
+    default_benchmark_cases,
+    run_benchmark_case,
+    run_benchmark_suite,
+    summarize_benchmark_records,
+    write_benchmark_results,
+)
+
+__all__ = [
+    "BenchmarkCase",
+    "BenchmarkRecord",
+    "default_benchmark_cases",
+    "run_benchmark_case",
+    "run_benchmark_suite",
+    "summarize_benchmark_records",
+    "write_benchmark_results",
+]

gemla/benchmarks/run_all_benchmarks.py

@@ -0,0 +1,31 @@
+from gemla.benchmarks import (
+    run_benchmark_suite,
+    summarize_benchmark_records,
+    write_benchmark_results,
+)
+
+
+def main() -> None:
+    records = run_benchmark_suite()
+    summary = summarize_benchmark_records(records)
+    paths = write_benchmark_results(records)
+
+    print("GEMLA Benchmark Suite")
+    print("---------------------")
+    print(f"Total cases: {summary['total_cases']}")
+    print(f"Passed cases: {summary['passed_cases']}")
+    print(f"Failed cases: {summary['failed_cases']}")
+    print(f"Pass rate: {summary['pass_rate']:.2%}")
+    print(f"All wrong-sign rejected: {summary['all_wrong_sign_rejected']}")
+    print(f"All phase-shuffle rejected: {summary['all_phase_shuffle_rejected']}")
+    print(f"All residue-scramble rejected: {summary['all_residue_scramble_rejected']}")
+    print(f"Minimum anchor count: {summary['min_anchor_count']}")
+    print(f"Minimum winding jumps: {summary['min_winding_jumps']}")
+    print()
+    print(f"CSV written to: {paths['csv']}")
+    print(f"JSON written to: {paths['json']}")
+    print(f"Summary written to: {paths['summary']}")
+
+
+if __name__ == "__main__":
+    main()

gemla/benchmarks/runner.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import csv
+import json
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from gemla.data import make_synthetic_transport
+from gemla.pipelines import GemlaPipeline
+
+
+@dataclass(frozen=True)
+class BenchmarkCase:
+    name: str
+    n: int = 1200
+    t_max: float = 80.0
+    noise: float = 0.01
+    seed: int = 7
+    pipeline_seed: int = 11
+
+
+@dataclass(frozen=True)
+class BenchmarkRecord:
+    name: str
+    verdict: bool
+    spectral_flatness_score: float
+    wrong_sign_rejected: bool
+    phase_shuffle_rejected: bool
+    residue_scramble_rejected: bool
+    anchor_count: int
+    anchor_spacing_cv: float
+    winding_jumps: int
+    winding_cells: int
+    n: int
+    t_max: float
+    noise: float
+    seed: int
+    pipeline_seed: int
+
+
+def default_benchmark_cases() -> list[BenchmarkCase]:
+    """
+    Minimal v0.2 benchmark suite.
+
+    These cases test whether the vertical slice remains stable across
+    modest changes in seed, noise, and trajectory length.
+    """
+    return [
+        BenchmarkCase(name="baseline", n=1200, t_max=80.0, noise=0.01, seed=7),
+        BenchmarkCase(name="low_noise", n=1200, t_max=80.0, noise=0.005, seed=7),
+        BenchmarkCase(name="no_noise", n=1200, t_max=80.0, noise=0.0, seed=7),
+        BenchmarkCase(name="alt_seed_1", n=1200, t_max=80.0, noise=0.01, seed=13),
+        BenchmarkCase(name="alt_seed_2", n=1200, t_max=80.0, noise=0.01, seed=29),
+        BenchmarkCase(name="shorter_series", n=800, t_max=60.0, noise=0.01, seed=7),
+        BenchmarkCase(name="longer_series", n=1600, t_max=100.0, noise=0.01, seed=7),
+    ]
+
+
+def run_benchmark_case(case: BenchmarkCase) -> BenchmarkRecord:
+    X = make_synthetic_transport(
+        n=case.n,
+        t_max=case.t_max,
+        noise=case.noise,
+        seed=case.seed,
+    )
+
+    result = GemlaPipeline(seed=case.pipeline_seed).fit_evaluate(X)
+
+    main = result.gate_result["main"]
+    controls = result.gate_result["controls"]
+
+    return BenchmarkRecord(
+        name=case.name,
+        verdict=result.verdict,
+        spectral_flatness_score=float(main["flatness"]["score"]),
+        wrong_sign_rejected=bool(controls["wrong_sign"]["rejected"]),
+        phase_shuffle_rejected=bool(controls["phase_shuffle"]["rejected"]),
+        residue_scramble_rejected=bool(controls["residue_scramble"]["rejected"]),
+        anchor_count=int(result.anchor_result["anchor_count"]),
+        anchor_spacing_cv=float(result.anchor_result["spacing_cv"]),
+        winding_jumps=int(result.winding_result["jump_count"]),
+        winding_cells=int(result.winding_result["total_winding_cells"]),
+        n=case.n,
+        t_max=case.t_max,
+        noise=case.noise,
+        seed=case.seed,
+        pipeline_seed=case.pipeline_seed,
+    )
+
+
+def run_benchmark_suite(
+    cases: list[BenchmarkCase] | None = None,
+) -> list[BenchmarkRecord]:
+    if cases is None:
+        cases = default_benchmark_cases()
+
+    return [run_benchmark_case(case) for case in cases]
+
+
+def summarize_benchmark_records(records: list[BenchmarkRecord]) -> dict:
+    total = len(records)
+    passed = sum(record.verdict for record in records)
+
+    return {
+        "total_cases": total,
+        "passed_cases": passed,
+        "failed_cases": total - passed,
+        "pass_rate": passed / total if total else 0.0,
+        "all_passed": passed == total,
+        "all_wrong_sign_rejected": all(r.wrong_sign_rejected for r in records),
+        "all_phase_shuffle_rejected": all(r.phase_shuffle_rejected for r in records),
+        "all_residue_scramble_rejected": all(r.residue_scramble_rejected for r in records),
+        "min_anchor_count": min((r.anchor_count for r in records), default=0),
+        "min_winding_jumps": min((r.winding_jumps for r in records), default=0),
+    }
+
+
+def write_benchmark_results(
+    records: list[BenchmarkRecord],
+    output_dir: str | Path = "benchmarks/results",
+) -> dict[str, Path]:
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    csv_path = output_dir / "benchmark_results.csv"
+    json_path = output_dir / "benchmark_results.json"
+    summary_path = output_dir / "benchmark_summary.json"
+
+    rows = [asdict(record) for record in records]
+
+    if rows:
+        with csv_path.open("w", newline="", encoding="utf-8") as f:
+            writer = csv.DictWriter(f, fieldnames=list(rows[0].keys()))
+            writer.writeheader()
+            writer.writerows(rows)
+    else:
+        csv_path.write_text("", encoding="utf-8")
+
+    json_path.write_text(json.dumps(rows, indent=2), encoding="utf-8")
+
+    summary = summarize_benchmark_records(records)
+    summary_path.write_text(json.dumps(summary, indent=2), encoding="utf-8")
+
+    return {
+        "csv": csv_path,
+        "json": json_path,
+        "summary": summary_path,
+    }

gemla/cli/__init__.py

@@ -0,0 +1,3 @@
+from gemla.cli.main import main
+
+__all__ = ["main"]

gemla/cli/main.py

@@ -0,0 +1,469 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+import numpy as np
+
+from gemla.benchmarks import (
+    run_benchmark_suite,
+    summarize_benchmark_records,
+    write_benchmark_results,
+)
+from gemla.data import make_synthetic_transport
+from gemla.pipelines import GemlaPipeline
+from gemla.reports import export_markdown_report
+from gemla.integrations.latent import make_synthetic_latents
+from gemla.pipelines import GemlaLatentPipeline
+from gemla.integrations.vjepa import (
+    load_vjepa_embeddings,
+    save_sample_vjepa_like_embeddings,
+)
+from gemla.data import (
+    make_market_microstructure, 
+    make_industrial_telemetry,
+    make_cyber_event_transport,
+    make_synthetic_transport
+)
+
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="gemla",
+        description="GEMLA: Γ–EML–α Transport Architecture CLI",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    evaluate = subparsers.add_parser(
+        "evaluate",
+        help="Run the minimal GEMLA transport evaluation pipeline.",
+    )
+
+    evaluate.add_argument(
+        "--output",
+        type=str,
+        default="reports/gemla_transport_report.md",
+        help="Path where the Markdown report will be written.",
+    )
+
+    evaluate.add_argument(
+        "--n",
+        type=int,
+        default=1200,
+        help="Number of synthetic samples.",
+    )
+
+    evaluate.add_argument(
+        "--t-max",
+        type=float,
+        default=80.0,
+        help="Maximum synthetic time value.",
+    )
+
+    evaluate.add_argument(
+        "--noise",
+        type=float,
+        default=0.01,
+        help="Synthetic noise level.",
+    )
+
+    evaluate.add_argument(
+        "--seed",
+        type=int,
+        default=7,
+        help="Synthetic data random seed.",
+    )
+
+    evaluate.add_argument(
+        "--pipeline-seed",
+        type=int,
+        default=11,
+        help="Pipeline/control random seed.",
+    )
+
+    benchmark = subparsers.add_parser(
+        "benchmark",
+        help="Run the GEMLA benchmark suite.",
+    )
+
+    benchmark.add_argument(
+        "--output-dir",
+        type=str,
+        default="benchmarks/results",
+        help="Directory where benchmark CSV/JSON outputs will be written.",
+    )
+
+    evaluate_latent = subparsers.add_parser(
+        "evaluate-latent",
+        help="Run GEMLA transport evaluation on latent embeddings.",
+    )
+
+    evaluate_latent.add_argument(
+        "--input",
+        type=str,
+        default=None,
+        help="Optional .npy file containing latent embeddings of shape (n_steps, latent_dim).",
+    )
+
+    evaluate_latent.add_argument(
+        "--n",
+        type=int,
+        default=1200,
+        help="Number of synthetic latent samples if --input is not provided.",
+    )
+
+    evaluate_latent.add_argument(
+        "--latent-dim",
+        type=int,
+        default=16,
+        help="Synthetic latent dimension if --input is not provided.",
+    )
+
+    evaluate_latent.add_argument(
+        "--t-max",
+        type=float,
+        default=80.0,
+        help="Maximum synthetic time value.",
+    )
+
+    evaluate_latent.add_argument(
+        "--noise",
+        type=float,
+        default=0.01,
+        help="Synthetic latent noise level.",
+    )
+
+    evaluate_latent.add_argument(
+        "--seed",
+        type=int,
+        default=17,
+        help="Synthetic latent random seed.",
+    )
+
+    evaluate_latent.add_argument(
+        "--component-a",
+        type=int,
+        default=0,
+        help="Latent component used as real part.",
+    )
+
+    evaluate_latent.add_argument(
+        "--component-b",
+        type=int,
+        default=1,
+        help="Latent component used as imaginary part.",
+    )
+
+    evaluate_vjepa = subparsers.add_parser(
+        "evaluate-vjepa",
+        help="Run GEMLA transport evaluation on V-JEPA-style embeddings.",
+    )
+
+    evaluate_vjepa.add_argument(
+        "--input",
+        type=str,
+        default=None,
+        help="Path to a .npy file containing embeddings of shape (n_steps, latent_dim).",
+    )
+
+    evaluate_vjepa.add_argument(
+        "--synthetic",
+        action="store_true",
+        help="Generate synthetic V-JEPA-like embeddings for a demo run.",
+    )
+
+    evaluate_vjepa.add_argument(
+        "--synthetic-output",
+        type=str,
+        default="examples/vjepa_latent_transport/sample_vjepa_like_embeddings.npy",
+        help="Where synthetic V-JEPA-like embeddings will be saved.",
+    )
+
+    evaluate_vjepa.add_argument(
+        "--n",
+        type=int,
+        default=1200,
+        help="Number of synthetic embedding samples.",
+    )
+
+    evaluate_vjepa.add_argument(
+        "--latent-dim",
+        type=int,
+        default=32,
+        help="Synthetic latent dimension.",
+    )
+
+    evaluate_vjepa.add_argument(
+        "--t-max",
+        type=float,
+        default=80.0,
+        help="Maximum synthetic time value.",
+    )
+
+    evaluate_vjepa.add_argument(
+        "--noise",
+        type=float,
+        default=0.01,
+        help="Synthetic embedding noise level.",
+    )
+
+    evaluate_vjepa.add_argument(
+        "--seed",
+        type=int,
+        default=23,
+        help="Synthetic embedding random seed.",
+    )
+
+    evaluate_vjepa.add_argument(
+        "--component-a",
+        type=int,
+        default=0,
+        help="Embedding component used as real part.",
+    )
+
+    evaluate_vjepa.add_argument(
+        "--component-b",
+        type=int,
+        default=1,
+        help="Embedding component used as imaginary part.",
+    )
+
+    demo_industrial = subparsers.add_parser(
+        "demo-industrial",
+        help="Run the GEMLA industrial telemetry demo.",
+    )
+    demo_industrial.add_argument(
+        "--output",
+        type=str,
+        default="reports/industrial_telemetry_report.md",
+        help="Path where the Markdown report will be written.",
+    )
+
+    demo_market = subparsers.add_parser(
+        "demo-market",
+        help="Run the GEMLA market microstructure demo.",
+    )
+    demo_market.add_argument(
+        "--output",
+        type=str,
+        default="reports/market_microstructure_report.md",
+        help="Path where the Markdown report will be written.",
+    )
+
+    demo_cyber = subparsers.add_parser(
+        "demo-cyber",
+        help="Run the GEMLA cyber event transport demo.",
+    )
+    demo_cyber.add_argument(
+        "--output",
+        type=str,
+        default="reports/cyber_event_transport_report.md",
+        help="Path where the Markdown report will be written.",
+    )
+
+    return parser
+
+
+def run_evaluate(args: argparse.Namespace) -> int:
+    X = make_synthetic_transport(
+        n=args.n,
+        t_max=args.t_max,
+        noise=args.noise,
+        seed=args.seed,
+    )
+
+    pipe = GemlaPipeline(seed=args.pipeline_seed)
+    result = pipe.fit_evaluate(X)
+
+    print(result.summary())
+
+    report_path = export_markdown_report(
+        result,
+        output_path=Path(args.output),
+    )
+
+    print()
+    print(f"Report written to: {report_path}")
+
+    return 0 if result.verdict else 1
+
+
+def run_benchmark(args: argparse.Namespace) -> int:
+    records = run_benchmark_suite()
+    summary = summarize_benchmark_records(records)
+    paths = write_benchmark_results(
+        records,
+        output_dir=Path(args.output_dir),
+    )
+
+    print("GEMLA Benchmark Suite")
+    print("---------------------")
+    print(f"Total cases: {summary['total_cases']}")
+    print(f"Passed cases: {summary['passed_cases']}")
+    print(f"Failed cases: {summary['failed_cases']}")
+    print(f"Pass rate: {summary['pass_rate']:.2%}")
+    print(f"All wrong-sign rejected: {summary['all_wrong_sign_rejected']}")
+    print(f"All phase-shuffle rejected: {summary['all_phase_shuffle_rejected']}")
+    print(f"All residue-scramble rejected: {summary['all_residue_scramble_rejected']}")
+    print(f"Minimum anchor count: {summary['min_anchor_count']}")
+    print(f"Minimum winding jumps: {summary['min_winding_jumps']}")
+    print()
+    print(f"CSV written to: {paths['csv']}")
+    print(f"JSON written to: {paths['json']}")
+    print(f"Summary written to: {paths['summary']}")
+
+    return 0 if summary["all_passed"] else 1
+
+
+def main() -> int:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    if args.command == "evaluate":
+        return run_evaluate(args)
+
+    if args.command == "benchmark":
+        return run_benchmark(args)
+    
+    if args.command == "evaluate-latent":
+        return run_evaluate_latent(args)
+    
+    if args.command == "evaluate-vjepa":
+        return run_evaluate_vjepa(args)
+    
+    if args.command == "demo-industrial":
+        return run_demo_industrial(args)
+
+    if args.command == "demo-market":
+        return run_demo_market(args)
+
+    if args.command == "demo-cyber":
+        return run_demo_cyber(args)
+
+    parser.print_help()
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+
+def run_evaluate_latent(args: argparse.Namespace) -> int:
+    if args.input is not None:
+        latents = np.load(args.input)
+    else:
+        latents = make_synthetic_latents(
+            n=args.n,
+            latent_dim=args.latent_dim,
+            t_max=args.t_max,
+            noise=args.noise,
+            seed=args.seed,
+        )
+
+    pipe = GemlaLatentPipeline(
+        component_a=args.component_a,
+        component_b=args.component_b,
+    )
+
+    result = pipe.fit_evaluate(latents)
+
+    print(result.summary())
+
+    return 0 if result.verdict else 1
+def run_evaluate_vjepa(args: argparse.Namespace) -> int:
+    if args.synthetic:
+        embedding_path = save_sample_vjepa_like_embeddings(
+            args.synthetic_output,
+            n=args.n,
+            latent_dim=args.latent_dim,
+            t_max=args.t_max,
+            noise=args.noise,
+            seed=args.seed,
+        )
+        embeddings = load_vjepa_embeddings(embedding_path)
+    elif args.input is not None:
+        embedding_path = Path(args.input)
+        embeddings = load_vjepa_embeddings(embedding_path)
+    else:
+        print("Error: provide --input path/to/embeddings.npy or use --synthetic.")
+        return 2
+
+    pipe = GemlaLatentPipeline(
+        component_a=args.component_a,
+        component_b=args.component_b,
+    )
+
+    result = pipe.fit_evaluate(embeddings)
+
+    print("GEMLA V-JEPA-Style Latent Transport Evaluation")
+    print("----------------------------------------------")
+    print(f"Input embeddings: {embedding_path}")
+    print()
+    print(result.summary())
+
+    return 0 if result.verdict else 1
+
+def run_demo_industrial(args: argparse.Namespace) -> int:
+    X = make_industrial_telemetry()
+
+    pipe = GemlaPipeline()
+    result = pipe.fit_evaluate(X)
+
+    print("GEMLA Industrial Telemetry Demo")
+    print("-------------------------------")
+    print(result.summary())
+
+    report_path = export_markdown_report(
+        result,
+        output_path=Path(args.output),
+        title="GEMLA Industrial Telemetry Report",
+    )
+
+    print()
+    print(f"Report written to: {report_path}")
+
+    return 0 if result.verdict else 1
+
+
+def run_demo_market(args: argparse.Namespace) -> int:
+    X = make_market_microstructure()
+
+    pipe = GemlaPipeline()
+    result = pipe.fit_evaluate(X)
+
+    print("GEMLA Market Microstructure Demo")
+    print("--------------------------------")
+    print(result.summary())
+
+    report_path = export_markdown_report(
+        result,
+        output_path=Path(args.output),
+        title="GEMLA Market Microstructure Report",
+    )
+
+    print()
+    print(f"Report written to: {report_path}")
+
+    return 0 if result.verdict else 1
+
+
+def run_demo_cyber(args: argparse.Namespace) -> int:
+    X = make_cyber_event_transport()
+
+    pipe = GemlaPipeline()
+    result = pipe.fit_evaluate(X)
+
+    print("GEMLA Cyber Event Transport Demo")
+    print("--------------------------------")
+    print(result.summary())
+
+    report_path = export_markdown_report(
+        result,
+        output_path=Path(args.output),
+        title="GEMLA Cyber Event Transport Report",
+    )
+
+    print()
+    print(f"Report written to: {report_path}")
+
+    return 0 if result.verdict else 1

gemla/controls/__init__.py

@@ -0,0 +1,3 @@
+from gemla.controls.control_suite import make_controls
+
+__all__ = ["make_controls"]