Core API

The core API provides the main classes and functions for translation quality checking.

Basic Usage

import asyncio
from kttc.agents import AgentOrchestrator
from kttc.llm import OpenAIProvider
from kttc.core import TranslationTask

async def check_translation():
    # Initialize provider
    llm = OpenAIProvider(api_key="sk-...")

    # Create orchestrator
    orchestrator = AgentOrchestrator(llm)

    # Create task
    task = TranslationTask(
        source_text="Hello, world!",
        translation="¡Hola, mundo!",
        source_lang="en",
        target_lang="es",
    )

    # Evaluate
    report = await orchestrator.evaluate(task)

    # Access results
    print(f"MQM Score: {report.mqm_score}")
    print(f"Issues: {len(report.errors)}")

    for error in report.errors:
        print(f"  {error.severity}: {error.description}")

asyncio.run(check_translation())

Core Classes

TranslationTask

TranslationTask

Bases: BaseModel

Represents a translation to be evaluated.

Contains source text, translation, language codes, and optional metadata.

word_count property

Calculate word count of source text for scoring.

Main class for representing a translation task.

Example:

from kttc.core import TranslationTask

task = TranslationTask(
    source_text="Hello, world!",
    translation="¡Hola, mundo!",
    source_lang="en",
    target_lang="es",
)

QAReport

QAReport

Bases: BaseModel

Quality assessment report generated by the system.

Contains MQM score, detected errors, and pass/fail status.

New in weighted consensus mode: - confidence: Confidence level based on agent agreement (0.0-1.0) - agent_agreement: How much agents agree with each other - agent_scores: Individual MQM scores per agent - consensus_metadata: Additional consensus calculation details

critical_error_count property

Number of critical errors.

error_count property

Total number of errors found.

major_error_count property

Number of major errors.

minor_error_count property

Number of minor errors.

is_high_confidence(threshold=0.8)

Check if evaluation has high confidence.

Parameters:

Name	Type	Description	Default
threshold	float	Minimum confidence level (default: 0.8)	0.8

Returns:

Type	Description
bool	True if confidence >= threshold, False otherwise or if confidence is None

Example

report = QAReport(...) if not report.is_high_confidence(): ... print("Warning: Low confidence - recommend human review")

needs_human_review(confidence_threshold=0.7)

Determine if translation needs human review based on confidence.

Parameters:

Name	Type	Description	Default
confidence_threshold	float	Minimum acceptable confidence (default: 0.7)	0.7

Returns:

Type	Description
bool	True if human review recommended (low confidence or fail status)

Example

report = QAReport(...) if report.needs_human_review(): ... print("Flagged for human review")

Represents the results of quality analysis.

Example:

# Report is returned by AgentOrchestrator
report = await orchestrator.evaluate(task)

print(f"MQM Score: {report.mqm_score}")
print(f"Total Errors: {len(report.errors)}")

ErrorAnnotation

ErrorAnnotation

Bases: BaseModel

Represents a single quality error found by an agent.

Follows MQM error typology with category, subcategory, and severity.

Represents a translation quality issue.

ErrorSeverity

ErrorSeverity

Bases: str, Enum

MQM error severity levels.

Based on Multidimensional Quality Metrics (MQM) framework. Each level has a different penalty weight in quality scoring.

penalty_value property

Get numeric penalty value for scoring.

Enumeration of error severity levels.

Advanced Usage

Using Glossary

from kttc.core import Glossary, TermEntry

# Create glossary
glossary = Glossary(
    name="Technical Terms",
    version="1.0",
    terms=[
        TermEntry(
            source="API",
            target="API",
            context="Keep as-is"
        ),
        TermEntry(
            source="cloud",
            target="nube",
            context="Technology context"
        )
    ]
)

# Use in task
task = TranslationTask(
    source_text="Cloud API documentation",
    translation="Documentación de API en la nube",
    source_lang="en",
    target_lang="es",
    glossary=glossary
)

report = await orchestrator.evaluate(task)

Batch Processing

from kttc.core import BatchFileParser

async def process_batch():
    # Parse batch file
    parser = BatchFileParser()
    tasks = parser.parse_csv("translations.csv")

    # Evaluate each task
    reports = []
    for task in tasks:
        report = await orchestrator.evaluate(task)
        reports.append(report)

    # Calculate average MQM
    avg_mqm = sum(r.mqm_score for r in reports) / len(reports)
    print(f"Average MQM Score: {avg_mqm:.2f}")

MQM Scoring

from kttc.core import MQMScorer

# Create scorer
scorer = MQMScorer()

# Calculate MQM score from errors
errors = [...]  # List of ErrorAnnotation objects
mqm_score = scorer.calculate_score(errors, total_words=10)

print(f"MQM Score: {mqm_score:.2f}")