Use an existing taxonomy instead of generating one. Useful when you want to label documents with known categories.
# From a JSON/CSV filedelve = Delve(predefined_taxonomy="categories.json")# Or as a list of dictsdelve = Delve(predefined_taxonomy=[ {"id": "1", "name": "Bug", "description": "Bug reports and issues"}, {"id": "2", "name": "Feature", "description": "Feature requests"},])
When provided, Delve skips taxonomy discovery and directly labels documents using the given categories.
OpenAI embedding model for classifier training. Used when sample_size < total documents to train an efficient classifier for labeling remaining documents.
Minimum confidence for classifier predictions. Documents below this threshold fall back to LLM labeling. Set to 0 to use classifier for all documents (no fallback).
delve = Delve(classifier_confidence_threshold=0.8) # Use LLM for low-confidence docs
Fast, lightweight binary detection for finding documents matching a single category. Uses hybrid semantic + keyword matching without running the full taxonomy pipeline.
from delve import Delveresult = Delve.find_matches( "data.csv", category={ "name": "Refund Request", "description": "User asking for refund, money back, or cancellation", "keywords": ["refund", "money back", "cancel order"], }, text_column="content", threshold=0.6,)# All documents returned with scoresprint(f"Found {result.stats['matches']} matches")# Access matched documents (category != None)for doc in result.matched_documents[:5]: print(f"{doc.id}: {doc.confidence:.2f}")
The result.metadata dictionary contains comprehensive run statistics:
result.metadata = { # Basic info "num_documents": 5000, # Total documents processed "num_categories": 10, # Number of taxonomy categories "sample_size": 100, # Configured sample size "batch_size": 200, # Configured batch size "model": "anthropic/claude-sonnet-4-5-20250929", "fast_llm": "anthropic/claude-haiku-4-5-20251001", # Timing "run_duration_seconds": 145.32, # Total processing time # Category distribution "category_counts": { # Documents per category "Bug Fix": 1250, "Feature Request": 890, "Question": 650, ... }, # Labeling breakdown "llm_labeled_count": 100, # Documents labeled by LLM "classifier_labeled_count": 4900, # Documents labeled by classifier "skipped_document_count": 5, # Documents that couldn't be categorized # Classifier metrics (when classifier is used) "classifier_metrics": { "train_accuracy": 0.92, "test_accuracy": 0.85, "train_f1": 0.91, "test_f1": 0.847 }, # Source information "source": { "type": "csv", # csv, json, dataframe, langsmith, docs "path": "data.csv", "text_column": "content", "id_column": null }, # Quality tracking "warnings": [], # Any processing warnings "status_log": [...] # Step-by-step status messages}
Use category_counts to quickly see how your documents are distributed across categories:
from collections import Counter# Get top 5 categoriestop_categories = Counter(result.metadata["category_counts"]).most_common(5)for category, count in top_categories: print(f"{category}: {count} documents")
The classifier_metrics key is only present when sample_size < total documents, meaning a classifier was trained to label the remaining documents.
from delve import Delvetry: delve = Delve() result = delve.run_sync("data.csv", text_column="text")except ValueError as e: # Missing API key, invalid parameters, etc. print(f"Configuration error: {e}")except FileNotFoundError as e: # File doesn't exist print(f"File not found: {e}")except Exception as e: # Other errors print(f"Error: {e}")
# Requiredexport ANTHROPIC_API_KEY="your-anthropic-key"# Required when sample_size > 0 and docs > sample_size (for classifier embeddings)export OPENAI_API_KEY="your-openai-key"# Optionalexport LANGSMITH_API_KEY="your-langsmith-key"
The OpenAI API key is required for generating embeddings when training the classifier. If you set sample_size=0, all documents are labeled by the LLM and no OpenAI key is needed.
Or use python-dotenv:
from dotenv import load_dotenvload_dotenv()from delve import Delve# API keys are loaded automatically
