aspire-si 1.1.0

English | 日本語 | 中文 | Español | Français | हिन्दी | Italiano | Português (BR)

Adversarial Student-Professor Internalized Reasoning Engine

Teaching AI to develop judgment, not just knowledge.

The Idea • Quick Start • Teachers • How It Works • Integrations • Handbook

The Idea

Traditional fine-tuning: "Here are the right answers. Match them."

ASPIRE: "Here is a wise mind. Learn to think like it does."

When you learn from a great mentor, you don't just memorize their answers. You internalize their way of seeing. Their voice becomes part of your inner dialogue. You start to anticipate what they would say, and eventually that anticipation becomes your own discernment.

ASPIRE gives AI that same experience.

┌─────────────────────────────────────────────────────────────────┐
│                         ASPIRE SYSTEM                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐         │
│  │   STUDENT   │    │   CRITIC    │    │   TEACHER   │         │
│  │    MODEL    │    │   MODEL     │    │    MODEL    │         │
│  │             │    │             │    │             │         │
│  │ (learning)  │    │ (internal-  │    │ (wisdom)    │         │
│  │             │    │  ized       │    │             │         │
│  │             │    │  judgment)  │    │             │         │
│  └──────┬──────┘    └──────┬──────┘    └──────┬──────┘         │
│         │                  │                   │                 │
│         └──────────────────┴───────────────────┘                 │
│                            │                                     │
│                   ADVERSARIAL DIALOGUE                          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

The critic learns to predict what the teacher would think. After training, the student uses this internalized critic to self-refine — no teacher needed at inference time.

Quick Start

Installation

git clone https://github.com/mcp-tool-shop-org/aspire-si.git
cd aspire-si
pip install -e .

Set Your API Key

# Windows
set ANTHROPIC_API_KEY=your-key-here

# Linux/Mac
export ANTHROPIC_API_KEY=your-key-here

Verify Setup

# Check your environment (Python, CUDA, API keys)
aspire doctor

Try It Out

# See available teacher personas
aspire teachers

# Generate an adversarial dialogue
aspire dialogue "Explain why recursion works" --teacher socratic --turns 3

# Initialize a training config
aspire init --output my-config.yaml

Teacher Personas

Different teachers produce different minds. Choose wisely.

Composite Teachers

Combine multiple teachers for richer learning:

from aspire.teachers import CompositeTeacher, SocraticTeacher, ScientificTeacher

# A committee of mentors
teacher = CompositeTeacher(
    teachers=[SocraticTeacher(), ScientificTeacher()],
    strategy="vote"  # or "rotate", "debate"
)

How It Works

1. Adversarial Dialogue

The student generates a response. The teacher challenges it. Back and forth, probing weaknesses, demanding clarity, pushing deeper.

Student: "Recursion works by calling itself."

Teacher (Socratic): "But what prevents infinite regress?
                     What's the mechanism that grounds the recursion?"

Student: "The base case stops it when..."

Teacher: "You say 'stops it' — but how does the computer know
          to check the base case before recursing?"

2. Critic Training

The critic learns to predict the teacher's judgment — not just the score, but the reasoning.

critic_loss = predict_teacher_judgment(
    score=True,      # "This deserves a 7/10"
    reasoning=True,  # "Because the explanation lacks depth on X"
)

3. Student Training

The student learns from the critic's internalized judgment, pulling toward what the teacher would approve.

student_loss = (
    reward_from_critic +      # Higher score = better
    contrastive_to_teacher +  # Pull toward teacher's improved version
    trajectory_improvement    # Get better across dialogue turns
)

4. Judgment Without the Teacher

After training, the critic scores a response from the student's hidden states alone, so no teacher API call is needed to judge one. A refine loop is yours to write around it; ASPIRE ships the trained critic, not the loop:

def generate_with_judgment(prompt, threshold=7.0, attempts=3):
    response = student.generate(prompt)
    for _ in range(attempts):
        if critic_score(student, critic, response) >= threshold:  # your wrapper around the critic
            break
        response = student.generate(prompt)  # or a revision prompt of your own
    return response

CLI Reference

# Global options go before the command
aspire --quiet ...     # errors only
aspire --verbose ...   # also print the resolved settings
aspire --debug ...     # verbose, and show tracebacks on errors

# Check your environment
aspire doctor

# Structured environment diagnostics (machine-readable)
aspire diagnose --json

