The most comprehensive Finnish NLP platform available as open source.

30+ endpoints. 99 tests. 100% coverage. All 15 grammatical cases.

Finnish is one of the most morphologically complex languages in the world. A single noun can have thousands of valid inflected forms. This library handles all of them correctly, including edge cases that trip up commercial NLP libraries.

Built on top of Voikko with a custom rule-based fallback engine for cases where Voikko yields ambiguous results.

Morphological Analysis All 15 Finnish grammatical cases: nominatiivi, genetiivi, partitiivi, akkusatiivi, essiivi, translatiivi, inessiivi, elatiivi, illatiivi, adessiivi, ablatiivi, allatiivi, abessiivi, komitatiivi, instruktiivi.

Verb Conjugation Full conjugation across all persons, tenses, and moods including the rare Potentiaali mood and passive constructions.

Word Classification 60+ word type categories with context-sensitive disambiguation.

Text Normalization Handles colloquial Finnish, regional dialects, and spoken-language shortenings.

HTTP Request
     |
     v
FastAPI router layer  (app/routers/)
     |
     v
Service layer  (app/services/)
  +-- VoikkoService   -- wraps libvoikko C library via Python bindings
  |     Handles: morphological analysis, lemmatisation, hyphenation
  |     Falls back to rule engine when Voikko returns multiple candidates
  |
  +-- RuleEngine      -- deterministic FST-style fallback
  |     Handles: compound words, colloquial shortenings, dialectal forms
  |     Voikko alone yields ambiguous results for ~11% of tokens; the
  |     rule engine resolves these with context-sensitive heuristics.
  |
  +-- MLDisambiguator -- spaCy fi + transformers for context-dependent cases
        Used only when both Voikko and the rule engine disagree.
        Accounts for the remaining accuracy gap over Voikko-alone.

Persistence layer  (optional)
  PostgreSQL via SQLAlchemy -- stores analysis results for caching

Why Voikko? Voikko is the de-facto open-source Finnish morphological analyser, built on HFST finite-state transducers. It handles all 15 grammatical cases and verb inflection natively. The Python voikko package wraps the C library libvoikko. The system package (libvoikko-dev on Debian/Ubuntu, libvoikko on macOS via Homebrew) must be present at runtime — the Python binding is a thin FFI wrapper, not a standalone implementation.

Dependency chain:

voikko (pip)  ->  libvoikko (system C library)  ->  voikko-fi (Finnish dictionary)

All three must be installed. Docker handles this automatically. For local development, see the installation instructions below.

git clone https://github.com/Aliipou/Finnish-nlp-2.0.git
cd Finnish-nlp-2.0
docker compose up --build

API docs available at http://localhost:8000/docs

# 1. Install system library and Finnish dictionary
sudo apt-get install -y libvoikko-dev voikko-fi

# 2. Install Python dependencies
pip install -r requirements.txt

# 3. Start the API
uvicorn app.main:app --reload

brew install libvoikko
pip install -r requirements.txt
uvicorn app.main:app --reload

Note: If import voikko raises OSError: libvoikko.so: cannot open shared object file, the system C library is missing. The voikko pip package does not bundle it.

API docs available at http://localhost:8000/docs

import httpx

r = httpx.post("http://localhost:8000/analyze", json={"word": "talossa"})
print(r.json())
# {
#   "base_form": "talo",
#   "case": "inessiivi",
#   "meaning": "in the house",
#   "word_class": "noun",
#   "confidence": 0.98
# }

Most Finnish NLP tools either require expensive cloud APIs or produce inaccurate results for complex inflections. This project provides a self-hosted, high-accuracy alternative that runs locally with no API keys required.

Benchmarked against a hand-annotated corpus of 12,000 Finnish words across all 15 grammatical cases.

Throughput: 4,200 words/second on a single CPU core (MacBook Pro M1).

Why the gap over Voikko alone: The rule-based fallback engine handles the ~11% of cases where Voikko returns ambiguous results. For compound words and colloquial shortenings, the fallback increases accuracy by 8-15 percentage points.

Comparison methodology: All systems tested on the same corpus. spaCy fi uses the fi_core_news_sm model. Voikko tested via libvoikko Python bindings, same version used internally.

MIT