Tarakib Multilingual NLP API

Tarakib provides part-of-speech tagging, morphology suggestions, and dependency parsing through one multilingual Sawtone v4 backbone. The API returns spaCy-style token fields and explicit quality evidence for each evaluated language.

Tarakib is a beta. It is suitable for assisted annotation, corpus search, filtering, and other forgiving workflows in languages that pass their task-specific gate. It is not approved for unattended or consequential parsing.

Endpoint

text

POST https://api.sawalni.com/v1/tarakib/analyze

Metadata endpoints:

text

GET https://api.sawalni.com/v1/tarakib/models
GET https://api.sawalni.com/v1/tarakib/languages

Request body

Parameter	Type	Required	Description
`text`	string	Yes*	Raw Unicode text. Maximum 20,000 characters.
`tokens`	string[]	Yes*	Caller-supplied token boundaries. Each item must contain one non-whitespace token.
`language`	string	No	ISO or dataset language code, such as `ar`, `ary`, `en`, or `tzm`.
`tasks`	string[]	No	Any of `pos`, `morphology`, and `dependencies`. All run by default.
`morphology_threshold`	number	No	Include morphology labels at or above this confidence. Range 0.05–0.95. Default 0.5.

*Provide exactly one of text or tokens. A request can contain at most 96 tokens.

curl

bash

curl https://api.sawalni.com/v1/tarakib/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "ذهب الطفل إلى المدرسة.",
    "language": "ar",
    "tasks": ["pos", "morphology", "dependencies"]
  }'

Python

python

import requests

response = requests.post(
    "https://api.sawalni.com/v1/tarakib/analyze",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "text": "The child walked to school.",
        "language": "en",
        "tasks": ["pos", "morphology", "dependencies"],
    },
    timeout=30,
)
response.raise_for_status()
analysis = response.json()
for token in analysis["tokens"]:
    print(token["text"], token["pos"], token["head"], token["dep"])

spaCy adapter

Tarakib is API-compatible with common spaCy token workflows. This helper creates a real spaCy Doc from the response. The returned head is a zero-based absolute token index. A root token points to itself.

python

import requests
import spacy
from spacy.tokens import Doc

def tarakib_doc(text: str, language: str, api_key: str) -> Doc:
    response = requests.post(
        "https://api.sawalni.com/v1/tarakib/analyze",
        headers={"Authorization": f"Bearer {api_key}"},
        json={"text": text, "language": language},
        timeout=30,
    )
    response.raise_for_status()
    result = response.json()

    nlp = spacy.blank("xx")
    rows = result["tokens"]
    doc = Doc(nlp.vocab, words=[row["text"] for row in rows], spaces=[row["space_after"] for row in rows])
    for token, row in zip(doc, rows):
        token.is_sent_start = row["sent_start"]
        token.pos_ = row["pos"]
        token.dep_ = row["dep"]
        token.head = doc[row["head"]]

        # Keep the strongest value for each morphology feature name.
        strongest = {}
        for item in row.get("morphology") or []:
            name = item["feature"].split("=", 1)[0]
            if name not in strongest or item["confidence"] > strongest[name]["confidence"]:
                strongest[name] = item
        token.set_morph("|".join(item["feature"] for item in strongest.values()))
    return doc

doc = tarakib_doc("ذهب الطفل إلى المدرسة.", "ar", "YOUR_API_KEY")
print([(token.text, token.pos_, token.head.text, token.dep_) for token in doc])

Response fields

Each token includes offsets, whitespace, sentence-start state, UPOS, morphology candidates, an absolute head index, dependency relation, and task confidence. The top-level quality object includes the evaluation group, evidence size, intrinsic POS/UAS/LAS scores, and a deployment recommendation.

The benchmark used gold token boundaries. Raw-text tokenization is a separate beta component. For the most controlled evaluation or annotation workflow, supply tokens.

Quality and language coverage

Tarakib learned grammar from 166 training language identities.
The Sawtone v4 backbone contains representations for 389 learned language and variety identifiers.
GET /v1/tarakib/languages returns measured evidence and recommendations.
Other Sawtone languages are accepted as unverified. Do not treat backbone coverage as task validation.
A language hint selects the reported language and evidence record. It does not yet force Sawtone's latent language route.

Confidence is not a guarantee. Use the per-language deployment recommendation before you design a workflow.

Rate and capacity limits

Limit	Value
Requests per API key	60 per minute
Burst	8 requests
Active analyses per key	2
Active analyses globally	4
Maximum tokens	96
Maximum characters	20,000

Responses include standard RateLimit-* and X-RateLimit-* headers. A 429 response includes Retry-After.

