Python SDK

Official Python SDK for Sematryx. Full-featured client library with support for optimization, AEAO Tetrad configuration, and domain-specific libraries.

Install the Python SDK

pip install sematryx

The SDK requires Python 3.8 or higher. For domain-specific optimizations, install with extras:

Install with domain libraries

pip install sematryx[financial,healthcare,supply_chain]

The simplest way to use Sematryx is with the main sematryx() function:

Basic optimization example

from sematryx import sematryx

# Define your objective function
def sphere(x):
    return sum(xi**2 for xi in x)

# Run optimization
result = sematryx(
    objective_function=sphere,
    bounds=[[-5, 5], [-5, 5]],
    max_evaluations=1000
)

print(f"Best solution: {result['best_solution']}")
print(f"Best fitness: {result['best_fitness']}")

Configure the four pillars of AEAO intelligence to match your needs:

Tetrad configuration examples

from sematryx import sematryx, AEAOTetradCompleteConfig

# Option 1: Use preset configuration
result = sematryx(
    objective_function=sphere,
    bounds=[[-5, 5], [-5, 5]],
    preset="production"  # development, production, research, enterprise, minimal
)

# Option 2: Enable specific tetrad pillars
result = sematryx(
    objective_function=sphere,
    bounds=[[-5, 5], [-5, 5]],
    use_agentic_intelligence=True,      # Multi-agent coordination
    use_autodidactic_intelligence=True,  # Self-improvement
    explanation_level=3                 # Detailed explanations
)

# Option 3: Complete custom configuration
config = AEAOTetradCompleteConfig.enterprise()
config.expository.explanation_level = 4
config.agentic.max_agents_per_problem = 5
result = sematryx(objective_function=sphere, bounds=[[-5, 5], [-5, 5]], config=config)

The AEAO Tetrad

🤖 Agentic Intelligence: Multi-agent coordination for strategy selection
📖 Expository Intelligence: Explainable results (levels 0-5)
🧠 Autodidactic Intelligence: Self-improvement through learning
🏗️ Domain Extension: Business domain libraries (enabled by default)

Use specialized domain libraries for industry-specific problems:

Domain-specific optimization examples

from sematryx import financial_optimize, healthcare_optimize, supply_chain_optimize

# Financial portfolio optimization
result = financial_optimize(
    problem_type='portfolio',
    config={
        'assets': ['AAPL', 'GOOGL', 'MSFT', 'TSLA'],
        'risk_tolerance': 0.15,
        'expected_returns': [0.12, 0.15, 0.10, 0.20]
    },
    max_evaluations=2000
)

# Healthcare drug discovery
result = healthcare_optimize(
    problem_type='drug_discovery',
    config={
        'target_protein': 'protein_id_123',
        'constraints': {'toxicity': '< 0.1', 'solubility': '> 0.5'}
    }
)

# Supply chain routing
result = supply_chain_optimize(
    problem_type='vehicle_routing',
    config={
        'locations': [...],
        'vehicle_capacity': 1000,
        'time_windows': {...}
    }
)

Available Domains

financial: Portfolio optimization, trading strategies, risk management
healthcare: Drug discovery, clinical trials, treatment optimization
supply_chain: Vehicle routing, inventory optimization, cold chain
ai_ml: Neural architecture search, hyperparameter tuning
marketing: Campaign optimization, pricing strategies

For server-side optimization via the REST API:

Using the API client

from sematryx import SematryxClient

# Initialize API client
client = SematryxClient(
    api_url="https://api.sematryx.com",
    api_key="your-api-key"
)

# Authenticate
client.authenticate()

# Run optimization via API
result = client.optimize(
    objective_function=sphere,
    bounds=[[-5, 5], [-5, 5]],
    max_evaluations=1000
)

Enable advanced capabilities for complex optimization problems:

Advanced features

from sematryx import sematryx

# GPU acceleration
result = sematryx(
    objective_function=complex_function,
    bounds=[[-10, 10]] * 100,  # High-dimensional
    use_gpu_acceleration=True
)

# Visual intelligence
result = sematryx(
    objective_function=landscape_function,
    bounds=[[-5, 5], [-5, 5]],
    use_visual_intelligence=True,
    explanation_level=4
)

# Neural-symbolic reasoning
result = sematryx(
    objective_function=hybrid_function,
    bounds=[[-5, 5], [-5, 5]],
    use_neural_symbolic=True
)

The SDK provides specific exception types for different error scenarios:

Error handling

from sematryx.exceptions import (
    SematryxError, 
    AuthenticationError, 
    RateLimitError,
    OptimizationError
)

try:
    result = sematryx(
        objective_function=sphere,
        bounds=[[-5, 5], [-5, 5]],
        max_evaluations=1000
    )
except AuthenticationError:
    print('Invalid API key')
except RateLimitError:
    print('Rate limit exceeded. Please wait and retry.')
except OptimizationError as e:
    print(f'Optimization failed: {e.message}')
except SematryxError as e:
    print(f'Error: {e.message}')

Use AsyncAEAO for concurrent operations:

Async usage

import asyncio
from sematryx import AsyncSematryx

