API Documentation

Comprehensive API Reference for Fuzzy-Bayesian Evidence Processing

Complete documentation for all endpoints, including the revolutionary fuzzy evidence integration system

API Overview

Base URL

https://api.hegel-bio.org/v1

Authentication

All API requests require JWT authentication via the Authorization header:

Authorization: Bearer <your-jwt-token>

Content Type

Content-Type: application/json

Fuzzy Evidence Endpoints

Revolutionary fuzzy-Bayesian evidence processing endpoints that handle continuous, uncertain biological evidence

POST /fuzzy-evidence/integrate

Hybrid Fuzzy-Bayesian Evidence Integration

Integrates multiple evidence sources using fuzzy logic and Bayesian inference for enhanced confidence scoring.

Request Body

{
  "molecule_id": "MOL_12345",
  "evidence_list": [
    {
      "type": "spectral_match",
      "value": 0.85,
      "uncertainty": 0.1,
      "timestamp": "2024-01-15T10:30:00Z",
      "source": "NIST_MS_DB",
      "metadata": {
        "spectrum_quality": "high",
        "peak_count": 45
      }
    },
    {
      "type": "sequence_similarity",
      "value": 0.72,
      "uncertainty": 0.15,
      "timestamp": "2024-01-15T10:25:00Z",
      "source": "UniProt",
      "metadata": {
        "alignment_score": 156.2,
        "e_value": 1e-12
      }
    }
  ],
  "fuzzy_config": {
    "membership_functions": {
      "spectral_match": "gaussian",
      "sequence_similarity": "triangular"
    },
    "linguistic_variables": ["very_low", "low", "medium", "high", "very_high"],
    "temporal_decay_enabled": true,
    "decay_half_life_days": 30
  },
  "objective_weights": {
    "maximize_confidence": 0.4,
    "minimize_uncertainty": 0.3,
    "maximize_consistency": 0.2,
    "minimize_conflicts": 0.1
  }
}

Response

{
  "molecule_id": "MOL_12345",
  "fuzzy_confidence": {
    "overall_score": 0.78,
    "uncertainty_bounds": [0.65, 0.91],
    "linguistic_assessment": {
      "very_low": 0.0,
      "low": 0.1,
      "medium": 0.2,
      "high": 0.6,
      "very_high": 0.1
    }
  },
  "evidence_analysis": {
    "individual_contributions": [
      {
        "type": "spectral_match",
        "fuzzy_membership": {
          "high": 0.8,
          "very_high": 0.2
        },
        "temporal_weight": 0.95,
        "contribution_score": 0.42
      },
      {
        "type": "sequence_similarity",
        "fuzzy_membership": {
          "medium": 0.4,
          "high": 0.6
        },
        "temporal_weight": 0.96,
        "contribution_score": 0.36
      }
    ],
    "evidence_relationships": [
      {
        "source": "spectral_match",
        "target": "sequence_similarity",
        "relationship_type": "supports",
        "strength": 0.65
      }
    ]
  },
  "network_statistics": {
    "coherence_score": 0.82,
    "consistency_score": 0.75,
    "conflict_score": 0.12
  },
  "objective_optimization": {
    "total_score": 0.78,
    "component_scores": {
      "maximize_confidence": 0.81,
      "minimize_uncertainty": 0.73,
      "maximize_consistency": 0.75,
      "minimize_conflicts": 0.88
    }
  },
  "processing_metadata": {
    "processing_time_ms": 245,
    "algorithm_version": "1.0.0",
    "timestamp": "2024-01-15T10:35:00Z"
  }
}
GET /fuzzy-evidence/network-stats/{molecule_id}

Evidence Network Statistics

Retrieves comprehensive statistics about the evidence network for a specific molecule.

Path Parameters

molecule_id (string): Unique identifier for the molecule

Query Parameters

include_predictions (boolean, optional): Include missing evidence predictions (default: false)
temporal_window_days (integer, optional): Time window for evidence analysis (default: 90)

