themis-eval 0.2.0__tar.gz → 0.2.2__tar.gz

{themis_eval-0.2.0/themis_eval.egg-info → themis_eval-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: themis-eval
-Version: 0.2.0
+Version: 0.2.2
 Summary: Lightweight evaluation platform for LLM experiments
 Author: Pittawat Taveekitworachai
 License: MIT
@@ -25,6 +25,7 @@ Requires-Dist: tabulate>=0.9.0
 Requires-Dist: tenacity>=9.1.2
 Requires-Dist: plotly>=6.5.0
 Requires-Dist: math-verify>=0.8.0
+Requires-Dist: rich>=14.2.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-cov>=6.0.0; extra == "dev"
@@ -358,9 +359,9 @@ Themis is built on a clean, modular architecture:
 
 - **[API Reference](docs/index.md)** - Detailed API documentation
 - **[Examples](examples-simple/)** - Runnable code examples
-- **[Extending Backends](docs/EXTENDING_BACKENDS.md)** - Custom storage and execution
-- **[API Server](docs/API_SERVER.md)** - Web dashboard and REST API
-- **[Comparison Engine](docs/COMPARISON.md)** - Statistical testing guide
+- **[Extending Backends](docs/customization/backends.md)** - Custom storage and execution
+- **[API Server](docs/reference/api-server.md)** - Web dashboard and REST API
+- **[Comparison Engine](docs/guides/comparison.md)** - Statistical testing guide
 
 ---
 
@@ -388,7 +389,7 @@ result = evaluate(
 )
 ```
 
-See [EXTENDING_BACKENDS.md](docs/EXTENDING_BACKENDS.md) for details.
+See [docs/customization/backends.md](docs/customization/backends.md) for details.
 
 ### Distributed Execution
 

{themis_eval-0.2.0 → themis_eval-0.2.2}/README.md

@@ -300,9 +300,9 @@ Themis is built on a clean, modular architecture:
 
 - **[API Reference](docs/index.md)** - Detailed API documentation
 - **[Examples](examples-simple/)** - Runnable code examples
-- **[Extending Backends](docs/EXTENDING_BACKENDS.md)** - Custom storage and execution
-- **[API Server](docs/API_SERVER.md)** - Web dashboard and REST API
-- **[Comparison Engine](docs/COMPARISON.md)** - Statistical testing guide
+- **[Extending Backends](docs/customization/backends.md)** - Custom storage and execution
+- **[API Server](docs/reference/api-server.md)** - Web dashboard and REST API
+- **[Comparison Engine](docs/guides/comparison.md)** - Statistical testing guide
 
 ---
 
@@ -330,7 +330,7 @@ result = evaluate(
 )
 ```
 
-See [EXTENDING_BACKENDS.md](docs/EXTENDING_BACKENDS.md) for details.
+See [docs/customization/backends.md](docs/customization/backends.md) for details.
 
 ### Distributed Execution
 

{themis_eval-0.2.0 → themis_eval-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "themis-eval"
-version = "0.2.0"
+version = "0.2.2"
 description = "Lightweight evaluation platform for LLM experiments"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -32,6 +32,7 @@ dependencies = [
     "tenacity>=9.1.2",
     "plotly>=6.5.0",
     "math-verify>=0.8.0",
+    "rich>=14.2.0",
 ]
 
 [tool.setuptools.packages.find]
@@ -85,3 +86,6 @@ all = [
 [tool.pytest.ini_options]
 addopts = "-q"
 pythonpath = ["."]
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+]

themis_eval-0.2.2/themis/__init__.py

@@ -0,0 +1,47 @@
+"""Themis experiment platform - Dead simple LLM evaluation.
+
+The primary interface is the `evaluate()` function:
+
+    import themis
+    report = themis.evaluate("math500", model="gpt-4", limit=100)
+
+Extension APIs for registering custom components:
+    - themis.register_metric() - Register custom metrics
+    - themis.register_dataset() - Register custom datasets
+    - themis.register_provider() - Register custom model providers
+    - themis.register_benchmark() - Register custom benchmark presets
+"""
+
+from themis import config, core, evaluation, experiment, generation, project
+from themis._version import __version__
+from themis.api import evaluate, get_registered_metrics, register_metric
+from themis.datasets import register_dataset, list_datasets, is_dataset_registered
+from themis.presets import register_benchmark, list_benchmarks, get_benchmark_preset
+from themis.providers import register_provider
+
+__all__ = [
+    # Main API
+    "evaluate",
+    # Metrics
+    "register_metric",
+    "get_registered_metrics",
+    # Datasets
+    "register_dataset",
+    "list_datasets",
+    "is_dataset_registered",
+    # Benchmarks
+    "register_benchmark",
+    "list_benchmarks",
+    "get_benchmark_preset",
+    # Providers
+    "register_provider",
+    # Submodules
+    "config",
+    "core",
+    "evaluation",
+    "experiment",
+    "generation",
+    "project",
+    # Version
+    "__version__",
+]

{themis_eval-0.2.0 → themis_eval-0.2.2}/themis/_version.py

@@ -9,7 +9,7 @@ def _detect_version() -> str:
     try:
         return metadata.version("themis-eval")
     except metadata.PackageNotFoundError:  # pragma: no cover - local dev only
-        return "0.2.0"  # Fallback for development
+        return "0.2.2"  # Fallback for development
 
 
 __version__ = _detect_version()

{themis_eval-0.2.0 → themis_eval-0.2.2}/themis/api.py

@@ -33,6 +33,7 @@ Example:
 
 from __future__ import annotations
 
+import logging
 from datetime import datetime
 from pathlib import Path
 from typing import Any, Callable, Sequence
@@ -52,6 +53,67 @@ from themis.generation.runner import GenerationRunner
 from themis.generation.templates import PromptTemplate
 from themis.providers import create_provider
 
+# Import provider modules to ensure they register themselves
+try:
+    from themis.generation import clients  # noqa: F401 - registers fake provider
+    from themis.generation.providers import (
+        litellm_provider,  # noqa: F401
+        vllm_provider,  # noqa: F401
+    )
+except ImportError:
+    pass
+
+logger = logging.getLogger(__name__)
+
+
+# Module-level metrics registry for custom metrics
+_METRICS_REGISTRY: dict[str, type] = {}
+
+
+def register_metric(name: str, metric_cls: type) -> None:
+    """Register a custom metric for use in evaluate().
+    
+    This allows users to add their own metrics to Themis without modifying
+    the source code. Registered metrics can be used by passing their names
+    to the `metrics` parameter in evaluate().
+    
+    Args:
+        name: Metric name (used in evaluate(metrics=[name]))
+        metric_cls: Metric class implementing the Metric interface.
+            Must have a compute() method that takes prediction, references,
+            and metadata parameters.
+    
+    Raises:
+        TypeError: If metric_cls is not a class
+        ValueError: If metric_cls doesn't implement the required interface
+    
+    Example:
+        >>> from themis.evaluation.metrics import MyCustomMetric
+        >>> themis.register_metric("my_metric", MyCustomMetric)
+        >>> report = themis.evaluate("math500", model="gpt-4", metrics=["my_metric"])
+    """
+    if not isinstance(metric_cls, type):
+        raise TypeError(f"metric_cls must be a class, got {type(metric_cls)}")
+    
+    # Validate that it implements the Metric interface
+    if not hasattr(metric_cls, "compute"):
+        raise ValueError(
+            f"{metric_cls.__name__} must implement compute() method. "
+            f"See themis.evaluation.metrics for examples."
+        )
+    
+    _METRICS_REGISTRY[name] = metric_cls
+    logger.info(f"Registered custom metric: {name} -> {metric_cls.__name__}")
+
+
+def get_registered_metrics() -> dict[str, type]:
+    """Get all currently registered custom metrics.
+    
+    Returns:
+        Dictionary mapping metric names to their classes
+    """
+    return _METRICS_REGISTRY.copy()
+
 
 def evaluate(
     benchmark_or_dataset: str | Sequence[dict[str, Any]],
@@ -123,6 +185,19 @@ def evaluate(
         >>> print(f"Accuracy: {report.evaluation_report.metrics['accuracy']:.2%}")
         Accuracy: 85.00%
     """
+    logger.info("=" * 60)
+    logger.info("Starting Themis evaluation")
+    logger.info(f"Model: {model}")
+    logger.info(f"Workers: {workers}")
+    logger.info(f"Temperature: {temperature}, Max tokens: {max_tokens}")
+    if "api_base" in kwargs:
+        logger.info(f"Custom API base: {kwargs['api_base']}")
+    if "api_key" in kwargs:
+        logger.info("API key: <provided>")
+    else:
+        logger.warning("⚠️  No api_key provided - may fail for custom API endpoints")
+    logger.info("=" * 60)
+    
     # Import presets system (lazy import to avoid circular dependencies)
     from themis.presets import get_benchmark_preset, parse_model_name
     
@@ -131,11 +206,23 @@ def evaluate(
     
     if is_benchmark:
         benchmark_name = benchmark_or_dataset
+        logger.info(f"Loading benchmark: {benchmark_name}")
+        
         # Get preset configuration
-        preset = get_benchmark_preset(benchmark_name)
+        try:
+            preset = get_benchmark_preset(benchmark_name)
+        except Exception as e:
+            logger.error(f"❌ Failed to get benchmark preset '{benchmark_name}': {e}")
+            raise
         
         # Load dataset using preset loader
-        dataset = preset.load_dataset(limit=limit)
+        logger.info(f"Loading dataset (limit={limit})...")
+        try:
+            dataset = preset.load_dataset(limit=limit)
+            logger.info(f"✅ Loaded {len(dataset)} samples from {benchmark_name}")
+        except Exception as e:
+            logger.error(f"❌ Failed to load dataset: {e}")
+            raise
         
         # Use preset prompt if not overridden
         if prompt is None:
@@ -158,11 +245,14 @@ def evaluate(
         dataset_id_field = preset.dataset_id_field
     else:
         # Custom dataset
+        logger.info("Using custom dataset")
         dataset = list(benchmark_or_dataset)
+        logger.info(f"Custom dataset has {len(dataset)} samples")
         
         # Limit dataset if requested
         if limit is not None:
             dataset = dataset[:limit]
+            logger.info(f"Limited to {len(dataset)} samples")
         
         # Use provided prompt or default
         if prompt is None:
@@ -188,7 +278,15 @@ def evaluate(
         dataset_id_field = "id"
     
     # Parse model name to get provider and options
-    provider_name, model_id, provider_options = parse_model_name(model, **kwargs)
+    logger.info(f"Parsing model configuration...")
+    try:
+        provider_name, model_id, provider_options = parse_model_name(model, **kwargs)
+        logger.info(f"Provider: {provider_name}")
+        logger.info(f"Model ID: {model_id}")
+        logger.debug(f"Provider options: {provider_options}")
+    except Exception as e:
+        logger.error(f"❌ Failed to parse model name '{model}': {e}")
+        raise
     
     # Create model spec
     model_spec = ModelSpec(
@@ -214,17 +312,31 @@ def evaluate(
     )
     
     # Create provider and router
-    provider = create_provider(provider_name, **provider_options)
+    logger.info(f"Creating provider '{provider_name}'...")
+    try:
+        provider = create_provider(provider_name, **provider_options)
+        logger.info(f"✅ Provider created successfully")
+    except KeyError as e:
+        logger.error(f"❌ Provider '{provider_name}' not registered. Available providers: fake, litellm, openai, anthropic, azure, bedrock, gemini, cohere, vllm")
+        logger.error(f"   This usually means the provider module wasn't imported.")
+        raise
+    except Exception as e:
+        logger.error(f"❌ Failed to create provider: {e}")
+        raise
+    
     router = ProviderRouter({model_id: provider})
+    logger.debug(f"Router configured for model: {model_id}")
     
     # Create runner
-    runner = GenerationRunner(provider=router)
+    runner = GenerationRunner(provider=router, max_parallel=workers)
+    logger.info(f"Runner configured with {workers} parallel workers")
     
     # Create evaluation pipeline
     pipeline = EvaluationPipeline(
         extractor=extractor,
         metrics=metrics_list,
     )
+    logger.info(f"Evaluation metrics: {[m.name for m in metrics_list]}")
     
     # Determine storage location
     if storage is None:
@@ -235,11 +347,15 @@ def evaluate(
     # Generate run ID if not provided
     if run_id is None:
         run_id = f"run-{datetime.now().strftime('%Y%m%d-%H%M%S')}"
+    logger.info(f"Run ID: {run_id}")
+    logger.info(f"Storage: {storage_dir}")
+    logger.info(f"Resume: {resume}")
     
     # Create storage backend
     if isinstance(storage_dir, Path):
         from themis.experiment.storage import ExperimentStorage
         storage_backend = ExperimentStorage(storage_dir)
+        logger.debug(f"Storage backend created at {storage_dir}")
     else:
         # Cloud storage (to be implemented in Phase 3)
         raise NotImplementedError(
@@ -264,15 +380,34 @@ def evaluate(
         )
     
     # Run locally
-    report = orchestrator.run(
-        dataset=dataset,
-        max_samples=limit,
-        run_id=run_id,
-        resume=resume,
-        on_result=on_result,
-    )
+    logger.info("=" * 60)
+    logger.info("🚀 Starting experiment execution...")
+    logger.info("=" * 60)
     
-    return report
+    try:
+        report = orchestrator.run(
+            dataset=dataset,
+            max_samples=limit,
+            run_id=run_id,
+            resume=resume,
+            on_result=on_result,
+        )
+        
+        logger.info("=" * 60)
+        logger.info("✅ Evaluation completed successfully!")
+        logger.info(f"   Total samples: {len(report.generation_results)}")
+        logger.info(f"   Successful: {report.metadata.get('successful_generations', 0)}")
+        logger.info(f"   Failed: {report.metadata.get('failed_generations', 0)}")
+        if report.evaluation_report.metrics:
+            logger.info(f"   Metrics: {list(report.evaluation_report.metrics.keys())}")
+        logger.info("=" * 60)
+        
+        return report
+    except Exception as e:
+        logger.error("=" * 60)
+        logger.error(f"❌ Evaluation failed: {e}")
+        logger.error("=" * 60)
+        raise
 
 
 def _resolve_metrics(metric_names: list[str]) -> list:
@@ -298,8 +433,8 @@ def _resolve_metrics(metric_names: list[str]) -> list:
     except ImportError:
         nlp_available = False
     
-    # Metric registry
-    METRICS_REGISTRY = {
+    # Built-in metrics registry
+    BUILTIN_METRICS = {
         # Core metrics
         "exact_match": ExactMatch,
         "math_verify": MathVerifyAccuracy,
@@ -308,7 +443,7 @@ def _resolve_metrics(metric_names: list[str]) -> list:
     
     # Add NLP metrics if available
     if nlp_available:
-        METRICS_REGISTRY.update({
+        BUILTIN_METRICS.update({
             "bleu": BLEU,
             "rouge1": lambda: ROUGE(variant=ROUGEVariant.ROUGE_1),
             "rouge2": lambda: ROUGE(variant=ROUGEVariant.ROUGE_2),
@@ -321,6 +456,10 @@ def _resolve_metrics(metric_names: list[str]) -> list:
     # "pass_at_k": PassAtK,
     # "codebleu": CodeBLEU,
     
+    # Merge built-in and custom metrics
+    # Custom metrics can override built-in metrics
+    METRICS_REGISTRY = {**BUILTIN_METRICS, **_METRICS_REGISTRY}
+    
     metrics = []
     for name in metric_names:
         if name not in METRICS_REGISTRY:
@@ -340,4 +479,4 @@ def _resolve_metrics(metric_names: list[str]) -> list:
     return metrics
 
 
-__all__ = ["evaluate"]
+__all__ = ["evaluate", "register_metric", "get_registered_metrics"]

{themis_eval-0.2.0 → themis_eval-0.2.2}/themis/experiment/orchestrator.py

@@ -2,10 +2,13 @@
 
 from __future__ import annotations
 
+import logging
 from datetime import datetime, timezone
 from typing import Callable, Sequence
 
 from themis.config.schema import IntegrationsConfig
+
+logger = logging.getLogger(__name__)
 from themis.core.entities import (
     EvaluationRecord,
     ExperimentFailure,
@@ -102,6 +105,8 @@ class ExperimentOrchestrator:
         Returns:
             ExperimentReport with generation results, evaluation, and metadata
         """
+        logger.info("Orchestrator: Initializing experiment run")
+        
         # Initialize integrations
         self._integrations.initialize_run(
             {
@@ -112,13 +117,23 @@ class ExperimentOrchestrator:
         )
 
         # Prepare dataset
-        dataset_list = self._resolve_dataset(
-            dataset=dataset, dataset_loader=dataset_loader, run_id=run_id
-        )
+        logger.info("Orchestrator: Loading dataset...")
+        try:
+            dataset_list = self._resolve_dataset(
+                dataset=dataset, dataset_loader=dataset_loader, run_id=run_id
+            )
+            logger.info(f"Orchestrator: Dataset loaded ({len(dataset_list)} total samples)")
+        except Exception as e:
+            logger.error(f"Orchestrator: ❌ Failed to load dataset: {e}")
+            raise
+        
         selected_dataset = (
             dataset_list[:max_samples] if max_samples is not None else dataset_list
         )
         run_identifier = run_id or self._default_run_id()
+        
+        logger.info(f"Orchestrator: Processing {len(selected_dataset)} samples")
+        logger.info(f"Orchestrator: Run ID = {run_identifier}")
 
         # Initialize run in storage (if storage exists and run doesn't exist)
         if self._cache.has_storage:
@@ -130,18 +145,30 @@ class ExperimentOrchestrator:
             self._cache.cache_dataset(run_identifier, dataset_list)
 
         # Expand dataset into generation tasks
-        tasks = list(self._plan.expand(selected_dataset))
+        logger.info("Orchestrator: Expanding dataset into generation tasks...")
+        try:
+            tasks = list(self._plan.expand(selected_dataset))
+            logger.info(f"Orchestrator: Created {len(tasks)} generation tasks")
+        except Exception as e:
+            logger.error(f"Orchestrator: ❌ Failed to expand dataset: {e}")
+            raise
 
         # Build evaluation configuration for cache invalidation
         evaluation_config = self._build_evaluation_config()
 
         # Load cached results if resuming
+        if resume:
+            logger.info("Orchestrator: Loading cached results...")
         cached_records = (
             self._cache.load_cached_records(run_identifier) if resume else {}
         )
         cached_evaluations = (
             self._cache.load_cached_evaluations(run_identifier, evaluation_config) if resume else {}
         )
+        if resume and cached_records:
+            logger.info(f"Orchestrator: Found {len(cached_records)} cached generation records")
+        if resume and cached_evaluations:
+            logger.info(f"Orchestrator: Found {len(cached_evaluations)} cached evaluation records")
 
         # Process tasks: use cached or run new generations
         generation_results: list[GenerationRecord] = []
@@ -178,9 +205,18 @@ class ExperimentOrchestrator:
 
         # Run pending generation tasks
         if pending_tasks:
+            logger.info(f"Orchestrator: Running {len(pending_tasks)} generation tasks...")
+            completed = 0
             for record in self._runner.run(pending_tasks):
+                logger.debug(f"Orchestrator: Received generation record")
                 generation_results.append(record)
+                completed += 1
+                
+                # Log progress every 10 samples or at key milestones
+                if completed % 10 == 0 or completed == len(pending_tasks):
+                    logger.info(f"Orchestrator: Generation progress: {completed}/{len(pending_tasks)} ({100*completed//len(pending_tasks)}%)")
 
+                logger.debug(f"Orchestrator: Processing record (cost tracking...)")
                 # Track cost for successful generations
                 if record.output and record.output.usage:
                     usage = record.output.usage
@@ -197,6 +233,7 @@ class ExperimentOrchestrator:
                         cost=cost,
                     )
 
+                logger.debug(f"Orchestrator: Processing record (error handling...)")
                 if record.error:
                     failures.append(
                         ExperimentFailure(
@@ -204,20 +241,35 @@ class ExperimentOrchestrator:
                             message=record.error.message,
                         )
                     )
+                    
+                logger.debug(f"Orchestrator: Processing record (caching...)")
                 cache_key = experiment_storage.task_cache_key(record.task)
                 if cache_results:
                     self._cache.save_generation_record(
                         run_identifier, record, cache_key
                     )
+                    
+                logger.debug(f"Orchestrator: Processing record (adding to pending...)")
                 pending_records.append(record)
                 pending_keys.append(cache_key)
+                
+                logger.debug(f"Orchestrator: Processing record (callback...)")
                 if on_result:
                     on_result(record)
+                logger.debug(f"Orchestrator: Record processing complete")
 
         # Evaluate pending records
+        logger.info(f"Orchestrator: Preparing to evaluate {len(pending_records)} pending records...")
         if pending_records:
-            new_evaluation_report = self._evaluation.evaluate(pending_records)
+            logger.info(f"Orchestrator: Starting evaluation of {len(pending_records)} records...")
+            try:
+                new_evaluation_report = self._evaluation.evaluate(pending_records)
+                logger.info(f"Orchestrator: ✅ Evaluation complete - got {len(new_evaluation_report.records)} results")
+            except Exception as e:
+                logger.error(f"Orchestrator: ❌ Evaluation failed: {e}")
+                raise
         else:
+            logger.info("Orchestrator: No new records to evaluate (all cached)")
             new_evaluation_report = evaluation_pipeline.EvaluationReport(
                 metrics={}, failures=[], records=[]
             )
@@ -229,12 +281,16 @@ class ExperimentOrchestrator:
             )
 
         # Combine cached and new evaluations
+        logger.info("Orchestrator: Combining cached and new evaluations...")
         evaluation_report = self._combine_evaluations(
             cached_eval_records, new_evaluation_report
         )
+        logger.info(f"Orchestrator: Total evaluation records: {len(evaluation_report.records)}")
 
         # Get cost breakdown
         cost_breakdown = self._cost_tracker.get_breakdown()
+        if cost_breakdown.total_cost > 0:
+            logger.info(f"Orchestrator: Total cost: ${cost_breakdown.total_cost:.4f}")
 
         # Build metadata
         metadata = {