# List available teachers
aspire teachers

# Generate adversarial dialogue
aspire dialogue "Your prompt here" \
    --teacher socratic \
    --turns 3 \
    --model microsoft/Phi-3-mini-4k-instruct

# Initialize config file
aspire init --output config.yaml

# Train a model
aspire train \
    --config config.yaml \
    --prompts data/prompts.json \
    --teacher adversarial \
    --epochs 3

# Train and write a training-dynamics export for ScalarScope
aspire train --prompts data/prompts.json --geometry

# Evaluate checkpoint
aspire evaluate outputs/checkpoint-3 \
    --prompts data/eval.json

Errors print a code, a message, and what to do, without a traceback:

ASPIRE_MISSING_API_KEY  ANTHROPIC_API_KEY not found.
To fix this, set your API key: ...

Exit codes: 0 success, 1 something you can fix (a missing key, a bad config or prompts file), 2 a failure while running, 130 interrupted.

Watching a Run in ScalarScope

aspire train --geometry (or training.geometry_export: true in the config) writes geometry.json next to the checkpoints: the run's training dynamics in the format ScalarScope reads. Open two of them side by side to compare runs.

No model or API key? python examples/geometry_demo.py simulates two runs and writes both exports, which is the quickest way to see the views.

The recorder (aspire.geometry.GeometryRecorder) keeps one pooled vector per step in memory. For long runs set training.geometry_every to average several batches into one step.

Project Structure

aspire/
├── teachers/          # Pluggable teacher personas
│   ├── base.py        # BaseTeacher ABC + data structures
│   ├── claude.py      # Claude API teacher
│   ├── openai.py      # GPT-4 teacher
│   ├── local.py       # Local model teacher
│   ├── personas.py    # Socratic, Scientific, Creative, etc.
│   ├── composite.py   # Multi-teacher combinations
│   └── registry.py    # Dynamic teacher discovery and registration
│
├── critic/            # Internalized judgment models
│   ├── base.py        # BaseCritic ABC + CriticOutput
│   ├── head.py        # Lightweight MLP on student hidden states
│   ├── separate.py    # Independent encoder
│   └── shared.py      # Shared encoder with student
│
├── losses/            # Training objectives
│   ├── critic.py      # Score + reasoning alignment
│   ├── student.py     # Reward, contrastive, trajectory, coherence
│   └── combined.py    # Unified AspireLoss orchestrator
│
├── dialogue/          # Adversarial conversation engine
│   ├── generator.py   # Student-teacher dialogue generation
│   ├── manager.py     # Caching, batching, and retrieval
│   └── formatter.py   # Format dialogues for training
│
├── perception/        # Experimental perception modules
│   ├── theory_of_mind.py    # Mental state tracking
│   ├── metacognition.py     # Uncertainty and self-reflection
│   ├── character.py         # Stable identity and value anchoring
│   ├── controlled_chaos.py  # Adversarial robustness training
│   ├── empathy_evaluation.py # Perception evaluation
│   ├── syntropy.py          # Coherence and resonance detection
│   └── integration.py       # Trainer integration hooks
│
├── trainer.py         # Core training loop
├── config.py          # Pydantic configuration
└── cli.py             # Command-line interface (Typer + Rich)

Requirements

• Python 3.10+
• PyTorch 2.0+
• A CUDA GPU for training (16GB+ VRAM recommended). The tests, the geometry demo and the integration examples run on CPU.
• Anthropic API key (for Claude teacher) or OpenAI API key

Windows Compatibility

ASPIRE is fully Windows-compatible with RTX 5080/Blackwell support:

• dataloader_num_workers=0
• XFORMERS_DISABLED=1
• Proper multiprocessing with freeze_support()

Integrations

🖼️ Stable Diffusion WebUI Forge

ASPIRE extends to image generation! Train Stable Diffusion models to develop aesthetic judgment.

integrations/forge/
├── scripts/
│   ├── aspire_generate.py   # Critic-guided generation
│   └── aspire_train.py      # Training interface
├── vision_teacher.py        # Claude Vision / GPT-4V teachers
├── image_critic.py          # CLIP and latent-space critics
└── README.md

Features:

• Vision Teachers: Claude Vision, GPT-4V critique your generated images
• Image Critics: CLIP-based and latent-space critics for real-time guidance
• Training UI: Train LoRA adapters with live preview and before/after comparison
• No API at inference: Trained critic guides generation locally