async def main():
    client = AsyncSematryx(api_key='your-api-key')
    
    # Run multiple optimizations concurrently
    results = await asyncio.gather(
        client.optimize(objective1, bounds1, max_evaluations=1000),
        client.optimize(objective2, bounds2, max_evaluations=1000),
        client.optimize(objective3, bounds3, max_evaluations=1000)
    )
    
    return results

asyncio.run(main())

Manage client identity, privacy settings, and usage quotas:

Identity management examples

from sematryx import SematryxClient

client = SematryxClient(api_url="https://api.sematryx.com", api_key="your-api-key")

# Create client identity
identity = client.register_with_identity(
    email="user@example.com",
    organization_id="org_123",
    privacy_level=PrivacyLevel.AGGREGATED,
    subscription_tier=SubscriptionTier.PROFESSIONAL
)

# Get privacy status
privacy_status = client.get_privacy_status()
print(f"Privacy level: {privacy_status['privacy_level']}")

# Get usage quotas
quotas = client.get_usage_quotas()
print(f"Optimizations used: {quotas['current_usage']['optimizations_per_day']}")
print(f"Quota: {quotas['api_quotas']['optimizations_per_day']}")

# Configure data sharing
client.configure_data_sharing({
    'optimization_results': True,
    'performance_metrics': True,
    'problem_signatures': False
})

Submit and manage batch optimization jobs:

Batch operations examples

from sematryx import SematryxClient

client = SematryxClient(api_url="https://api.sematryx.com", api_key="your-api-key")

# Submit batch optimization job
batch_job = client.submit_batch_optimization(
    batch_name="portfolio_analysis",
    optimizations=[
        {
            "job_name": "portfolio_1",
            "objective_function": "sphere",
            "bounds": [[-5, 5], [-5, 5]],
            "max_evaluations": 1000
        },
        {
            "job_name": "portfolio_2",
            "objective_function": "rosenbrock",
            "bounds": [[-5, 5], [-5, 5]],
            "max_evaluations": 1000
        }
    ],
    parallel_workers=2
)

# Check batch status
status = client.get_batch_status(batch_job['batch_id'])
print(f"Progress: {status['progress_percentage']}%")

# Get batch results
results = client.get_batch_results(batch_job['batch_id'])
for job_result in results['job_results']:
    print(f"{job_result['job_name']}: {job_result['optimal_value']}")

Train models and get learning insights:

Learning system examples

from sematryx import SematryxClient

client = SematryxClient(api_url="https://api.sematryx.com", api_key="your-api-key")

# Train learning model
training_data = [
    {"problem_type": "sphere", "strategy": "differential_evolution", "success": True},
    {"problem_type": "rosenbrock", "strategy": "shgo", "success": True}
]

training_result = client.train_learning_model(
    training_data=training_data,
    model_type="cross_problem",
    max_epochs=100
)

# List trained models
models = client.list_learning_models()
for model in models:
    print(f"Model: {model['model_name']}, Type: {model['model_type']}")

# Get learning insights
insights = client.get_learning_insights()
print(f"Total models: {insights['total_models']}")
print(f"Learning enabled: {insights['learning_enabled']}")

Multi-objective optimization and sensitivity analysis:

Advanced optimization examples

from sematryx import SematryxClient

client = SematryxClient(api_url="https://api.sematryx.com", api_key="your-api-key")

# Multi-objective optimization
multi_obj_result = client.multi_objective_optimize(
    objectives=["sphere", "rosenbrock"],
    bounds=[[-5, 5], [-5, 5]],
    method="nsga2",
    max_evaluations=2000
)

# Get Pareto frontier
pareto_frontier = multi_obj_result['pareto_frontier']
for point in pareto_frontier:
    print(f"Solution: {point['solution']}, Objectives: {point['objectives']}")

# Sensitivity analysis
sensitivity_result = client.sensitivity_analysis(
    objective_function="sphere",
    bounds=[[-5, 5], [-5, 5]],
    reference_point=[0.0, 0.0],
    analysis_type="global"
)

print(f"Sensitivity scores: {sensitivity_result['sensitivity_scores']}")

Analyze problem context and get recommendations:

Context intelligence examples

from sematryx import SematryxClient

client = SematryxClient(api_url="https://api.sematryx.com", api_key="your-api-key")

# Analyze problem context
context = {
    "problem_id": "prob_123",
    "problem_type": "portfolio_optimization",
    "domain": "financial",
    "description": "Optimize portfolio allocation for risk-return tradeoff",
    "parameters": {"risk_tolerance": 0.15}
}

analysis = client.analyze_context(
    target_context=context,
    similarity_threshold=0.7,
    include_recommendations=True
)

# Get similar problems
for similar in analysis['similar_problems']:
    print(f"Similar problem: {similar['problem_id']}, Score: {similar['similarity_score']}")

# Get optimization recommendations
for recommendation in analysis['optimization_recommendations']:
    print(f"Recommendation: {recommendation}")

Store and query optimization data:

Data lake examples

from sematryx import SematryxClient

client = SematryxClient(api_url="https://api.sematryx.com", api_key="your-api-key")

