Metadata-Version: 2.4
Name: ai-evaluation
Version: 1.0.1
Summary: We help GenAI teams maintain high-accuracy for their Models in production.
Author-email: Future AGI <no-reply@futureagi.com>
Requires-Python: <3.14,>=3.10
Requires-Dist: futureagi>=0.6.7
Requires-Dist: jsonschema<5,>=4.25.1
Requires-Dist: litellm<2,>=1.77.4
Requires-Dist: openai<2,>=1.109.1
Requires-Dist: opentelemetry-api<2,>=1.39.1
Requires-Dist: opentelemetry-exporter-otlp<2,>=1.39.1
Requires-Dist: opentelemetry-sdk<2,>=1.39.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests<3,>=2.32.5
Requires-Dist: rich>=13.0.0
Requires-Dist: typer<1.0.0,>=0.9.0
Provides-Extra: all
Requires-Dist: celery>=5.3.0; extra == 'all'
Requires-Dist: chromadb>=0.4.0; extra == 'all'
Requires-Dist: ray>=2.0.0; extra == 'all'
Requires-Dist: redis>=5.0.0; extra == 'all'
Requires-Dist: sentence-transformers<6,>=5.2.3; extra == 'all'
Requires-Dist: temporalio>=1.7.0; extra == 'all'
Requires-Dist: torch<3,>=2.10.0; extra == 'all'
Requires-Dist: transformers<6,>=5.2.0; extra == 'all'
Provides-Extra: celery
Requires-Dist: celery>=5.3.0; extra == 'celery'
Requires-Dist: redis>=5.0.0; extra == 'celery'
Provides-Extra: embeddings
Requires-Dist: sentence-transformers<6,>=5.2.3; extra == 'embeddings'
Provides-Extra: feedback
Requires-Dist: chromadb>=0.4.0; extra == 'feedback'
Provides-Extra: nli
Requires-Dist: torch<3,>=2.10.0; extra == 'nli'
Requires-Dist: transformers<6,>=5.2.0; extra == 'nli'
Provides-Extra: ray
Requires-Dist: ray>=2.0.0; extra == 'ray'
Provides-Extra: temporal
Requires-Dist: temporalio>=1.7.0; extra == 'temporal'
Description-Content-Type: text/markdown

# Future AGI