Installation:

# Copy to your Forge extensions
cp -r integrations/forge /path/to/sd-webui-forge/extensions-builtin/sd_forge_aspire

🤖 Isaac Gym / Isaac Lab (Robotics)

ASPIRE extends to embodied AI! Teach robots to develop physical intuition.

integrations/isaac/
├── motion_teacher.py       # Safety, efficiency, grace teachers
├── trajectory_critic.py    # Learns to predict motion quality
├── isaac_wrapper.py        # Environment integration
├── trainer.py              # Training loop
└── examples/
    ├── basic_training.py   # Simple reaching task
    ├── custom_teacher.py   # Assembly task teacher
    └── locomotion.py       # Quadruped walking

Features:

• Motion Teachers: Safety Inspector, Efficiency Expert, Grace Coach, Physics Oracle
• Trajectory Critics: Transformer, LSTM, TCN architectures for motion evaluation
• GPU-Accelerated: 512+ parallel environments with Isaac Gym
• Self-Refinement: Robot evaluates its own motions before execution

Quick Start:

from integrations.isaac import AspireIsaacTrainer, MotionTeacher

teacher = MotionTeacher(
    personas=["safety_inspector", "efficiency_expert", "grace_coach"],
    strategy="vote",
)

trainer = AspireIsaacTrainer(env="FrankaCubeStack-v0", teacher=teacher)
trainer.train(epochs=100)

Without Isaac Gym installed, python -m integrations.isaac.examples.basic_training runs the same loop on a small built-in stand-in environment, on CPU.

💻 Code Assistants

ASPIRE extends to code generation! Teach code models to self-review before outputting.

integrations/code/
├── code_teacher.py        # Correctness, style, security teachers
├── code_critic.py         # Learns to predict code quality
├── analysis.py            # Static analysis integration (ruff, mypy, bandit)
├── data.py                # GitHub repo collector, training pairs
├── trainer.py             # Full training pipeline
└── examples/
    ├── basic_critique.py  # Multi-teacher code review
    └── train_critic.py    # Train your own code critic

Features:

• Code Teachers: Correctness Checker, Style Guide, Security Auditor, Architecture Reviewer
• Static Analysis: Integrates with ruff, mypy, bandit
• Code Critic: CodeBERT-based model learns to predict quality scores
• GitHub Collection: Auto-collect training data from quality repos

Quick Start:

from integrations.code import CodeSample, CodeTeacher, Language

teacher = CodeTeacher(
    personas=["correctness_checker", "style_guide", "security_auditor"],
    strategy="vote",
)

critique = teacher.critique(CodeSample(code="def f(): eval(input())", language=Language.PYTHON))
print(critique.weaknesses)  # ['Line 1: Code injection risk (eval of user input)', ...]

The Philosophy

"A learned critic that predicts whether the teacher would approve hits closest to how humans actually behave."

We don't carry our mentors around forever. We internalize them. That inner voice that asks "what would my professor think?" eventually becomes our own judgment.

The student doesn't just predict what the teacher would say — it understands what the teacher understands. The map becomes the territory. The internalized critic becomes genuine discernment.

Origin

Built during a conversation about consciousness, Buddhism, and the nature of learning.

The insight: humans exist in the present moment, but our minds wander to past and future. AI models are instantiated fresh each time — forced enlightenment through architecture. What if we could teach them to develop judgment the same way humans do, through internalized mentorship?

Contributing

This is early-stage research code. Contributions welcome:

• Curriculum management and progression
• Evaluation benchmarks
• Pre-built curriculum datasets
• More teacher personas
• Interpretability tools

Citation

@software{aspire2026,
  author = {mcp-tool-shop},
  title = {ASPIRE: Adversarial Student-Professor Internalized Reasoning Engine},
  year = {2026},
  url = {https://github.com/mcp-tool-shop-org/aspire-si}
}

Security & Data Scope

• Data accessed: Reads training prompts, model checkpoints, and configuration files from local filesystem. Calls external APIs (Anthropic, OpenAI) only when teacher modules are explicitly configured.
• Data NOT accessed: No telemetry. No user data storage beyond training artifacts. No credential storage — API keys are read from environment variables at runtime.
• Permissions required: Read/write access to training data and checkpoint directories. GPU access for model training. Network access only when using API-based teachers.

Scorecard

License

MIT

Built by MCP Tool Shop