# Create data connection
connection = client.create_data_connection(
    connection_type="s3",
    endpoint_url="https://s3.amazonaws.com/bucket",
    credentials={"access_key": "...", "secret_key": "..."}
)

# Upload dataset
dataset = client.upload_dataset(
    dataset_name="optimization_results",
    data_type="optimization_results",
    data=[...],  # Your data
    description="Historical optimization results"
)

# Store optimization data
client.store_optimization_data(
    experiment_id="exp_123",
    problem_definition={"bounds": [[-5, 5], [-5, 5]]},
    optimization_results=[...],
    performance_metrics={"duration": 2.5, "evaluations": 1000}
)

# Query data lake
query_result = client.query_data_lake(
    query_type="filter",
    dataset_ids=[dataset['dataset_id']],
    filters={"experiment_id": "exp_123"}
)

Submit metrics and generate performance reports:

Analytics examples

from sematryx import SematryxClient

client = SematryxClient(api_url="https://api.sematryx.com", api_key="your-api-key")

# Submit performance metrics
client.submit_metrics(
    metrics=[
        {
            "metric_name": "optimization_duration",
            "metric_value": 2.5,
            "metric_type": "time"
        },
        {
            "metric_name": "solution_quality",
            "metric_value": 0.95,
            "metric_type": "quality"
        }
    ],
    source_system="production"
)

# Generate performance report
report = client.generate_performance_report(
    report_type="comprehensive",
    metric_categories=["time", "quality", "efficiency"],
    time_range={"start": "2024-01-01", "end": "2024-01-31"}
)

# Get performance insights
insights = client.get_performance_insights()
for insight in insights:
    print(f"{insight['insight_type']}: {insight['description']}")

# Get metrics summary
summary = client.get_metrics_summary()
print(f"Average duration: {summary['average_duration']}")
print(f"Success rate: {summary['success_rate']}")

Get API configuration and check system health:

Configuration examples

from sematryx import SematryxClient

client = SematryxClient(api_url="https://api.sematryx.com", api_key="your-api-key")

# Get API configuration
config = client.get_api_config()
print(f"API Version: {config['version']}")
print(f"Environment: {config['environment']}")

# Get available features
features = client.get_features()
print(f"Optimization available: {features['optimization']['available']}")
print(f"Learning system: {features['ai_capabilities']['learning_system']}")

# Get operational limits
limits = client.get_limits()
print(f"Max evaluations: {limits['optimization']['max_evaluations']}")
print(f"Max variables: {limits['optimization']['max_variables']}")

Health check examples

from sematryx import SematryxClient

client = SematryxClient(api_url="https://api.sematryx.com", api_key="your-api-key")

# Basic health check
health = client.get_system_status()
print(f"API Server: {health['api_server']['success']}")
print(f"Local System: {health['local_system']['success']}")

# Get system health
health_status = client.get_system_health()
print(f"Status: {health_status['status']}")
print(f"Uptime: {health_status['uptime']} seconds")
print(f"Memory usage: {health_status['memory_usage']}%")

Main Function

aeao(objective_function, bounds, **kwargs) - Main optimization function
preset - Use preset config ("development", "production", "research", "enterprise", "minimal")
use_agentic_intelligence - Enable multi-agent coordination
use_expository_intelligence - Enable explainability
use_autodidactic_intelligence - Enable self-improvement
explanation_level - Explanation detail (0-5)
use_gpu_acceleration - Enable GPU/CUDA
use_visual_intelligence - Enable visual analysis

Configuration Classes

AEAOTetradCompleteConfig - Complete tetrad configuration
AEAOTetradCompleteConfig.development() - Development preset
AEAOTetradCompleteConfig.production() - Production preset
AEAOTetradCompleteConfig.research() - Research preset
AEAOTetradCompleteConfig.enterprise() - Enterprise preset

Domain Functions

financial_optimize(problem_type, config, **kwargs) - Financial optimization
healthcare_optimize(problem_type, config, **kwargs) - Healthcare optimization
supply_chain_optimize(problem_type, config, **kwargs) - Supply chain optimization

API Client

SematryxClient(api_url, api_key) - Initialize API client
client.authenticate() - Authenticate with API
client.optimize(objective, bounds, **kwargs) - Run optimization via API
client.register_with_identity() - Create client identity
client.get_usage_quotas() - Get usage quotas
client.submit_batch_optimization() - Submit batch job
client.train_learning_model() - Train learning model
client.multi_objective_optimize() - Multi-objective optimization
client.analyze_context() - Analyze problem context
client.upload_dataset() - Upload to data lake
client.submit_metrics() - Submit performance metrics
client.get_system_status() - Get system health
AsyncSematryx - Async version of API client

Python SDK

Installation

Quick Start

AEAO Tetrad Configuration

The AEAO Tetrad

Domain-Specific Optimization

Available Domains

API Client

Advanced Features

Error Handling

Async Support

Identity Management

Batch Operations

Learning System

Advanced Optimization

Context Intelligence

Data Lake

Analytics

Configuration & Health

API Reference

Main Function

Configuration Classes

Domain Functions

API Client