topogpt3 0.2.0__py3-none-any.whl

topogpt3/__init__.py

@@ -0,0 +1,205 @@
+"""TopoGPT3: complex-valued spectral language model for code.
+
+This package bundles:
+
+- ``topogpt3.model``: the base TopoGPT2 architecture (quaternion spectral
+  layers, BPE tokenizer, helpers).
+- ``topogpt3.train``: the curriculum trainer with Grassmannian / Fisher /
+  phase diagnostics.
+- ``topogpt3.inference``: a standard autoregressive sampler that loads a
+  trained safetensors checkpoint.
+- ``topogpt3.inference_hrm``: a hierarchical recursive reasoning sampler
+  that reuses the same checkpoint with no extra trained parameters.
+- ``topogpt3.lens_model``: the Jacobian-lens model adapter (LensModel
+  protocol + TopoGPT3LensModel wrapper).
+- ``topogpt3.jlens``: Jacobian lens fitting, application, and the
+  ActivationRecorder / JacobianLens infrastructure.
+
+Typical usage from a downstream project::
+
+    from topogpt3 import InferenceSettings, InferencePipeline
+
+    settings = InferenceSettings(
+        checkpoint_dir="checkpoints_topogpt3",
+        prompt="def fibonacci(",
+        max_new_tokens=200,
+    )
+    InferencePipeline(settings).execute()
+
+Jacobian lens usage::
+
+    from topogpt3.lens_model import TopoGPT3LensModel
+    from topogpt3.jlens import fit, JacobianLens
+
+    model = TopoGPT3LensModel.from_checkpoint("checkpoints_topogpt3/last")
+    lens = fit(model, prompts, source_layers=[0, 1, 2, 3, 4])
+    lens_logits, model_logits, input_ids = lens.apply(model, "def hello(")
+"""
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .model import (
+    BPETokenizer,
+    QuaternionSpectralLayer,
+    SpectralAutoencoder,
+    TopoGPT2,
+    TopoGPT2Config,
+    set_seed,
+    setup_logger,
+)
+from .train import (
+    CheckpointStore,
+    CodeCurriculumLoader,
+    GrassmannianTracker,
+    TopoGPT3Config,
+    TopoGPT3Trainer,
+    apply_gauss_patch,
+)
+from .inference import (
+    GenerationReport,
+    InferencePipeline,
+    InferenceSettings,
+    SamplingPolicy,
+)
+from .inference_hrm import (
+    GenerationReasoningSummary,
+    HRMInferencePipeline,
+    HRMInferenceSettings,
+    HierarchicalRecursiveReasoner,
+    RecursiveReasoningConfig,
+)
+from .lens_model import (
+    LensModel,
+    TinyDecoder,
+    TopoGPT3LensConfig,
+    TopoGPT3LensModel,
+)
+from .jlens import (
+    ActivationRecorder,
+    JacobianLens,
+    TopoGPT3JLensAppConfig,
+    TopoGPT3JLensFitConfig,
+    fit,
+    jacobian_for_prompt,
+    valid_position_mask,
+)
+# advanced training (identity preserved: additive
+# adapters + external loss/reward wrappers, never architecture rewrites)
+from .yarn import YaRNConfig, apply_yarn_to_rope, yarn_scale_inv_freq
+from .chat import (
+    apply_chat_template,
+    parse_thinking,
+    parse_tool_calls,
+    split_reasoning_content,
+)
+from .lora import (
+    LoRA,
+    apply_lora,
+    freeze_non_lora,
+    load_lora,
+    lora_parameters,
+    merge_lora,
+    save_lora,
+)
+from .rewards import (
+    base_rewards,
+    distillation_loss,
+    dpo_loss_fn,
+    grpo_advantages,
+    grpo_loss,
+    k3_kl,
+    logits_to_log_probs,
+    rep_penalty,
+    spectral_bonus,
+)
+from .rollout import (
+    RolloutResult,
+    TorchRolloutEngine,
+    compute_per_token_logps,
+    create_rollout_engine,
+)
+from .trainer_utils_topo import (
+    SkipBatchSampler,
+    get_lr,
+    init_distributed_mode,
+    is_main_process,
+    setup_seed,
+    topo_checkpoint,
+)
+from .tools_agent import TOOLS, execute_tool, rollout_multiturn
+from .eval_toolcall import evaluate as evaluate_toolcall
+
+__all__ = [
+    "__version__",
+    "ActivationRecorder",
+    "BPETokenizer",
+    "CheckpointStore",
+    "CodeCurriculumLoader",
+    "fit",
+    "GenerationReasoningSummary",
+    "GenerationReport",
+    "GrassmannianTracker",
+    "HierarchicalRecursiveReasoner",
+    "HRMInferencePipeline",
+    "HRMInferenceSettings",
+    "InferencePipeline",
+    "InferenceSettings",
+    "jacobian_for_prompt",
+    "JacobianLens",
+    "LensModel",
+    "QuaternionSpectralLayer",
+    "RecursiveReasoningConfig",
+    "SamplingPolicy",
+    "set_seed",
+    "setup_logger",
+    "SpectralAutoencoder",
+    "TinyDecoder",
+    "TopoGPT2",
+    "TopoGPT2Config",
+    "TopoGPT3Config",
+    "TopoGPT3JLensAppConfig",
+    "TopoGPT3JLensFitConfig",
+    "TopoGPT3LensConfig",
+    "TopoGPT3LensModel",
+    "TopoGPT3Trainer",
+    "apply_gauss_patch",
+    "valid_position_mask",
+    "YaRNConfig",
+    "apply_yarn_to_rope",
+    "yarn_scale_inv_freq",
+    "apply_chat_template",
+    "parse_thinking",
+    "parse_tool_calls",
+    "split_reasoning_content",
+    "LoRA",
+    "apply_lora",
+    "freeze_non_lora",
+    "load_lora",
+    "lora_parameters",
+    "merge_lora",
+    "save_lora",
+    "base_rewards",
+    "distillation_loss",
+    "dpo_loss_fn",
+    "grpo_advantages",
+    "grpo_loss",
+    "k3_kl",
+    "logits_to_log_probs",
+    "rep_penalty",
+    "spectral_bonus",
+    "RolloutResult",
+    "TorchRolloutEngine",
+    "compute_per_token_logps",
+    "create_rollout_engine",
+    "SkipBatchSampler",
+    "get_lr",
+    "init_distributed_mode",
+    "is_main_process",
+    "setup_seed",
+    "topo_checkpoint",
+    "TOOLS",
+    "execute_tool",
+    "rollout_multiturn",
+    "evaluate_toolcall",
+]