Errors

HTTP code	Meaning
400	Empty body or invalid JSON
401	Missing, invalid, or inactive API key
402	Insufficient credits
413	Gateway request body is too large
422	Invalid text, token, task, language, or threshold input
429	Rate or concurrency limit reached
503	Tarakib is unavailable or its queue is full
504	Inference timed out

Metering

A successful analysis uses one request credit. Model and language metadata requests are not billed.

Tarakib Multilingual NLP API

Endpoint

text

POST https://api.sawalni.com/v1/tarakib/analyze

Metadata endpoints:

text

GET https://api.sawalni.com/v1/tarakib/models
GET https://api.sawalni.com/v1/tarakib/languages

Request body

Parameter	Type	Required	Description
`text`	string	Yes*	Raw Unicode text. Maximum 20,000 characters.
`tokens`	string[]	Yes*	Caller-supplied token boundaries. Each item must contain one non-whitespace token.
`language`	string	No	ISO or dataset language code, such as `ar`, `ary`, `en`, or `tzm`.
`tasks`	string[]	No	Any of `pos`, `morphology`, and `dependencies`. All run by default.
`morphology_threshold`	number	No	Include morphology labels at or above this confidence. Range 0.05–0.95. Default 0.5.

*Provide exactly one of text or tokens. A request can contain at most 96 tokens.

curl

bash

curl https://api.sawalni.com/v1/tarakib/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "ذهب الطفل إلى المدرسة.",
    "language": "ar",
    "tasks": ["pos", "morphology", "dependencies"]
  }'

Python

python

import requests

response = requests.post(
    "https://api.sawalni.com/v1/tarakib/analyze",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "text": "The child walked to school.",
        "language": "en",
        "tasks": ["pos", "morphology", "dependencies"],
    },
    timeout=30,
)
response.raise_for_status()
analysis = response.json()
for token in analysis["tokens"]:
    print(token["text"], token["pos"], token["head"], token["dep"])

spaCy adapter

python

import requests
import spacy
from spacy.tokens import Doc

def tarakib_doc(text: str, language: str, api_key: str) -> Doc:
    response = requests.post(
        "https://api.sawalni.com/v1/tarakib/analyze",
        headers={"Authorization": f"Bearer {api_key}"},
        json={"text": text, "language": language},
        timeout=30,
    )
    response.raise_for_status()
    result = response.json()

    nlp = spacy.blank("xx")
    rows = result["tokens"]
    doc = Doc(nlp.vocab, words=[row["text"] for row in rows], spaces=[row["space_after"] for row in rows])
    for token, row in zip(doc, rows):
        token.is_sent_start = row["sent_start"]
        token.pos_ = row["pos"]
        token.dep_ = row["dep"]
        token.head = doc[row["head"]]

        # Keep the strongest value for each morphology feature name.
        strongest = {}
        for item in row.get("morphology") or []:
            name = item["feature"].split("=", 1)[0]
            if name not in strongest or item["confidence"] > strongest[name]["confidence"]:
                strongest[name] = item
        token.set_morph("|".join(item["feature"] for item in strongest.values()))
    return doc

doc = tarakib_doc("ذهب الطفل إلى المدرسة.", "ar", "YOUR_API_KEY")
print([(token.text, token.pos_, token.head.text, token.dep_) for token in doc])

Response fields

The benchmark used gold token boundaries. Raw-text tokenization is a separate beta component. For the most controlled evaluation or annotation workflow, supply tokens.

Quality and language coverage

Tarakib learned grammar from 166 training language identities.
The Sawtone v4 backbone contains representations for 389 learned language and variety identifiers.
GET /v1/tarakib/languages returns measured evidence and recommendations.
Other Sawtone languages are accepted as unverified. Do not treat backbone coverage as task validation.
A language hint selects the reported language and evidence record. It does not yet force Sawtone's latent language route.

Confidence is not a guarantee. Use the per-language deployment recommendation before you design a workflow.

Rate and capacity limits

Limit	Value
Requests per API key	60 per minute
Burst	8 requests
Active analyses per key	2
Active analyses globally	4
Maximum tokens	96
Maximum characters	20,000

Responses include standard RateLimit-* and X-RateLimit-* headers. A 429 response includes Retry-After.

Errors

HTTP code	Meaning
400	Empty body or invalid JSON
401	Missing, invalid, or inactive API key
402	Insufficient credits
413	Gateway request body is too large
422	Invalid text, token, task, language, or threshold input
429	Rate or concurrency limit reached
503	Tarakib is unavailable or its queue is full
504	Inference timed out

Metering

A successful analysis uses one request credit. Model and language metadata requests are not billed.