Metadata-Version: 2.4
Name: kttc
Version: 0.4.1
Summary: Knowledge Translation Transmutation Core - Transforming translations into gold-standard quality
Author-email: KTTC AI <dev@kt.tc>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/kttc-ai/kttc
Project-URL: Repository, https://github.com/kttc-ai/kttc
Project-URL: Issues, https://github.com/kttc-ai/kttc/issues
Keywords: translation,qa,quality-assurance,llm,agents,automation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: typer>=0.20.0
Requires-Dist: rich>=14.2.0
Requires-Dist: defusedxml>=0.7.1
Requires-Dist: pydantic>=2.12.4
Requires-Dist: pydantic-settings>=2.11.0
Requires-Dist: aiohttp>=3.13.2
Requires-Dist: openai>=2.8.1
Requires-Dist: anthropic>=0.74.0
Requires-Dist: aiosqlite>=0.21.0
Requires-Dist: orjson>=3.11.4
Requires-Dist: fastapi>=0.121.3
Requires-Dist: uvicorn>=0.38.0
Requires-Dist: websockets>=15.0.1
Requires-Dist: sacrebleu>=2.5.1
Requires-Dist: mtdata>=0.4.3
Requires-Dist: mawo-core[all]>=0.1.3
Requires-Dist: language-tool-python>=3.1.0
Provides-Extra: metrics
Requires-Dist: sentence-transformers>=5.1.2; extra == "metrics"
Provides-Extra: nlp
Requires-Dist: spacy>=3.8.11; extra == "nlp"
Provides-Extra: chinese
Requires-Dist: jieba>=0.42.1; extra == "chinese"
Requires-Dist: hanlp>=2.1.3; extra == "chinese"
Provides-Extra: hindi
Requires-Dist: indic-nlp-library>=0.92; extra == "hindi"
Requires-Dist: stanza>=1.11.0; extra == "hindi"
Requires-Dist: spello>=1.3.0; extra == "hindi"
Provides-Extra: persian
Requires-Dist: dadmatools[full]>=2.3.6; extra == "persian"
Provides-Extra: all-languages
Requires-Dist: spacy>=3.8.11; extra == "all-languages"
Requires-Dist: jieba>=0.42.1; extra == "all-languages"
Requires-Dist: hanlp>=2.1.3; extra == "all-languages"
Requires-Dist: indic-nlp-library>=0.92; extra == "all-languages"
Requires-Dist: stanza>=1.11.0; extra == "all-languages"
Requires-Dist: spello>=1.3.0; extra == "all-languages"
Requires-Dist: dadmatools[full]>=2.3.6; extra == "all-languages"
Provides-Extra: dev
Requires-Dist: pytest>=9.0.1; extra == "dev"
Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=1.3.0; extra == "dev"
Requires-Dist: black>=25.11.0; extra == "dev"
Requires-Dist: ruff>=0.14.6; extra == "dev"
Requires-Dist: mypy>=1.18.2; extra == "dev"
Requires-Dist: pre-commit>=4.5.0; extra == "dev"
Requires-Dist: types-requests>=2.32.4; extra == "dev"
Requires-Dist: types-tqdm>=4.67.0; extra == "dev"
Requires-Dist: mkdocs>=1.6.1; extra == "dev"
Requires-Dist: mkdocs-material>=9.7.0; extra == "dev"
Requires-Dist: mkdocstrings[python]>=0.30.1; extra == "dev"
Requires-Dist: mkdocs-autorefs>=1.4.3; extra == "dev"
Dynamic: license-file

<p align="center">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="docs/content/assets/img/kttc.logo-dark.png">
      <source media="(prefers-color-scheme: light)" srcset="docs/content/assets/img/kttc.logo.png">
      <img alt="KTTC" title="KTTC" src="docs/content/assets/img/kttc.logo.png">
    </picture>
</p>

**English** · [Русский](README.ru.md) · [中文](README.zh.md) · [हिन्दी](README.hi.md) · [فارسی](README.fa.md)

# KTTC - Knowledge Translation Transmutation Core

