claude-turing 1.0.0

package/config/defaults.yaml

@@ -0,0 +1,45 @@
+# Turing Plugin Defaults
+#
+# Fallback values used when a scaffolded project's config.yaml is missing keys.
+# These represent conservative starting points — the autoresearch agent will
+# explore the parameter space from here.
+
+convergence:
+  patience: 3                    # Consecutive non-improvements before stopping
+  improvement_threshold: 0.005   # 0.5% relative improvement required
+
+evaluation:
+  primary_metric: "accuracy"
+  metrics: ["accuracy", "f1_weighted"]
+  lower_is_better: false
+
+model:
+  type: "xgboost"
+  hyperparams:
+    n_estimators: 100
+    max_depth: 4
+    learning_rate: 0.1
+
+data:
+  split_ratios:
+    train: 0.70
+    val: 0.15
+    test: 0.15
+  random_state: 42
+
+# Template placeholders — resolved during /turing:init scaffolding
+placeholders:
+  PROJECT_NAME: "Name of the ML project (e.g., sentiment, churn)"
+  TARGET_METRIC: "Primary metric to optimize (e.g., accuracy, f1, mae)"
+  TASK_DESCRIPTION: "What the model does (e.g., Predict customer churn)"
+  ML_DIR: "Directory for ML files relative to project root"
+  DATA_SOURCE: "Path to training data file"
+  METRIC_DIRECTION: "lower or higher — which direction is better"
+
+# Agent configuration
+agents:
+  researcher:
+    max_turns: 200
+    memory_path: ".claude/agent-memory/ml-researcher/MEMORY.md"
+  evaluator:
+    max_turns: 50

package/config/experiment_archetypes.yaml