![Company Logo](https://fi-content.s3.ap-south-1.amazonaws.com/Logo.png)

Welcome to Future AGI - Empowering GenAI Teams with Advanced Performance Management

# Overview

Future AGI provides a cutting-edge platform designed to help GenAI teams maintain peak model accuracy in production environments.
Our solution is purpose-built, scalable, and delivers results 10x faster than traditional methods.

**Key Features**

* **_Simplified GenAI Performance Management_**: Streamline your workflow and focus on developing cutting-edge AI models.
* **_Instant Evaluation_**: Score outputs without human-in-the-loop or ground truth, increasing QA team efficiency by up to 10x.
* **_Advanced Error Analytics_**: Gain ready-to-use insights with comprehensive error tagging and segmentation.
* **_Configurable Metrics_**: Define custom metrics tailored to your specific use case for precise model evaluation.

# Quickstart
---
title: Quickstart
---

This guide will walk you through setting up an evaluation in **Future AGI**, allowing you to assess AI models and workflows efficiently. You can run evaluations via the **Future AGI platform** or using the **Python SDK**.

## Access API Key

To authenticate while running evals, you will need Future AGI's API keys, which you can get access by following below steps:

- Go to your Future AGI dashboard
- Click on **Keys** under **Developer** option from left column

- Copy both, **API Key** and **Secret Key**

---

## Setup Evaluator 

Install the Future AGI Python SDK using below command:

```python
pip install ai-evaluation
```

Then initialise the Evaluator:

```python
from fi.evals import Evaluator

evaluator = Evaluator(
    fi_api_key="your_api_key",
    fi_secret_key="your_secret_key",
)
```

We recommend you to set the `FI_API_KEY` and `FI_SECRET_KEY` environment variables before using the `Evaluator` class, instead of passing them as parameters.

---


## Running Your First Eval

This section walks you through the process of running your first evaluation using the Future AGI evaluation framework. To get started, we'll use **Tone Evaluation** as an example.

### a. Using Python SDK

**Define the Test Case**

Create a test case containing the **text input** that will be evaluated for tone.

```python
from fi.testcases import TestCase

test_case = TestCase(
    input='''
    Dear Sir, I hope this email finds you well. 
    I look forward to any insights or advice you might have 
    whenever you have a free moment.
    '''
)

```

You can also directly send the data through a dictionary with valid keys. However, it is recommended to use the `TestCase` class when working with Future AGI Evaluations.


**Configure the Evaluation Template**

For **Tone Evaluation**, we use the **Tone Evaluation Template** to analyse the sentiment and emotional tone of the input.

```python
from fi.evals.templates import Tone

tone_eval = Tone() # This is the evaluation template to use provided by Future AGI
```

[Click here to read more about all the Evals provided by Future AGI](https://docs.futureagi.com/future-agi/products/evaluation/eval-definition/overview)

**Run the Evaluation**

Execute the evaluation and retrieve the results.

```python
result = evaluator.evaluate(eval_templates=[tone_eval], inputs=[test_case])
tone_result = result.eval_results[0].metrics[0].value
```


To Evaluate the data on your own evaluation template which you have created, you can use the `evaluate` function with the `eval_templates` parameter.

```python
from fi.evals import evaluate

result = evaluate(eval_templates="name-of-your-eval", inputs={
    "input": "your_input_text",
    "output": "your_output_text"
})

print(result.eval_results[0].metrics[0].value)
```

### b. Using Web Interface

**Select a Dataset**

Before running an evaluation, ensure you have selected a dataset. If no dataset is available, follow the steps to **Add Dataset** on the Future AGI platform.

[Read more about all the ways you can add dataset](https://docs.futureagi.com/future-agi/products/dataset/overview)

**Access the Evaluation Panel**

- Navigate to your dataset.
- Click on the **Evaluate** button in the top-right menu.
- This will open the evaluation configuration panel.

**Starting a New Evaluation**

- Click on the **Add Evaluation** button.
- You will be directed to the Evaluation List page. 
You can either create your own evaluation or select from the available templates built by Future AGI.
- Click on one of the available templates.
- Write the name of the evaluation and select the required dataset column.
<Tip>
Checkmark on **Error Localization** if you want to localize the errors in the dataset when the datapoint is evaluated and fails the evaluation.
</Tip>
- Click on the **Add & Run** button.


## Creating a New Evaluation

Future AGI provides a wide range of evaluation templates to choose from. You can create your own evaluation to tailor your needs by following below simple steps:

- Click on the **Create your own eval** button after clicking on the **Add Evaluation** button.
- Write the name of the evaluation, this name will be used to identify the evaluation in the evaluation list. only lower case letters, numbers and underscores are allowed in the name. 
- Select either **Use Future AGI Agents** or **Use other LLMs**

**Future AGI Agents** are our own proprietary models trained on a vast variety of datasets to perform evaluations. These models vary in capabilities and are suited for different use cases:
- **TURING_LARGE** – Flagship evaluation model that delivers best-in-class accuracy across multimodal inputs (text, images, audio). Recommended when maximal precision outweighs latency constraints.

- **TURING_SMALL** – Compact variant that preserves high evaluation fidelity while lowering computational cost. Supports text and image evaluations.

- **TURING_FLASH** – Latency-optimised version of TURING, providing high-accuracy assessments for text and image inputs with fast response times.

- **PROTECT** – Real-time guardrailing model for safety, policy compliance, and content-risk detection. Offers very low latency on text and audio streams and permits user-defined rule sets.

- **PROTECT_FLASH** – Ultra-fast binary guardrail for text content. Designed for first-pass filtering where millisecond-level turnaround is critical.

- In the Rule Prompt, you can write the rules that the evaluation should follow. Use `{{}}` to create a key (variable), that variable will be used in future when you configure the evaluation.
- Choose Output Type As either Pass/Fail or Percentage or Deterministic Choices
    - **Pass/Fail**: The evaluation will return either Pass or Fail.
    - **Percentage**: The evaluation will return a Score between 0 and 100.
    - **Deterministic Choices**: The evaluation will return a categorical choice from the list of choices.
- Select the Tags for the evaluation that are suitable to use case.
- Write the description of the evaluation that will be used to identify the evaluation in the evaluation list.
- Checkmark on **Check Internet** to power your evaluation with the latest information.
- Click on the **Create Evaluation** button.

---

## Local Execution

The SDK supports running heuristic metrics locally without API calls, enabling offline evaluation and faster feedback loops during development.

### Execution Modes

- **LOCAL**: Run all evaluations locally using heuristic metrics only (no API calls)
- **CLOUD**: Run all evaluations via the cloud API (default behavior)
- **HYBRID**: Automatically route each evaluation to local or cloud based on metric type

### Available Local Metrics

The following metrics can run locally without API access:

| Category | Metrics |
|----------|---------|
| **String** | `regex`, `contains`, `contains_all`, `contains_any`, `contains_none`, `one_line`, `equals`, `starts_with`, `ends_with`, `length_less_than`, `length_greater_than`, `length_between` |
| **JSON** | `contains_json`, `is_json`, `json_schema` |
| **Similarity** | `bleu_score`, `rouge_score`, `recall_score`, `levenshtein_similarity`, `numeric_similarity`, `embedding_similarity`, `semantic_list_contains` |

### Using the Local Evaluator

```python
from fi.evals.local import LocalEvaluator, ExecutionMode

# Create a local evaluator
evaluator = LocalEvaluator()

# Run a metric locally
result = evaluator.evaluate(
    metric_name="contains",
    inputs=[{"response": "Hello world"}],
    config={"keyword": "world"}
)

print(result.results.eval_results[0].output)  # 1.0

# Check if a metric can run locally
evaluator.can_run_locally("contains")      # True
evaluator.can_run_locally("groundedness")  # False (requires LLM)
```

### Using Hybrid Mode

Hybrid mode automatically routes metrics to local or cloud execution based on their capabilities:

```python
from fi.evals.local import HybridEvaluator, ExecutionMode

hybrid = HybridEvaluator()

# Partition evaluations by execution mode
evaluations = [
    {"metric_name": "contains", "inputs": [{"response": "test"}]},       # → LOCAL
    {"metric_name": "is_json", "inputs": [{"response": "{}"}]},          # → LOCAL
    {"metric_name": "groundedness", "inputs": [{"response": "test"}]},   # → CLOUD
]

partitions = hybrid.partition_evaluations(evaluations)
# partitions[ExecutionMode.LOCAL] contains local-capable metrics
# partitions[ExecutionMode.CLOUD] contains LLM-based metrics

# Run local partition without API calls
local_results = hybrid.evaluate_local_partition(partitions[ExecutionMode.LOCAL])
```

### Batch Evaluation

Run multiple metrics in a single call:

```python
result = evaluator.evaluate_batch([
    {
        "metric_name": "contains",
        "inputs": [{"response": "Hello world"}],
        "config": {"keyword": "world"},
    },
    {
        "metric_name": "is_json",
        "inputs": [{"response": '{"key": "value"}'}],
    },
    {
        "metric_name": "length_between",
        "inputs": [{"response": "medium length text"}],
        "config": {"min_length": 5, "max_length": 50},
    },
])
```

### Local LLM Support

For air-gapped environments or faster iteration, you can run LLM-based evaluations locally using Ollama:

```python
from fi.evals.local import OllamaLLM, HybridEvaluator

# Initialize local LLM (requires Ollama running: `ollama serve`)
llm = OllamaLLM()  # Uses llama3.2 by default

# Check if Ollama is available
if llm.is_available():
    # Use LLM as judge
    result = llm.judge(
        query="What is the capital of France?",
        response="The capital of France is Paris.",
        criteria="Evaluate if the response correctly answers the question."
    )
    print(f"Score: {result['score']}, Passed: {result['passed']}")

# Use with HybridEvaluator for automatic routing
hybrid = HybridEvaluator(local_llm=llm, prefer_local=True)

# LLM-based metrics will now run locally
result = hybrid.evaluate(
    template="groundedness",
    inputs=[{"query": "What is AI?", "response": "AI is artificial intelligence."}]
)
```

**CLI Usage:**

```bash
# Run with local LLM
fi run --mode local --local-llm ollama/llama3.2

# Run in hybrid mode (auto-route local/cloud)
fi run --mode hybrid --local-llm ollama/mistral

# Run completely offline (no cloud API calls)
fi run --offline --local-llm ollama/llama3.2
```

**Supported Local LLM Backends:**
- `ollama/llama3.2` - Llama 3.2 (default)
- `ollama/mistral` - Mistral
- `ollama/phi3` - Phi-3
- Any model available in your local Ollama installation

---

## Development & Testing

### Running Unit Tests

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run unit tests
pytest tests/unit/ -v
```

### Running Integration Tests

Integration tests verify the SDK against a running backend. See the [SDK Testing Guide](../core-backend/docs/SDK_TESTING.md) in the `core-backend` repository for detailed instructions.

**Quick Start:**

```bash
# From core-backend directory
cd /path/to/core-backend

# One-time setup
bin/sdk-test setup

# Terminal 1: Start backend
bin/sdk-test backend

# Terminal 2: Run tests
bin/sdk-test test
```

**Manual test run:**

```bash
export FI_API_KEY="test_api_key_12345"
export FI_SECRET_KEY="test_secret_key_67890"
export FI_BASE_URL="http://localhost:8001"

pytest tests/integration/ -v -m integration --run-model-serving
```

---