[![CI](https://github.com/kttc-ai/kttc/workflows/CI/badge.svg)](https://github.com/kttc-ai/kttc/actions)
[![CodeQL](https://github.com/kttc-ai/kttc/workflows/CodeQL/badge.svg)](https://github.com/kttc-ai/kttc/security/code-scanning)
[![PyPI](https://img.shields.io/pypi/v/kttc)](https://pypi.org/project/kttc/)
[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)

**Autonomous AI-powered translation quality assurance**

KTTC uses specialized multi-agent systems to automatically detect, analyze, and fix translation quality issues following the industry-standard MQM (Multidimensional Quality Metrics) framework. Get production-ready translation quality in seconds, not hours.

---

## Key Features

- **Multi-Agent QA System** - 5 specialized agents analyze accuracy, fluency, terminology, hallucinations, and context
- **MQM Scoring** - Industry-standard quality metrics used in WMT benchmarks
- **Smart Routing** - Automatically selects optimal models based on text complexity (60% cost savings)
- **Auto-Correction** - LLM-powered error fixing with iterative refinement (TEaR loop)
- **Language-Specific Agents** - Native-level checks for English, Chinese, Russian, Hindi, and Persian
- **Self-Check / Proofreading** - Grammar, spelling, punctuation checking using school curriculum rules
- **Translation Memory** - Semantic search with quality tracking and reuse
- **Glossary Management** - Custom terminology + school curriculum glossaries (FGOS, UK GPS, NCERT, PEP)
- **Batch Processing** - Process thousands of translations in parallel
- **CI/CD Ready** - GitHub Actions integration, exit codes, multiple output formats
- **Multi-LLM Support** - OpenAI, Anthropic, GigaChat, YandexGPT

**Performance:** 90% cost reduction vs manual review • 100-1000x faster • 95+ MQM quality target

---

## Try KTTC Online

Experience KTTC without installation:

[![Open in Colab](https://img.shields.io/badge/Open_in_Colab-F9AB00?style=for-the-badge&logo=googlecolab&logoColor=white)](https://colab.research.google.com/github/kttc-ai/kttc/blob/main/examples/kttc_demo.ipynb)
[![Streamlit Demo](https://img.shields.io/badge/Streamlit_Demo-FF4B4B?style=for-the-badge&logo=streamlit&logoColor=white)](https://kttc-demo.streamlit.app)
[![Open in Codespaces](https://img.shields.io/badge/Open_in_Codespaces-181717?style=for-the-badge&logo=github&logoColor=white)](https://github.com/codespaces/new?repo=kttc-ai/kttc)

- **Google Colab** - Interactive tutorial with examples (5 min, no setup)
- **Streamlit Demo** - Web UI to test your own translations (no code required)
- **GitHub Codespaces** - Full dev environment in browser (for contributors)

---

## Quick Start

### 1. Install

```bash
pip install kttc
```

Optional language enhancements:

```bash
pip install kttc[english]        # English: LanguageTool (5,000+ grammar rules)
pip install kttc[chinese]        # Chinese: HanLP (measure words, particles)
pip install kttc[hindi]          # Hindi: Indic NLP + Stanza + Spello
pip install kttc[persian]        # Persian: DadmaTools (spaCy-based)
pip install kttc[all-languages]  # All language helpers
```

### 2. Set API Key

```bash
export KTTC_OPENAI_API_KEY="sk-..."
# or
export KTTC_ANTHROPIC_API_KEY="sk-ant-..."
```

### 3. Check Translation Quality

```bash
kttc check source.txt translation.txt --source-lang en --target-lang es
```

**Output:**

```
✅ MQM Score: 96.5 (PASS - Excellent Quality)
📊 5 agents analyzed translation
⚠️  Found 2 minor issues, 0 major, 0 critical
✓ Quality threshold met (≥95.0)
```

That's it! KTTC works out of the box with smart defaults:
- ✅ Smart routing (auto-selects cheaper models for simple texts)
- ✅ Auto-glossary (uses 'base' glossary if exists)
- ✅ Auto-format (detects output format from file extension)

---

## Commands

KTTC provides a unified CLI with smart auto-detection:

```bash
kttc check source.txt translation.txt          # Single quality check
kttc check source.txt t1.txt t2.txt t3.txt     # Auto-compares multiple translations
kttc check translations.csv                     # Auto-detects batch mode (CSV/JSON)
kttc check source_dir/ trans_dir/              # Auto-detects directory batch mode

kttc batch --file translations.csv              # Explicit batch processing
kttc compare --source src.txt -t t1 -t t2      # Compare translations side-by-side
kttc translate --text "Hello" --source-lang en --target-lang es  # Translate with QA
kttc benchmark --source text.txt --providers openai,anthropic    # Benchmark LLMs

# Glossary management (project + user global storage)
kttc glossary list                              # List all glossaries
kttc glossary create tech --from-csv terms.csv  # Create project glossary
kttc glossary create personal --from-csv my.csv --user  # Create user glossary

# 🥚 Self-check / Proofreading (new!)
kttc check article.md --self --lang ru          # Proofread without translation
kttc proofread article.md --lang ru             # Same as above (alias)
kttc lint article.md --lang ru --fix            # Quick rule-based check (no LLM)
```

**See full command reference:** [docs/en/reference/cli-commands.md](docs/en/reference/cli-commands.md)

---

## Python API

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

async def check_quality():
    llm = OpenAIProvider(api_key="your-key")
    orchestrator = AgentOrchestrator(llm)

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

    report = await orchestrator.evaluate(task)
    print(f"MQM Score: {report.mqm_score}")
    print(f"Status: {report.status}")

asyncio.run(check_quality())
```

**See full API reference:** [docs/en/reference/api-reference.md](docs/en/reference/api-reference.md)

---

## Documentation

📚 **Complete documentation is available in [docs/](docs/)**

### Quick Links

- **[Quickstart Guide](docs/en/tutorials/quickstart.md)** - Get started in 5 minutes
- **[Installation Guide](docs/en/guides/installation.md)** - Detailed setup instructions
- **[CLI Reference](docs/en/reference/cli-commands.md)** - All commands and options
- **[Architecture](docs/en/explanation/architecture.md)** - How KTTC works
- **[Language Features](docs/en/explanation/language-features-explained.md)** - English/Chinese/Russian specialization

### Documentation Structure

Following the [Diátaxis](https://diataxis.fr/) framework:

- 📚 **[Tutorials](docs/en/tutorials/README.md)** - Learn by doing (step-by-step guides)
- 📖 **[Guides](docs/en/guides/README.md)** - Solve specific problems (how-to guides)
- 📋 **[Reference](docs/en/reference/README.md)** - Look up technical details (API, CLI)
- 💡 **[Explanation](docs/en/explanation/README.md)** - Understand concepts (architecture, design)

### Translations

**Languages:** 🇺🇸 [English](docs/en/) (primary) · 🇷🇺 [Русский](README.ru.md) · 🇨🇳 [中文](README.zh.md) · 🇮🇳 [हिन्दी](README.hi.md) · 🇮🇷 [فارسی](README.fa.md)

Full documentation available in:
- 🇺🇸 **[English](docs/en/README.md)** - Complete (primary source)
- 🇷🇺 **[Русский](docs/ru/README.md)** - Complete
- 🇨🇳 **[中文](docs/zh/README.md)** - Complete
- 🇮🇳 **[हिन्दी](docs/hi/README.md)** - Complete
- 🇮🇷 **[فارسی](docs/fa/README.md)** - Complete

---

## Development

### Setup

```bash
git clone https://github.com/kttc-ai/kttc.git
cd kttc
python3.11 -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
pre-commit install
```

### Quality Standards

- **Type Checking:** mypy --strict
- **Formatting:** black (line length: 100)
- **Linting:** ruff
- **Testing:** pytest with asyncio support

```bash
# Run all checks
pre-commit run --all-files
pytest --cov=kttc
```

---

## Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

**Quick start:**
1. Fork the repository
2. Create a feature branch
3. Make changes and add tests
4. Run quality checks: `pre-commit run --all-files && pytest`
5. Submit a pull request

Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.

---

## Security

For security vulnerabilities, see [SECURITY.md](SECURITY.md). Do not open public issues for security concerns.

---

## License

Licensed under the Apache License 2.0. See [LICENSE](LICENSE) for details.

Copyright 2025 KTTC AI (https://github.com/kttc-ai)

---

## Citation

If you use KTTC in your research:

```bibtex
@software{kttc2025,
  title = {KTTC: Knowledge Translation Transmutation Core},
  author = {KTTC AI},
  year = {2025},
  url = {https://github.com/kttc-ai/kttc},
  version = {0.1.0}
}
```

---

## Links

- 📦 [PyPI Package](https://pypi.org/project/kttc/)
- 📖 [Documentation](docs/)
- 🐛 [Issue Tracker](https://github.com/kttc-ai/kttc/issues)
- 💬 [Discussions](https://github.com/kttc-ai/kttc/discussions)
- 🔒 [Security Policy](SECURITY.md)