@@ -0,0 +1,127 @@
+# Structured Experiment Archetypes
+#
+# Pre-defined experiment strategies that give the agent (and human)
+# structured starting points instead of ad-hoc free text.
+#
+# Usage:
+#   /turing:try archetype:model_comparison
+#   /turing:try archetype:feature_sweep
+#   python scripts/manage_hypotheses.py add --archetype model_comparison
+#
+# Each archetype defines: what to do, in what order, and what to measure.
+# The agent fills in project-specific details (metric, model type, etc.)
+# from config.yaml at execution time.
+
+archetypes:
+  model_comparison:
+    name: "Systematic Model Comparison"
+    description: "Compare multiple model families with identical preprocessing to find the best architecture for this task"
+    steps:
+      - "Train all candidate models with identical data splits and preprocessing"
+      - "Use cross-validation (5-fold) for each model"
+      - "Compare on primary metric + secondary metrics"
+      - "Run statistical comparison (paired t-test or Wilcoxon) between top 2"
+      - "Report: comparison table, statistical significance, recommendation"
+    suggested_models:
+      - "xgboost"
+      - "lightgbm"
+      - "random_forest"
+      - "logistic_regression"
+      - "mlp"
+    when_to_use: "Early in a project when you haven't established which model family works best"
+    expected_experiments: 5
+    family_tag: "model-comparison"
+
+  hyperparameter_sweep:
+    name: "Hyperparameter Grid Sweep"
+    description: "Systematically explore the hyperparameter space of the current best model"
+    steps:
+      - "Define parameter ranges based on current best config"
+      - "Generate cartesian product queue via sweep_config.yaml"
+      - "Run all combinations sequentially"
+      - "Identify top 3 configurations"
+      - "Run statistical validation on top 3 (multi-seed)"
+    when_to_use: "After selecting a model family, before fine-tuning"
+    expected_experiments: 15-36
+    family_tag: "hyperparameter-sweep"
+
+  feature_sweep:
+    name: "Feature Engineering Exploration"
+    description: "Systematically add and evaluate feature transformations one at a time"
+    steps:
+      - "Establish baseline with current features"
+      - "Add polynomial interaction features — evaluate"
+      - "Add target encoding for high-cardinality categoricals — evaluate"
+      - "Add binning for continuous features — evaluate"
+      - "Remove low-importance features (bottom 20%) — evaluate"
+      - "Combine the improvements that helped independently"
+    when_to_use: "When model architecture is settled but performance plateaus"
+    expected_experiments: 6-10
+    family_tag: "feature-engineering"
+
+  regularization_search:
+    name: "Regularization Optimization"
+    description: "Find the optimal regularization strength to minimize overfitting"
+    steps:
+      - "Measure current train/val gap (overfit_gap metric)"
+      - "If gap > 0.05: increase regularization (max_depth down, min_child_weight up, dropout up)"
+      - "If gap < 0.01: decrease regularization (model may be underfitting)"
+      - "Binary search: try 3-4 regularization levels"
+      - "Plot train/val gap vs regularization strength"
+      - "Select the configuration with smallest gap that doesn't sacrifice val performance"
+    when_to_use: "When train metrics are much better than val metrics (overfit_gap > 0.05)"
+    expected_experiments: 4-6
+    family_tag: "regularization"
+
+  ensemble_construction:
+    name: "Ensemble Model Construction"
+    description: "Combine top-performing models into an ensemble for improved stability and accuracy"
+    steps:
+      - "Select top 3 diverse models (different families preferred)"
+      - "Try soft voting ensemble — evaluate"
+      - "Try stacking with a simple meta-learner (logistic regression) — evaluate"
+      - "Try blending (average predictions on holdout) — evaluate"
+      - "Compare ensemble vs best individual model"
+      - "Run multi-seed validation on the best ensemble"
+    when_to_use: "Late-stage optimization when individual models have plateaued"
+    expected_experiments: 4-6
+    family_tag: "ensemble"
+
+  learning_rate_schedule:
+    name: "Learning Rate Schedule Optimization"
+    description: "Trade off learning rate against number of estimators for gradient boosting models"
+    steps:
+      - "Start with current lr and n_estimators"
+      - "Try lr/2 with 2x n_estimators"
+      - "Try lr/5 with 5x n_estimators"
+      - "Try lr/10 with 10x n_estimators"
+      - "Find the sweet spot where val performance peaks before overfitting"
+    when_to_use: "For gradient boosting models (XGBoost, LightGBM) after initial hyperparameter selection"
+    expected_experiments: 4-5
+    family_tag: "lr-schedule"
+
+  data_quality_audit:
+    name: "Data Quality Investigation"
+    description: "Investigate whether data quality issues are limiting model performance"
+    steps:
+      - "Check class balance — if imbalanced, try SMOTE or class weights"
+      - "Check for label noise — train on 90% of data, predict the held-out 10%, flag disagreements"
+      - "Check for data leakage — verify no future information in features"
+      - "Check feature distributions — identify outliers, missing value patterns"
+      - "Try robust preprocessing — winsorize outliers, impute missing values differently"
+    when_to_use: "When model performance is unexpectedly poor or unstable across seeds"
+    expected_experiments: 3-5
+    family_tag: "data-quality"
+
+  ablation_study:
+    name: "Feature Ablation Study"
+    description: "Remove features one at a time to understand their individual contribution"
+    steps:
+      - "Train baseline with all features — record metric"
+      - "For each feature group: remove it, retrain, record metric delta"
+      - "Rank features by importance (metric drop when removed)"
+      - "Identify features that hurt performance (metric improves when removed)"
+      - "Train final model without harmful features"
+    when_to_use: "When you have many features and want to understand which matter"
+    expected_experiments: "N+1 where N is the number of feature groups"
+    family_tag: "ablation"

package/config/lifecycle.toml

@@ -0,0 +1,31 @@
+# Experiment Lifecycle State Machine
+#
+# Each experiment transitions through these states. The autoresearch
+# agent validates transitions against this data — not English prose.
+#
+# This is a formal encoding of the scientific method applied to ML:
+# hypothesize -> execute -> observe -> decide -> record.
+
+[states]
+proposed   = { description = "Hypothesis formed, changes committed, not yet run" }
+running    = { description = "Training in progress" }
+evaluating = { description = "Training complete, metrics being computed" }
+kept       = { description = "Improvement confirmed, merged to main" }
+discarded  = { description = "No improvement, reverted" }
+converged  = { description = "Training loop terminated — convergence detected" }
+
+[transitions]
+# from -> [valid next states]
+proposed   = ["running"]
+running    = ["evaluating", "discarded"]     # discarded if training crashes
+evaluating = ["kept", "discarded"]
+kept       = ["proposed"]                     # next iteration starts new hypothesis
+discarded  = ["proposed"]                     # next iteration starts new hypothesis
+
+[requirements]
+# Preconditions for each transition
+"proposed -> running"    = "Changes committed to git, venv activated"
+"running -> evaluating"  = "train.py completed without error, run.log exists"
+"evaluating -> kept"     = "Primary metric improved over prior best"
+"evaluating -> discarded" = "Primary metric did not improve"
+"running -> discarded"   = "Training crashed or timed out"

