brainwires-prompting

Adaptive prompting techniques, task clustering, and temperature optimization for the Brainwires Agent Framework.

Overview

brainwires-prompting implements the research from "Adaptive Selection of Prompting Techniques" (arXiv:2510.18162). It provides 15 proven prompting techniques organized into 4 categories, semantic task clustering to match tasks to optimal techniques, a multi-source selection pipeline (PKS > BKS > cluster default), adaptive temperature optimization, and a learning coordinator that promotes effective patterns to the Behavioral Knowledge System.

Design principles:

• Research-backed — all 15 techniques drawn from the academic paper, with SEAL quality thresholds for each
• Multi-source selection — cascading priority: user preferences (PKS), shared knowledge (BKS), cluster defaults
• Self-improving — effectiveness tracking with automatic BKS promotion when reliability thresholds are met
• WASM-compatible — the wasm feature disables k-means clustering and SQLite storage

  ┌──────────────────────────────────────────────────────────────┐
  │                    brainwires-prompting                       │
  │                                                              │
  │  ┌──────────┐     ┌──────────────┐     ┌─────────────────┐  │
  │  │  Task +  │────►│  Clustering  │────►│    Library       │  │
  │  │  SEAL    │     │  (k-means)   │     │  (15 techniques) │  │
  │  └──────────┘     └──────────────┘     └────────┬────────┘  │
  │                                                  │           │
  │                   ┌──────────────┐     ┌─────────▼────────┐  │
  │                   │  Temperature │────►│   Generator      │  │
  │                   │  Optimizer   │     │  (PKS>BKS>cluster)│  │
  │                   └──────┬───────┘     └─────────┬────────┘  │
  │                          │                       │           │
  │                          │           ┌───────────▼────────┐  │
  │                          │           │  GeneratedPrompt   │  │
  │                          │           │  (system_prompt +  │  │
  │                          │           │   techniques +     │  │
  │                          │           │   temperature)     │  │
  │                          │           └────────────────────┘  │
  │                          │                       │           │
  │                   ┌──────▼───────────────────────▼────────┐  │
  │                   │        Learning Coordinator           │  │
  │                   │  (effectiveness → BKS promotion)      │  │
  │                   └──────────────────┬────────────────────┘  │
  │                                      │                       │
  │                   ┌──────────────────▼────────────────────┐  │
  │                   │        Storage (SQLite)               │  │
  │                   │  clusters · technique perf · temp perf│  │
  │                   └───────────────────────────────────────┘  │
  └──────────────────────────────────────────────────────────────┘

Quick Start

Add to your Cargo.toml:

[dependencies]
brainwires-prompting = "0.1"

Generate an adaptive prompt for a task:

use brainwires_prompting::{
    PromptGenerator, TechniqueLibrary, TaskClusterManager, SealProcessingResult,
};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let library = TechniqueLibrary::new();
    let clusters = TaskClusterManager::new();
    let generator = PromptGenerator::new(library, clusters);

    let seal = SealProcessingResult {
        quality_score: 0.85,
        resolved_query: "Implement a binary search tree in Rust".into(),
    };

    let prompt = generator.generate_prompt(
        "Implement a binary search tree",
        &[],  // task embedding
        Some(&seal),
    ).await;

    println!("System prompt: {}", prompt.system_prompt);
    println!("Techniques: {:?}", prompt.techniques);
    println!("SEAL quality: {}", prompt.seal_quality);

    Ok(())
}

Features

# Default (native with clustering + storage)
brainwires-prompting = "0.1"

# WASM target
brainwires-prompting = { version = "0.1", default-features = false, features = ["wasm"] }

Architecture

Prompting Techniques

15 techniques organized into 4 categories, each with metadata, templates, and SEAL quality thresholds.

TechniqueCategory variants:

ComplexityLevel mapping (from SEAL quality):

TaskCharacteristic variants: MultiStepReasoning, NumericalCalculation, LogicalDeduction, CreativeGeneration, LongContextSummarization, SpatialReasoning, VisualUnderstanding, CodeGeneration, AlgorithmicProblem

TechniqueMetadata fields:

Task Clustering

Semantic clustering with SEAL-boosted similarity matching and optional k-means.

TaskCluster fields:

TaskClusterManager key methods:

Helper functions:

Technique Library

Complete library of all 15 techniques with BKS integration.

use brainwires_prompting::{TechniqueLibrary, TechniqueCategory};

let library = TechniqueLibrary::new();

// Get all reasoning techniques
let reasoning = library.get_by_category(TechniqueCategory::Reasoning);

// Get techniques suitable for a SEAL quality score
let suitable = library.get_by_seal_quality(0.75);

// Get BKS-recommended techniques for a cluster
let recommended = library.get_bks_recommended_techniques("code-generation");

Key methods:

Prompt Generator

Multi-source selection pipeline that composes techniques into a final prompt.

Selection priority (cascading):

1. PKS (Personal Knowledge) — user-specific technique preferences
2. BKS (Behavioral Knowledge) — collective learned effectiveness
3. Cluster default — techniques mapped to the matched cluster

Selection rules (from the paper):

• Always includes one RoleAssignment technique (RolePlaying)
• Selects one EmotionalStimulus technique, filtered by SEAL quality
• Selects one Reasoning technique, matched to complexity level
• Optionally selects Others techniques if SEAL quality > 0.6

PromptGenerator methods:

GeneratedPrompt fields:

Template substitution heuristics:

Learning Coordinator

Tracks technique effectiveness and promotes high-performing patterns to BKS.

TechniqueStats fields:

Key methods:

PromptingLearningCoordinator methods:

Promotion thresholds (configurable):

ClusterSummary methods:

Temperature Optimizer

Adaptive temperature selection per cluster based on the paper's findings.