Response

{
  "molecule_id": "MOL_12345",
  "network_topology": {
    "node_count": 8,
    "edge_count": 12,
    "density": 0.43,
    "clustering_coefficient": 0.67
  },
  "evidence_distribution": {
    "very_low": 1,
    "low": 2,
    "medium": 3,
    "high": 2,
    "very_high": 0
  },
  "relationship_analysis": {
    "supports": 7,
    "contradicts": 1,
    "corroborates": 3,
    "implies": 1,
    "requires": 0
  },
  "temporal_analysis": {
    "evidence_age_distribution": {
      "0-7_days": 3,
      "8-30_days": 4,
      "31-90_days": 1
    },
    "decay_impact": 0.15
  },
  "coherence_metrics": {
    "overall_coherence": 0.82,
    "consistency_score": 0.75,
    "conflict_resolution_score": 0.88
  }
}
POST /fuzzy-evidence/predict-evidence/{molecule_id}

Missing Evidence Prediction

Predicts likely evidence values based on network structure and partial observations.

Request Body

{
  "evidence_types_to_predict": [
    "pathway_membership",
    "protein_interaction"
  ],
  "prediction_config": {
    "confidence_threshold": 0.6,
    "max_predictions": 10,
    "include_uncertainty": true,
    "network_learning_enabled": true
  },
  "context_evidence": [
    {
      "type": "spectral_match",
      "value": 0.85,
      "uncertainty": 0.1
    }
  ]
}

Response

{
  "molecule_id": "MOL_12345",
  "predictions": [
    {
      "evidence_type": "pathway_membership",
      "predicted_value": 0.73,
      "uncertainty_bounds": [0.58, 0.88],
      "confidence": 0.82,
      "supporting_evidence": [
        {
          "type": "spectral_match",
          "influence_weight": 0.65
        }
      ],
      "network_path": [
        "spectral_match",
        "sequence_similarity",
        "pathway_membership"
      ]
    }
  ],
  "network_learning": {
    "new_relationships_discovered": 2,
    "relationship_strength_updates": 5,
    "network_coherence_improvement": 0.08
  },
  "prediction_metadata": {
    "algorithm": "fuzzy_network_inference",
    "processing_time_ms": 156,
    "timestamp": "2024-01-15T10:40:00Z"
  }
}
POST /fuzzy-evidence/optimize-objective/{molecule_id}

Multi-Criteria Objective Optimization

Optimizes evidence assessment using weighted objective functions for different research priorities.

Request Body

{
  "optimization_config": {
    "objectives": {
      "maximize_confidence": 0.3,
      "minimize_uncertainty": 0.25,
      "maximize_consistency": 0.2,
      "minimize_conflicts": 0.15,
      "maximize_network_coherence": 0.1
    },
    "constraints": {
      "min_evidence_count": 3,
      "max_uncertainty": 0.3,
      "temporal_window_days": 60
    },
    "optimization_method": "pareto_frontier"
  },
  "evidence_weights": {
    "spectral_match": 1.0,
    "sequence_similarity": 0.8,
    "pathway_membership": 0.6
  }
}

Response

{
  "molecule_id": "MOL_12345",
  "optimization_results": {
    "optimal_score": 0.84,
    "pareto_solutions": [
      {
        "solution_id": 1,
        "total_score": 0.84,
        "objective_scores": {
          "maximize_confidence": 0.89,
          "minimize_uncertainty": 0.76,
          "maximize_consistency": 0.82,
          "minimize_conflicts": 0.91,
          "maximize_network_coherence": 0.78
        },
        "evidence_configuration": {
          "active_evidence_types": ["spectral_match", "sequence_similarity"],
          "fuzzy_parameters": {
            "membership_function": "gaussian",
            "linguistic_granularity": 5
          }
        }
      }
    ]
  },
  "sensitivity_analysis": {
    "objective_sensitivity": {
      "maximize_confidence": 0.23,
      "minimize_uncertainty": 0.18
    },
    "parameter_sensitivity": {
      "temporal_decay": 0.12,
      "membership_function_type": 0.08
    }
  },
  "recommendations": [
    {
      "type": "evidence_collection",
      "description": "Collect additional pathway membership evidence to improve consistency",
      "priority": "high",
      "expected_improvement": 0.15
    }
  ]
}
GET /fuzzy-evidence/linguistic-variables