package/config/novelty_aliases.yaml

@@ -0,0 +1,107 @@
+# Novelty Guard Alias Configuration
+#
+# Configurable per-project. The novelty guard normalizes experiment
+# descriptions using these tables before comparing similarity.
+# Extend with domain-specific aliases for your ML task.
+
+phrase_aliases:
+  "learning rate": "lr"
+  "step size": "lr"
+  "batch size": "batch_size"
+  "gradient accumulation": "grad_accum"
+  "weight decay": "weight_decay"
+  "early stopping": "early_stop"
+  "random forest": "rf"
+  "gradient boosting": "gbdt"
+  "neural network": "nn"
+  "neural net": "nn"
+  "decision tree": "dtree"
+  "feature engineering": "feat_eng"
+  "feature selection": "feat_sel"
+  "hyperparameter tuning": "hparam_tune"
+  "cross validation": "cv"
+  "train test split": "split"
+  "one hot encoding": "onehot"
+  "label encoding": "label_enc"
+
+token_aliases:
+  "increase": "up"
+  "increasing": "up"
+  "raise": "up"
+  "higher": "up"
+  "boost": "up"
+  "larger": "up"
+  "bigger": "up"
+  "more": "up"
+  "decrease": "down"
+  "decreasing": "down"
+  "lower": "down"
+  "reduce": "down"
+  "smaller": "down"
+  "fewer": "down"
+  "less": "down"
+  "remove": "drop"
+  "delete": "drop"
+  "disable": "drop"
+  "add": "include"
+  "enable": "include"
+  "introduce": "include"
+  "switch": "change"
+  "replace": "change"
+  "swap": "change"
+
+stopwords:
+  - "a"
+  - "an"
+  - "and"
+  - "are"
+  - "as"
+  - "at"
+  - "be"
+  - "by"
+  - "for"
+  - "from"
+  - "if"
+  - "in"
+  - "into"
+  - "is"
+  - "it"
+  - "of"
+  - "on"
+  - "or"
+  - "the"
+  - "to"
+  - "try"
+  - "use"
+  - "using"
+  - "with"
+
+concept_patterns:
+  lr: ["lr", "learning_rate", "step_size"]
+  architecture: ["depth", "width", "layers", "heads", "nn", "rf", "gbdt", "dtree", "xgboost", "lightgbm"]
+  regularization: ["dropout", "weight_decay", "l1", "l2", "early_stop", "regulariz"]
+  features: ["feat_eng", "feat_sel", "onehot", "label_enc", "feature", "column"]
+  data: ["split", "augment", "sample", "oversample", "undersample", "cv"]
+  optimizer: ["adam", "sgd", "optim", "momentum", "scheduler"]
+  ensemble: ["voting", "stacking", "blending", "bagging", "boosting"]
+
+# Mode policies: what each research mode allows/blocks
+mode_policies:
+  explore:
+    novel: "allow"
+    known_success: "block"
+    incremental_followup: "block"
+    repeat_failure: "block"
+    duplicate_run: "block"
+  exploit:
+    novel: "caution"
+    known_success: "allow"
+    incremental_followup: "allow"
+    repeat_failure: "block"
+    duplicate_run: "block"
+  replicate:
+    novel: "block"
+    known_success: "allow"
+    incremental_followup: "allow"
+    repeat_failure: "caution"
+    duplicate_run: "allow"

package/config/relationships.toml