Paper findings:

Candidate temperatures: [0.0, 0.2, 0.4, 0.6, 0.8, 1.0, 1.3]

TemperaturePerformance scoring:

Combined score = 60% success_rate + 40% avg_quality (both tracked via EMA with alpha=0.3).

Selection cascade (get_optimal_temperature()):

1. Query BKS for shared temperature knowledge
2. Use local learned optimal (if ≥ min_samples data points)
3. Fall back to heuristic based on cluster description keywords

TemperatureOptimizer methods:

Heuristic fallbacks:

SEAL Integration

Stub types for Self-Explanatory Adaptive Learning quality scores.

SealProcessingResult fields:

SEAL quality drives technique selection, cluster matching boosts, and complexity level inference throughout the system.

Storage (native only)

SQLite persistence for clusters and performance data.

Tables:

ClusterStorage methods:

Usage Examples

Technique Discovery

use brainwires_prompting::{
    TechniqueLibrary, TechniqueCategory, PromptingTechnique, ComplexityLevel,
};

let library = TechniqueLibrary::new();

// Browse techniques by category
let reasoning = library.get_by_category(TechniqueCategory::Reasoning);
for meta in &reasoning {
    println!("{}: {}", meta.name, meta.description);
}

// Filter by SEAL quality
let advanced = library.get_by_seal_quality(0.85);
for meta in &advanced {
    println!("{} (min SEAL: {})", meta.name, meta.min_seal_quality);
}

Task Clustering and Matching

use brainwires_prompting::{TaskClusterManager, TaskCluster, SealProcessingResult, cosine_similarity};

let mut manager = TaskClusterManager::new();

// Add a pre-defined cluster
let cluster = TaskCluster {
    id: "code-generation".into(),
    description: "Code generation and implementation tasks".into(),
    embedding: vec![0.1, 0.2, 0.3], // simplified
    techniques: vec![],
    example_tasks: vec!["Implement a REST API".into()],
    ..Default::default()
};
manager.add_cluster(cluster);

// Match a task to a cluster
let seal = SealProcessingResult {
    quality_score: 0.9,
    resolved_query: "Build a REST endpoint".into(),
};
let task_embedding = vec![0.15, 0.22, 0.28];

if let Some((cluster, score)) = manager.find_matching_cluster(&task_embedding, Some(&seal)) {
    println!("Matched: {} (similarity: {:.2})", cluster.id, score);
}

Effectiveness Tracking and BKS Promotion

use brainwires_prompting::{
    PromptingLearningCoordinator, PromptingTechnique, TechniqueEffectivenessRecord,
};
use chrono::Utc;

let mut coordinator = PromptingLearningCoordinator::new();

// Record outcomes as agents complete tasks
for i in 0..6 {
    coordinator.record_outcome(TechniqueEffectivenessRecord {
        technique: PromptingTechnique::ChainOfThought,
        cluster_id: "algorithm-design".into(),
        task_description: format!("Algorithm task {}", i),
        success: i < 5,  // 5/6 = 83% success
        iterations_used: 8,
        quality_score: 0.85,
        timestamp: Utc::now(),
    });
}

// Check if technique qualifies for BKS promotion
if coordinator.should_promote("algorithm-design", PromptingTechnique::ChainOfThought) {
    coordinator.promote_technique_to_bks(
        "algorithm-design",
        PromptingTechnique::ChainOfThought,
    ).await?;
}

// Or promote all eligible techniques at once
coordinator.check_and_promote_all().await?;

Temperature Optimization

use brainwires_prompting::TemperatureOptimizer;

let mut optimizer = TemperatureOptimizer::new();

// Record outcomes for different temperatures
optimizer.record_temperature_outcome("code-generation", 0.6, true, 0.9);
optimizer.record_temperature_outcome("code-generation", 0.6, true, 0.85);
optimizer.record_temperature_outcome("code-generation", 0.8, false, 0.4);

// Get optimal temperature (uses cascade: BKS → learned → heuristic)
let temp = optimizer.get_optimal_temperature("code-generation").await;
println!("Optimal temperature: {}", temp); // likely 0.6 based on recorded data

// Promote to BKS if criteria met
optimizer.check_and_promote_temperature("code-generation", 0.6).await?;

Full Pipeline with BKS/PKS

use brainwires_prompting::{
    PromptGenerator, TechniqueLibrary, TaskClusterManager, SealProcessingResult,
};
use brainwires_brain::knowledge::{BehavioralKnowledgeCache, PersonalKnowledgeCache};

let library = TechniqueLibrary::new();
let clusters = TaskClusterManager::new();

let mut generator = PromptGenerator::new(library, clusters);

// Integrate knowledge systems for multi-source selection
let bks = BehavioralKnowledgeCache::new();
let pks = PersonalKnowledgeCache::new();
generator = generator.with_bks(bks).with_pks(pks);

let seal = SealProcessingResult {
    quality_score: 0.82,
    resolved_query: "Design a concurrent hash map with fine-grained locking".into(),
};

let prompt = generator.generate_prompt(
    "Design a concurrent hash map",
    &[],  // task embedding
    Some(&seal),
).await;

// Use the generated prompt as a system message
println!("Techniques selected: {:?}", prompt.techniques);
println!("Cluster: {:?}", prompt.cluster_id);
println!("System prompt:\n{}", prompt.system_prompt);

Integration with Brainwires

Use via the brainwires facade crate:

[dependencies]
brainwires = "0.1"

Or use standalone — brainwires-prompting depends on brainwires-core and optionally on brainwires-brain for knowledge integration (BKS/PKS). The knowledge systems live in brainwires-brain; this crate re-exports them behind the knowledge feature.

License

Licensed under either of Apache License, Version 2.0 or MIT License at your option.