Available Fuzzy Linguistic Variables

Returns the available fuzzy linguistic variables and their membership function definitions.

Response

{
  "linguistic_variables": {
    "confidence_levels": [
      {
        "name": "very_low",
        "range": [0.0, 0.2],
        "membership_function": {
          "type": "triangular",
          "parameters": [0.0, 0.0, 0.2]
        },
        "description": "Minimal evidence support"
      },
      {
        "name": "low",
        "range": [0.1, 0.4],
        "membership_function": {
          "type": "triangular",
          "parameters": [0.1, 0.25, 0.4]
        },
        "description": "Weak evidence support"
      },
      {
        "name": "medium",
        "range": [0.3, 0.7],
        "membership_function": {
          "type": "triangular",
          "parameters": [0.3, 0.5, 0.7]
        },
        "description": "Moderate evidence support"
      },
      {
        "name": "high",
        "range": [0.6, 0.9],
        "membership_function": {
          "type": "triangular",
          "parameters": [0.6, 0.75, 0.9]
        },
        "description": "Strong evidence support"
      },
      {
        "name": "very_high",
        "range": [0.8, 1.0],
        "membership_function": {
          "type": "triangular",
          "parameters": [0.8, 1.0, 1.0]
        },
        "description": "Maximal evidence support"
      }
    ]
  },
  "membership_function_types": [
    {
      "name": "triangular",
      "parameters": ["left", "center", "right"],
      "description": "Triangular membership function for evidence with clear boundaries"
    },
    {
      "name": "gaussian",
      "parameters": ["center", "sigma"],
      "description": "Gaussian membership function for normally distributed evidence"
    },
    {
      "name": "trapezoidal",
      "parameters": ["left", "left_top", "right_top", "right"],
      "description": "Trapezoidal membership function for evidence with plateau regions"
    },
    {
      "name": "sigmoid",
      "parameters": ["center", "slope"],
      "description": "Sigmoid membership function for evidence with sharp transitions"
    }
  ],
  "fuzzy_operations": {
    "t_norms": ["minimum", "product", "lukasiewicz"],
    "s_norms": ["maximum", "probabilistic", "lukasiewicz"],
    "defuzzification": ["centroid", "weighted_average", "maximum"]
  }
}

Traditional Evidence Endpoints

Standard molecular evidence processing endpoints for compatibility with existing systems

POST /molecules/analyze

Molecule Analysis

Analyzes molecular evidence using traditional binary classification methods.

GET /molecules/{molecule_id}

Get Molecule Information

Retrieves detailed information about a specific molecule.

POST /evidence/rectify

Evidence Rectification

Rectifies conflicting evidence using traditional algorithmic approaches.

Authentication

POST /auth/login

User Login

Authenticate user and obtain JWT token.

Request Body

{
  "username": "researcher@university.edu",
  "password": "secure_password"
}

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600,
  "user": {
    "id": "user_123",
    "username": "researcher@university.edu",
    "role": "researcher",
    "organization": "University Research Lab"
  }
}
GET /auth/users/me

Get Current User

Retrieve information about the currently authenticated user.

Usage Examples

Python Example - Fuzzy Evidence Integration

import requests
import json

# Authentication
auth_response = requests.post('https://api.hegel-bio.org/v1/auth/login', 
    json={
        'username': 'researcher@university.edu',
        'password': 'secure_password'
    })
token = auth_response.json()['access_token']