@@ -0,0 +1,125 @@
+# ADR Relationship Graph
+#
+# Encodes dependencies and relationships between ADRs.
+# Used by /blueprint:impact for incremental conflict detection.
+
+[nodes]
+"ADR-0001" = { title = "Use ADRs for architectural decisions", status = "Accepted" }
+"ADR-0002" = { title = "Separate hypothesis space from measurement apparatus", status = "Accepted" }
+"ADR-0003" = { title = "Two-agent architecture with least-privilege boundaries", status = "Accepted" }
+"ADR-0004" = { title = "TOML config DSL for domain knowledge", status = "Accepted" }
+"ADR-0005" = { title = "Git-disciplined experiment lifecycle", status = "Accepted" }
+"ADR-0006" = { title = "Patience-based convergence detection", status = "Accepted" }
+"ADR-0007" = { title = "JSONL append-only experiment logging", status = "Accepted" }
+"ADR-0008" = { title = "Template-based project scaffolding", status = "Accepted" }
+"ADR-0009" = { title = "XGBoost default with pluggable featurizers", status = "Accepted" }
+"ADR-0010" = { title = "Claude Code plugin distribution", status = "Accepted" }
+
+[[edges]]
+from = "ADR-0003"
+to = "ADR-0002"
+type = "implements"
+description = "Agent capability boundary is the agent-level implementation of hypothesis-measurement separation"
+
+[[edges]]
+from = "ADR-0006"
+to = "ADR-0007"
+type = "depends-on"
+description = "Convergence detection reads the JSONL experiment log to count non-improvements"
+
+[[edges]]
+from = "ADR-0005"
+to = "ADR-0002"
+type = "supports"
+description = "Git discipline (commit before, revert on failure) preserves the measurement-hypothesis boundary across experiments"
+
+[[edges]]
+from = "ADR-0008"
+to = "ADR-0002"
+type = "implements"
+description = "Template headers label files as MEASUREMENT APPARATUS or HYPOTHESIS SPACE"
+
+[[edges]]
+from = "ADR-0008"
+to = "ADR-0009"
+type = "depends-on"
+description = "Templates include the default XGBoost training pipeline"
+
+[[edges]]
+from = "ADR-0010"
+to = "ADR-0008"
+type = "depends-on"
+description = "npm installer deploys the templates directory"
+
+[[edges]]
+from = "ADR-0009"
+to = "ADR-0002"
+type = "supports"
+description = "Featurizer pipeline is READ-ONLY, agent modifies how train.py uses it"
+
+# Proposed ADRs from architecture evaluation (2026-03-31)
+[nodes."ADR-0011"]
+title = "Establish testing strategy for plugin infrastructure"
+status = "Proposed"
+
+[nodes."ADR-0012"]
+title = "Extract convergence detection from shell to testable Python"
+status = "Proposed"
+
+[nodes."ADR-0013"]
+title = "Standardize experiment status vocabulary"
+status = "Proposed"
+
+[nodes."ADR-0014"]
+title = "Enforce placeholder substitution verification"
+status = "Proposed"
+
+[nodes."ADR-0015"]
+title = "Extract metric output format into documented contract"
+status = "Proposed"
+
+[nodes."ADR-0016"]
+title = "Unify scaffolding into a single implementation"
+status = "Proposed"
+
+[[edges]]
+from = "ADR-0011"
+to = "ADR-0002"
+type = "enforces"
+description = "Testing strategy must verify hypothesis-measurement separation invariant"
+
+[[edges]]
+from = "ADR-0011"
+to = "ADR-0006"
+type = "enforces"
+description = "Testing strategy must verify convergence detection"
+
+[[edges]]
+from = "ADR-0012"
+to = "ADR-0006"
+type = "refines"
+description = "Extracts convergence logic from bash to testable Python module"
+
+[[edges]]
+from = "ADR-0013"
+to = "ADR-0004"
+type = "enforces"
+description = "Standardizes runtime code to use lifecycle.toml vocabulary"
+
+[[edges]]
+from = "ADR-0014"
+to = "ADR-0008"
+type = "refines"
+description = "Adds verification step to template scaffolding system"
+
+[[edges]]
+from = "ADR-0016"
+to = "ADR-0008"
+type = "refines"
+description = "Merges dual scaffolding paths into single implementation"
+
+[[edges]]
+from = "ADR-0016"
+to = "ADR-0014"
+type = "depends-on"
+description = "Unified scaffolding would integrate placeholder verification"

