FOLIO Python Library

The FOLIO Python Library is the official reference implementation for working with the Federated Open Legal Information Ontology (FOLIO) — an open, CC-BY licensed standard of more than 18,000 standardized legal concepts spanning areas of law, document types, jurisdictions, governmental bodies, services, and more.

It gives developers, researchers, and legal professionals a single, well-typed Python API for loading the ontology, searching it by label, definition, prefix, or natural language, querying it with structured filters, traversing its taxonomy, exploring object-property relationships, and exporting classes to JSON, JSON-LD, OWL XML, or Markdown.

The library is designed to be easy to install, fast to use, and gentle on dependencies — the base install is just pydantic, lxml, and httpx. Optional fuzzy and LLM search live behind a single [search] extra so it stays lightweight when you don’t need them.

Documentation

The reference is split into focused sub-pages. Start with Getting Started if you’re new, or jump straight to the topic you need.

Quick Start

# Install: uv add 'folio-python[search]'  (or: pip install 'folio-python[search]')
from folio import FOLIO

# Initialize the FOLIO client (loads ontology from GitHub, caches locally)
folio = FOLIO()

# Search for a class by label
result, score = folio.search_by_label("southern district new york")[0]
print(f"{result.iri} (Score: {score})")
print(f"Preferred Label: {result.preferred_label}")
print(f"Synonyms: {result.alternative_labels}")
print(f"Parents: {[folio[c].label for c in result.sub_class_of]}")

# Output:
# https://folio.openlegalstandard.org/RB8D8b89B9b18DB928b27dfe (Score: 95.0)
# Preferred Label: District Court, S.D. New York
# Synonyms: ['S.D. N.Y.', 'S.D.N.Y.', 'SDNY', 'Southern District of New York', 'NYSD']
# Parents: ['U.S. District Courts']

That’s it — six lines of code to look up the U.S. District Court for the Southern District of New York with all of its known synonyms and parent classes.

For more, head to Getting Started.

Overview

The FOLIO Python Library provides:

• Loading the FOLIO ontology from GitHub or a custom HTTP URL, with transparent local caching at ~/.folio/cache/
• Class access by short IRI (R8BD30978Ccbc4C2f0f8459f), prefixed namespace (folio:R8BD…), full URI, or integer position — with legacy lmss.sali.org and soli: IRIs normalized automatically
• Lexical search by label and definition via rapidfuzz (WRatio for labels, partial-token-set-ratio for definitions)
• Prefix search via a marisa-trie index — case-insensitive by default since 0.3.5, with primary-label matches ranked ahead of alt-label matches
• Structured queries with composable text and structural filters (query(), query_properties()) supporting substring, exact, regex, and fuzzy match modes
• Taxonomy traversal through 24 branch helpers (get_areas_of_law, get_locations, get_industries, get_services, …) plus get_parents, get_children, and get_subgraph with depth limits
• Object properties and relationships via get_all_properties, find_connections, and the raw triples API (get_triples_by_subject/predicate/object)
• LLM-backed semantic search via search_by_llm and parallel_search_by_llm, with pluggable providers (OpenAI, Anthropic, Grok, Google, vLLM, Together) and effort/tier tuning
• Serialization to JSON, JSON-LD, OWL XML, and Markdown for individual classes; JSONL prompt formatting for LLM workflows

The library currently loads the FOLIO 2.0.0 ontology by default — 18,323 classes, 130,427 RDF triples, 175 object properties — in roughly 1.5 seconds on a cold cache and around 1.1 seconds on subsequent loads.

Installation

Add it to your project with uv (recommended) or pip:

# uv (recommended)
uv add 'folio-python[search]'

# pip
pip install 'folio-python[search]'

The [search] extra pulls in rapidfuzz, marisa-trie, and alea-llm-client to enable search_by_label, search_by_definition, search_by_prefix, the fuzzy match mode of query(), and all LLM search methods. If you only need loading, parsing, traversal, and serialization, omit the extra:

# Base install (pydantic, lxml, httpx only)
uv add folio-python
# or: pip install folio-python

For the latest development version from main:

# uv
uv add 'folio-python[search] @ git+https://github.com/alea-institute/folio-python@main'

# pip
pip install --upgrade 'folio-python[search] @ https://github.com/alea-institute/folio-python/archive/refs/heads/main.zip'

Migrating from soli-python? The package was renamed from soli-python (v0.1.x) to folio-python to match the FOLIO standard. Uninstall the old package first (pip uninstall soli-python) and install folio-python to avoid dependency conflicts.

For full installation details and configuration options, see Getting Started.

Contributing

Contributions to the FOLIO Python library are welcome! If you’d like to contribute, please follow these steps:

1. Fork the repository
2. Create a new branch for your feature or bug fix
3. Make your changes and write tests if applicable
4. Run the test suite to ensure everything is working
5. Submit a pull request with a clear description of your changes

For more information, see the contribution guidelines.

License

The FOLIO Python library is released under the MIT License. See the LICENSE file for details.

The FOLIO standard itself is available under the Creative Commons Attribution (CC-BY) License.

Support

If you encounter any issues or have questions about using the FOLIO Python library, please open an issue on GitHub or join the discussion on the FOLIO community forum.