ValiScore API Documentation

calculate_bleu

Calculates the BLEU score for a candidate sentence against a reference sentence.

Parameters

Parameter	Type	Description
reference	str	Reference text to compare against
candidate	str	Candidate text to score

Returns

BLEU score between 0 and 1

Example

from valiscore import calculate_bleu

reference = "The quick brown fox jumps over the lazy dog"
candidate = "A quick brown fox jumps over a lazy dog"

score = calculate_bleu(reference, candidate)
print(f"BLEU Score: {score:.3f}")  # Output: BLEU Score: 0.857

calculate_rouge

Calculates ROUGE scores (ROUGE-1, ROUGE-2, ROUGE-L) for a candidate against a reference.

Returns

Dictionary containing ROUGE-1, ROUGE-2, and ROUGE-L scores

Example

from valiscore import calculate_rouge

reference = "The quick brown fox jumps over the lazy dog"
candidate = "A quick brown fox jumps over a lazy dog"

scores = calculate_rouge(reference, candidate)
print(f"ROUGE-1: {scores['rouge1']:.3f}")
print(f"ROUGE-2: {scores['rouge2']:.3f}")
print(f"ROUGE-L: {scores['rougeL']:.3f}")

shapley_value

Calculates Shapley values for fair contribution distribution among multiple participants.

Example

from valiscore import shapley_value, simple_characteristic_function

contributions = [0.8, 0.6, 0.9]
shapley_values = shapley_value(contributions, simple_characteristic_function)
print(f"Shapley Values: {shapley_values}")

ScoringEngine

Main engine for calculating multiple scoring metrics with configurable weights.

Example

from valiscore import ScoringEngine

engine = ScoringEngine()
engine.set_weights({
    'bleu': 0.4,
    'rouge1': 0.3,
    'rouge2': 0.2,
    'rougeL': 0.1
})

scores = engine.score_responses(
    reference="The answer is 42",
    responses=["The answer is 42", "It's 42", "42 is the answer"]
)

print(f"Individual Scores: {scores['individual_scores']}")
print(f"Weighted Score: {scores['weighted_score']:.3f}")

ValidatorAnalyzer

Comprehensive validator analysis using real Bittensor blockchain data.

Methods

Example

import asyncio
from valiscore import ValidatorAnalyzer

async def comprehensive_analysis():
    analyzer = ValidatorAnalyzer(network="finney")
    
    # Analyze subnet
    analysis = await analyzer.analyze_subnet(netuid=1)
    
    # Print results
    print(f"Subnet Analysis Results:")
    print(f"  Validators: {analysis['validator_count']}")
    print(f"  Active: {analysis['active_validators']}")
    print(f"  Total Stake: {analysis['total_stake']:.2f} TAO")
    print(f"  Performance: {analysis['average_performance']:.3f}")
    
    # Show insights
    for insight in analysis['insights']:
        print(f"  💡 {insight}")
    
    # Export results
    await analyzer.export_analysis(netuid=1, output_path="analysis.json")
    
    analyzer.disconnect()

asyncio.run(comprehensive_analysis())

BittensorClient

Direct integration with Bittensor blockchain for real-time data access.

Methods

Example

import asyncio
from valiscore import BittensorClient

async def get_subnet_data():
    client = BittensorClient(network="finney")
    
    # Get subnet information
    subnet_info = await client.get_subnet_info(netuid=1)
    print(f"Subnet: {subnet_info.name}")
    print(f"Modality: {subnet_info.modality}")
    
    # Get validators
    validators = await client.get_validators(netuid=1)
    print(f"Found {len(validators)} validators")
    
    # Get miner responses
    responses = await client.get_miner_responses(netuid=1)
    print(f"Found {len(responses)} miner responses")
    
    client.disconnect()

asyncio.run(get_subnet_data())

ValiScoreMCPServer

Model Context Protocol server for AI assistant integration.

Available Tools

• analyze_subnet - Analyze Bittensor subnet with real blockchain data
• compare_subnets - Compare multiple subnets side-by-side
• score_responses - Score multiple responses using BLEU, ROUGE metrics
• calculate_shapley - Calculate Shapley values for fair contribution distribution
• monitor_subnet - Real-time subnet monitoring
• export_analysis - Export results to JSON, CSV, HTML formats

Example

import asyncio
from mcp import ClientSession, StdioServerParameters

async def mcp_example():
    async with ClientSession(
        StdioServerParameters(
            command="valiscore-cli",
            args=["mcp-server"]
        )
    ) as session:
        
        # List available tools
        tools = await session.list_tools()
        print(f"Available tools: {[tool.name for tool in tools.tools]}")
        
        # Analyze a subnet
        result = await session.call_tool(
            "analyze_subnet",
            {"subnet_id": 1, "network": "finney"}
        )
        print(f"Analysis result: {result.content[0].text}")

asyncio.run(mcp_example())

Subnet Comparison

import asyncio
from valiscore import SubnetComparison

async def compare_subnets():
    comparison = SubnetComparison(network="finney")
    
    # Compare text prompting (1) and image generation (2) subnets
    results = await comparison.compare_subnets([1, 2])
    
    print("🏆 Performance Ranking:")
    for subnet_name, score in results['comparison_metrics']['performance_ranking']:
        print(f"  {subnet_name}: {score:.3f}")
    
    comparison.disconnect()

asyncio.run(compare_subnets())

Real-time Monitoring

import asyncio
from valiscore import ValidatorAnalyzer

async def monitor_subnet():
    analyzer = ValidatorAnalyzer(network="finney")
    
    async def callback(analysis):
        print(f"🔄 Update: {analysis['validator_count']} validators, "
              f"Performance: {analysis['average_performance']:.3f}")
    
    # Monitor subnet 1 every 30 seconds
    await analyzer.monitor_subnet(netuid=1, callback=callback, interval=30)

asyncio.run(monitor_subnet())