package/config/state.toml

@@ -0,0 +1,24 @@
+# Blueprint State — Session Memory
+#
+# Tracks the current state of the ADR system for contextual suggestions.
+# Updated automatically by blueprint commands.
+
+[paths]
+adr_directory = "docs/adr"
+architecture_doc = "docs/ARCHITECTURE.md"
+project_root = "."
+
+[timestamps]
+last_adr_created = "2026-03-31"
+last_audit = ""
+last_evaluation = "2026-03-31"
+last_retro = ""
+
+[counts]
+total_adrs = 16
+accepted = 16
+proposed = 0
+rejected = 0
+deferred = 0
+deprecated = 0
+superseded = 0

package/config/task_taxonomy.yaml

@@ -0,0 +1,110 @@
+# ML Task Property Taxonomy
+#
+# Used by suggest_models.py to classify a task and generate
+# targeted arXiv search queries. Adapted from AERO's
+# ML_RESEARCH_CATEGORIES (src/aero/model_researcher/shared_defs.py).
+#
+# Each category has a key, a human-readable label, and a description.
+# The LLM detects which categories apply to the user's task.
+# Categories can be extended per-project by editing this file.
+
+categories:
+  variable_length_sequences:
+    label: "Variable-Length Sequences"
+    description: "Data consists of sequences of varying lengths (e.g., text, sensor streams, speech)"
+    search_terms: ["sequence modeling", "variable length", "recurrent"]
+
+  fixed_channel_count:
+    label: "Fixed Channel Count"
+    description: "Inputs have a fixed number of channels or features across all samples (e.g., EEG, RGB images)"
+    search_terms: ["multi-channel", "fixed input", "feature vector"]
+
+  temporal_structure:
+    label: "Temporal Structure"
+    description: "Data has inherent time dependencies or ordering (e.g., time series, forecasting)"
+    search_terms: ["time series", "temporal", "forecasting"]
+
+  classification_objective:
+    label: "Classification"
+    description: "Task involves predicting discrete labels from data"
+    search_terms: ["classification", "categorical prediction"]
+
+  regression_objective:
+    label: "Regression"
+    description: "Task involves predicting continuous values"
+    search_terms: ["regression", "continuous prediction"]
+
+  generation_objective:
+    label: "Generation"
+    description: "Models must produce new data samples from learned distributions"
+    search_terms: ["generative model", "data generation", "synthesis"]
+
+  noise_robustness:
+    label: "Noise Robustness"
+    description: "System must perform well under noisy, incomplete, or corrupted inputs"
+    search_terms: ["noise robust", "data corruption", "missing data"]
+
+  real_time_constraint:
+    label: "Real-Time Constraint"
+    description: "Solution must operate under strict latency or streaming requirements"
+    search_terms: ["real-time", "low latency", "streaming"]
+
+  sensor_data:
+    label: "Sensor Data"
+    description: "Inputs originate from physical sensors (e.g., IoT, biomedical, accelerometers)"
+    search_terms: ["sensor data", "IoT", "signal processing"]
+
+  multimodal_data:
+    label: "Multimodal"
+    description: "Task combines multiple data types or modalities (e.g., vision + language)"
+    search_terms: ["multimodal", "multi-modal", "cross-modal"]
+
+  interpretability_required:
+    label: "Interpretability"
+    description: "Model must provide human-understandable reasoning or explanations"
+    search_terms: ["interpretable", "explainable", "XAI"]
+
+  few_shot_learning:
+    label: "Few-Shot Learning"
+    description: "System must generalize from very few labeled examples"
+    search_terms: ["few-shot", "low resource", "meta-learning"]
+
+  tabular_data:
+    label: "Tabular Data"
+    description: "Inputs are structured rows/columns (e.g., CSV, database tables)"
+    search_terms: ["tabular", "structured data", "gradient boosting"]
+
+  image_data:
+    label: "Image Data"
+    description: "Inputs are images or visual data"
+    search_terms: ["image classification", "computer vision", "convolutional"]
+
+  text_data:
+    label: "Text Data"
+    description: "Inputs are natural language text"
+    search_terms: ["NLP", "text classification", "language model"]
+
+  anomaly_detection:
+    label: "Anomaly Detection"
+    description: "Task involves identifying outliers or unusual patterns"
+    search_terms: ["anomaly detection", "outlier detection", "novelty detection"]
+
+  imbalanced_classes:
+    label: "Imbalanced Classes"
+    description: "Class distribution is heavily skewed"
+    search_terms: ["class imbalance", "oversampling", "SMOTE"]
+
+  high_dimensionality:
+    label: "High Dimensionality"
+    description: "Feature space is very large relative to sample count"
+    search_terms: ["dimensionality reduction", "feature selection", "curse of dimensionality"]
+
+  small_dataset:
+    label: "Small Dataset"
+    description: "Training data is limited (hundreds to low thousands of samples)"
+    search_terms: ["small data", "data-efficient", "transfer learning"]
+
+  large_scale:
+    label: "Large Scale"
+    description: "Dataset or model requires distributed or efficient training"
+    search_terms: ["large-scale", "distributed training", "efficient training"]