topogpt3/__main__.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import sys
+
+
+def main() -> None:
+    """TopoGPT3 entry point. Delegates to subcommands."""
+    if len(sys.argv) < 2:
+        print(
+            "TopoGPT3: complex-valued spectral language model\n"
+            "\n"
+            "Usage:\n"
+            "  python3 -m topogpt3              this help\n"
+            "  python3 -m topogpt3 infer         standard autoregressive inference\n"
+            "  python3 -m topogpt3 infer-hrm     HRM recursive reasoning inference\n"
+            "  python3 -m topogpt3 train         curriculum training\n"
+            "  python3 -m topogpt3 api           start API server\n"
+            "  python3 -m topogpt3 lens          test model loading\n"
+            "  python3 -m topogpt3 jlens         Jacobian lens demo\n"
+            "  python3 -m topogpt3 check         quick checkpoint validation\n"
+            "  python3 -m topogpt3 train-lora      SFT with native LoRA adapters\n"
+            "  python3 -m topogpt3 train-dpo       preference alignment (DPO)\n"
+            "  python3 -m topogpt3 train-grpo      RLAIF (GRPO/CISPO, no critic)\n"
+            "  python3 -m topogpt3 train-ppo       RLAIF (PPO + value head)\n"
+            "  python3 -m topogpt3 train-distill   white-box distillation\n"
+            "  python3 -m topogpt3 train-agent     agentic RL (multi-turn tools)\n"
+            "  python3 -m topogpt3 convert         merge LoRA / export stubs\n"
+            "  python3 -m topogpt3 export-chat     curriculum HF -> chat JSONL\n"
+        )
+        return
+    subcommand = sys.argv[1]
+    sys.argv = sys.argv[1:]
+    if subcommand in ("jlens", "lens"):
+        from .jlens import _demo_jlens
+        _demo_jlens()
+    elif subcommand == "check":
+        from .lens_model import TopoGPT3LensModel
+        m = TopoGPT3LensModel.from_checkpoint("checkpoints_topogpt3/last")
+        print(f"OK: n_layers={m.n_layers}, d_model={m.d_model}")
+    elif subcommand in ("api", "api_server"):
+        from .api_server import main as api_main
+        api_main()
+    elif subcommand in ("infer", "inference"):
+        from .inference import main as infer_main
+        infer_main()
+    elif subcommand in ("infer-hrm", "inference-hrm"):
+        from .inference_hrm import main as hrm_main
+        hrm_main()
+    elif subcommand == "train":
+        from .train import main as train_main
+        train_main()
+    elif subcommand == "train-lora":
+        from .train_lora import main as m
+        m()
+    elif subcommand == "train-dpo":
+        from .train_dpo import main as m
+        m()
+    elif subcommand == "train-grpo":
+        from .train_grpo import main as m
+        m()
+    elif subcommand == "train-ppo":
+        from .train_ppo import main as m
+        m()
+    elif subcommand == "train-distill":
+        from .train_distill import main as m
+        m()
+    elif subcommand == "train-agent":
+        from .train_agent import main as m
+        m()
+    elif subcommand == "convert":
+        from .convert import main as m
+        m()
+    elif subcommand == "export-chat":
+        from .export_chat import main as m
+        m()
+    else:
+        print(f"Unknown subcommand: {subcommand}")
+
+
+if __name__ == "__main__":
+    main()