# LangChain tools

> The official fluentc-langchain-tool Python package. Install it, translate in real time or batch, detect languages, and give a LangChain agent FluentC as tools.

Source: https://www.fluentc.ai/docs/integrations/langchain/

`fluentc-langchain-tool` is the official Python package for using FluentC from LangChain. Each capability is a LangChain tool (a `BaseTool` subclass), so you can call it directly or hand it to an agent.

- **Requires:** Python 3.8 or newer and LangChain.
- **Authentication:** your FluentC API key, passed to each tool's constructor. See [Authentication](https://www.fluentc.ai/docs/authentication.md).
- **Source of truth:** the package's page on [PyPI](https://pypi.org/project/fluentc-langchain-tool/).

## Install

```bash
pip install fluentc-langchain-tool
```

```python
import os

API_KEY = os.environ["FLUENTC_KEY"]
```

## The tools

| Class | Tool name | What it does |
| --- | --- | --- |
| `FluentCTranslationTool` | `fluentc_translation` | Translate in real-time or batch mode |
| `FluentCBatchTranslationTool` | `fluentc_batch_translation` | Submit a batch job and wait for the result |
| `FluentCLanguageDetectorTool` | `fluentc_language_detector` | Detect the language of some text |
| `FluentCTranslationStatusTool` | `fluentc_translation_status` | Check a batch job by `job_id` |
| `FluentCSupportedLanguagesTool` | `fluentc_supported_languages` | List the languages enabled for your key |
| `FluentCResultsTool` | `fluentc_results` | Legacy. Use `fluentc_translation_status` instead |

All tools take the API key as their only constructor argument: `FluentCTranslationTool(api_key=API_KEY)`. Tools return a string, which is what an agent reads back.

## Translate in real time

```python
from fluentc_langchain_tool import FluentCTranslationTool

tool = FluentCTranslationTool(api_key=API_KEY)

result = tool.run({
    "text": "Hello, world!",
    "target_language": "fr",
    "source_language": "en",
    "mode": "realtime",
})
print(result)  # Bonjour, le monde !
```

Input fields for `fluentc_translation`:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `text` | string or list of strings | Yes | What to translate. |
| `target_language` | string | Yes | Target language code, such as `fr`. |
| `source_language` | string | Yes | Source language code, such as `en`. |
| `mode` | string | No | `realtime` (default) or `batch`. |
| `callback_url` | string | No | For batch mode: a URL to notify when the job completes. |

Real-time mode needs the Real-time plan. See [Concepts](https://www.fluentc.ai/docs/concepts.md#plans-and-modes).

## Translate in batch

`FluentCBatchTranslationTool` submits the job and polls until it finishes or `max_wait_time` runs out:

```python
from fluentc_langchain_tool import FluentCBatchTranslationTool

tool = FluentCBatchTranslationTool(api_key=API_KEY)

result = tool.run({
    "text": "<html>Hello, batch world!</html>",
    "target_language": "de",
    "source_language": "en",
})
print(result)  # the translated output, once the job completes
```

Input fields for `fluentc_batch_translation`:

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `text` | string or list of strings | required | What to translate. |
| `target_language` | string | required | Target language code. |
| `source_language` | string | required | Source language code. |
| `wait_for_completion` | boolean | `true` | Set `false` to return the job ID immediately. |
| `max_wait_time` | integer | `300` | Seconds to wait before giving up. |
| `callback_url` | string | none | A URL to notify when the job completes. |

To control the loop yourself, set `wait_for_completion` to `false` and check the job with `FluentCTranslationStatusTool`:

```python
from fluentc_langchain_tool import FluentCTranslationStatusTool

status = FluentCTranslationStatusTool(api_key=API_KEY)
print(status.run({"job_id": "abc123def456"}))
```

## Detect a language

```python
from fluentc_langchain_tool import FluentCLanguageDetectorTool

detector = FluentCLanguageDetectorTool(api_key=API_KEY)
print(detector.run({"text": "Hola, ¿cómo estás?"}))
# Detected language: es (confidence: 0.99)
```

## List supported languages

```python
from fluentc_langchain_tool import FluentCSupportedLanguagesTool

languages = FluentCSupportedLanguagesTool(api_key=API_KEY)
print(languages.run({}))
```

## Use the tools in an agent

Pass the tools to any LangChain agent. The tool names and descriptions tell the model when to use each one.

```python
from langchain.agents import initialize_agent
from langchain.llms import OpenAI
from fluentc_langchain_tool import (
    FluentCTranslationTool,
    FluentCLanguageDetectorTool,
)

agent = initialize_agent(
    tools=[
        FluentCTranslationTool(API_KEY),
        FluentCLanguageDetectorTool(API_KEY),
    ],
    llm=OpenAI(temperature=0),
    agent="zero-shot-react-description",
)

agent.run("Translate 'Hello world' from English to German using FluentC.")
```

This example uses LangChain's classic `initialize_agent` interface. The tools are standard `BaseTool` objects, so they work with newer LangChain agent constructors too.

## Errors

The tools catch API errors and return them as a readable string, for example `Translation error: ...`, instead of raising. An agent can read that and recover or report it. If you need exceptions, call the [REST API](https://www.fluentc.ai/docs/api/translate.md) directly.

The usual causes are on the [Errors](https://www.fluentc.ai/docs/api/errors.md) page: a language that isn't enabled for your key, a real-time request on a Batch plan key, or a key problem.