package/config/taxonomy.toml

@@ -0,0 +1,37 @@
+# Experiment Classification Taxonomy
+#
+# Structured vocabulary for categorizing experiments, failure modes,
+# and model architectures. Agents use these categories consistently
+# across sessions — classification by data, not by English judgment.
+
+[experiment_types]
+hyperparameter = "Change model hyperparameters (lr, depth, n_estimators, etc.)"
+architecture   = "Change model type or structure (XGBoost -> LightGBM, add layers)"
+feature        = "Change feature engineering (add/remove/transform features)"
+data           = "Change data handling (augmentation, sampling, preprocessing)"
+ensemble       = "Combine multiple models"
+regularization = "Change regularization strategy (dropout, weight decay, early stopping)"
+
+[failure_modes]
+overfitting      = "Val metrics significantly worse than train metrics"
+underfitting     = "Both train and val metrics poor"
+convergence      = "Metrics plateaued — no improvement for N iterations"
+instability      = "Metrics oscillate across runs with same config"
+data_leakage     = "Suspiciously high metrics suggesting information leak"
+resource_limit   = "OOM, timeout, or disk space exhaustion"
+numerical        = "NaN/Inf in gradients, loss, or predictions"
+implementation   = "Bug in train.py causing incorrect training"
+
+[model_families]
+gradient_boosting = ["xgboost", "lightgbm", "catboost", "sklearn_gbdt"]
+random_forest     = ["sklearn_rf", "extra_trees"]
+linear            = ["logistic_regression", "ridge", "lasso", "elastic_net"]
+neural_network    = ["mlp", "cnn", "rnn", "transformer"]
+ensemble          = ["voting", "stacking", "blending"]
+baseline          = ["dummy", "majority_class", "mean_prediction"]
+
+[severity_levels]
+critical = "Experiment cannot run at all"
+major    = "Experiment runs but produces invalid/unreliable results"
+minor    = "Experiment runs correctly but with suboptimal configuration"
+info     = "Observation for future reference, no action required"

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "claude-turing",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Autonomous ML research harness for Claude Code. The autoresearch loop as a formal protocol — iteratively trains, evaluates, and improves ML models with structured experiment tracking, convergence detection, immutable evaluation infrastructure, and safety guardrails.",
+  "bin": {
+    "turing": "./bin/cli.js",
+    "claude-turing": "./bin/cli.js"
+  },
+  "scripts": {
+    "postinstall": "node src/postinstall.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    ".claude-plugin/",
+    "commands/",
+    "agents/",
+    "templates/",
+    "config/"
+  ],
+  "keywords": [
+    "ml",
+    "machine-learning",
+    "autoresearch",
+    "experiment-tracking",
+    "hyperparameter-tuning",
+    "autonomous-training",
+    "convergence-detection",
+    "model-evaluation",
+    "scientific-method",
+    "claude-code",
+    "plugin",
+    "ai-agents"
+  ],
+  "author": {
+    "name": "pragnition"
+  },
+  "homepage": "https://github.com/pragnition/turing",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pragnition/turing.git"
+  },
+  "bugs": {
+    "url": "https://github.com/pragnition/turing/issues"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "commander": "^13.0.0"
+  }
+}