Bootstrap a Taxonomy with AI

This cookbook shows you how to use the platform’s AI to automatically generate custom taxonomies. Instead of manually defining tags one by one, you can describe your use case in natural language, and the AI will propose a complete taxonomy for you.

AI-Generated Taxonomies

taxonomy.generate_from_context bootstraps a taxonomy from a free-form description of your data. Nothing is saved, so you can review the result first:

from deasy import DeasyClient

client = DeasyClient(
    base_url="https://unstructured.your-company.com/rest/unstructured",
    username="your-username",
    password="your-password",
)

suggestion = client.taxonomy.generate_from_context(
    user_context="""
    I need to analyze legal contracts. Extract key terms, financial obligations,
    risk indicators, important dates, and anything relevant for compliance.
    Focus on NDAs, MSAs, and employment agreements.
    """,
)

# Review the suggestion before saving anything
print(suggestion.taxonomy_description)
print(suggestion.taxonomy_data)  # the taxonomy graph: nodes (tags) and edges (conditions)
print(suggestion.suggested_tags)

Optional parameters steer the result: industry, data_type, use_case, taxonomy_type (default hierarchical) and max_depth (default 3).

Validate Against Your Documents

For higher accuracy, pass the data source’s id and set validate_tags=True. The platform samples that data source’s files and scores the suggested tags against them; tag_not_found_rates reports how often each tag was not found in the sample.

page = client.get("/v2/datasources", options={"params": {"name": "my-documents"}}, cast_to=object)
rows = page["results"]
# Prefer the connection you own if a shared one has the same name
datasource_id = next((r["datasource_id"] for r in rows if r["is_owner"]), rows[0]["datasource_id"])

suggestion = client.taxonomy.generate_from_context(
    user_context="Extract key data from these vendor invoices",
    datasource_id=datasource_id,
    validate_tags=True,
)

for tag, rate in (suggestion.tag_not_found_rates or {}).items():
    if rate >= 0:
        print(f"{tag}: not found in {rate:.0%} of sampled files")

A rate of -1 means there is no score for that tag. Validation was not requested, no sample files were found, or validation failed. Without a data source and validate_tags=True, every tag reports -1.

generate_from_context takes the data source by id only. The lookup above is the same name-to-id lookup described in the SDK README.

Create the Tags

Once you are happy with the suggestion, create its tags with tags.upsert. Each entry in suggested_tags is keyed by tag name:

for name, tag in suggestion.suggested_tags.items():
    client.tags.upsert(tag_data={
        "name": name,
        "description": tag["description"],
        "output_type": tag["output_type"],
    })

Add tags the AI missed the same way:

client.tags.upsert(tag_data={
    "name": "reviewed_by_legal",
    "description": "Whether this contract has been reviewed",
    "output_type": "binary",
})

The suggested graph names its nodes by tag name, while a saved taxonomy refers to tags by id, so don’t pass suggestion.taxonomy_data to taxonomy.upsert as returned. Use the suggestion as a blueprint for the tags above.

Common Use Cases

Financial Reports
Resumes
Insurance Claims

client.taxonomy.generate_from_context(
    user_context="""
    Analyze quarterly financial reports. Extract revenue, earnings,
    growth metrics, risk factors, and forward guidance.
    """,
    industry="finance",
)

client.taxonomy.generate_from_context(
    user_context="""
    Process resumes for technical recruiting. Extract skills,
    experience level, education, and certifications.
    """,
    use_case="recruiting",
)

client.taxonomy.generate_from_context(
    user_context="""
    Analyze insurance claims. Extract claim details, incident info,
    injury status, and potential fraud indicators.
    """,
    industry="insurance",
)

Next Steps

Organize a SharePoint Library

Enrich libraries at the source with your taxonomy.

Clean Up a RAG Index

Curate a serving collection with your taxonomy.

Protect Sensitive Data

Add sensitive data detection.

Taxonomies Concept

Learn the fundamentals of taxonomies.

Getting Started

Core Concepts

Live Map

Cookbooks

Integrations

Bootstrap a Taxonomy with AI

AI-Generated Taxonomies

Validate Against Your Documents

Create the Tags

Common Use Cases

Next Steps

Organize a SharePoint Library

Clean Up a RAG Index

Protect Sensitive Data

Taxonomies Concept

​AI-Generated Taxonomies

​Validate Against Your Documents

​Create the Tags

​Common Use Cases

​Next Steps

Organize a SharePoint Library

Clean Up a RAG Index

Protect Sensitive Data

Taxonomies Concept

AI-Generated Taxonomies

Validate Against Your Documents

Create the Tags

Common Use Cases

Next Steps