# Fuzzy evidence integration
evidence_data = {
    "molecule_id": "MOL_12345",
    "evidence_list": [
        {
            "type": "spectral_match",
            "value": 0.85,
            "uncertainty": 0.1,
            "timestamp": "2024-01-15T10:30:00Z",
            "source": "NIST_MS_DB"
        },
        {
            "type": "sequence_similarity", 
            "value": 0.72,
            "uncertainty": 0.15,
            "timestamp": "2024-01-15T10:25:00Z",
            "source": "UniProt"
        }
    ],
    "fuzzy_config": {
        "membership_functions": {
            "spectral_match": "gaussian",
            "sequence_similarity": "triangular"
        },
        "temporal_decay_enabled": True,
        "decay_half_life_days": 30
    }
}

response = requests.post(
    'https://api.hegel-bio.org/v1/fuzzy-evidence/integrate',
    headers={'Authorization': f'Bearer {token}'},
    json=evidence_data
)

result = response.json()
print(f"Fuzzy confidence: {result['fuzzy_confidence']['overall_score']}")
print(f"Uncertainty bounds: {result['fuzzy_confidence']['uncertainty_bounds']}")

JavaScript Example - Evidence Network Analysis

// Authentication
const authResponse = await fetch('https://api.hegel-bio.org/v1/auth/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        username: 'researcher@university.edu',
        password: 'secure_password'
    })
});
const { access_token } = await authResponse.json();

// Get network statistics
const networkResponse = await fetch(
    'https://api.hegel-bio.org/v1/fuzzy-evidence/network-stats/MOL_12345?include_predictions=true',
    {
        headers: { 'Authorization': `Bearer ${access_token}` }
    }
);

const networkStats = await networkResponse.json();
console.log('Network coherence:', networkStats.coherence_metrics.overall_coherence);
console.log('Evidence distribution:', networkStats.evidence_distribution);

// Predict missing evidence
const predictionData = {
    evidence_types_to_predict: ['pathway_membership'],
    prediction_config: {
        confidence_threshold: 0.6,
        network_learning_enabled: true
    }
};

const predictionResponse = await fetch(
    'https://api.hegel-bio.org/v1/fuzzy-evidence/predict-evidence/MOL_12345',
    {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${access_token}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify(predictionData)
    }
);

const predictions = await predictionResponse.json();
console.log('Predicted evidence:', predictions.predictions);

cURL Example - Objective Optimization

# Login and get token
TOKEN=$(curl -s -X POST https://api.hegel-bio.org/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"researcher@university.edu","password":"secure_password"}' \
  | jq -r '.access_token')

# Optimize objectives
curl -X POST https://api.hegel-bio.org/v1/fuzzy-evidence/optimize-objective/MOL_12345 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "optimization_config": {
      "objectives": {
        "maximize_confidence": 0.4,
        "minimize_uncertainty": 0.3,
        "maximize_consistency": 0.2,
        "minimize_conflicts": 0.1
      },
      "optimization_method": "pareto_frontier"
    }
  }' | jq '.optimization_results.optimal_score'

Error Handling

HTTP Status Codes

200 OK - Request successful
201 Created - Resource created successfully
400 Bad Request - Invalid request parameters
401 Unauthorized - Authentication required
403 Forbidden - Insufficient permissions
404 Not Found - Resource not found
422 Unprocessable Entity - Validation error
500 Internal Server Error - Server error

Error Response Format

{
  "error": {
    "code": "FUZZY_EVIDENCE_VALIDATION_ERROR",
    "message": "Invalid membership function parameters",
    "details": {
      "field": "fuzzy_config.membership_functions.spectral_match",
      "issue": "Gaussian function requires 'center' and 'sigma' parameters",
      "provided": {"type": "gaussian", "parameters": [0.5]}
    },
    "timestamp": "2024-01-15T10:35:00Z",
    "request_id": "req_abc123"
  }
}