LLM Feature Gen
llm-feature-gen turns text, images, tabular files, and videos into interpretable tabular features with LLMs.
Use it when you have raw multimodal data and want a CSV dataset with explicit, human-readable feature columns for analysis, modeling, or inspection.
What It Does
The package follows a two-step workflow:
- Discover a feature schema from example inputs.
- Generate feature values for class-organized data and save CSV files.
Supported workflows include:
- Text:
.txt,.md,.pdf,.docx,.html - Images:
.jpg,.jpeg,.png - Tabular data:
.csv,.xlsx,.xls,.parquet,.json - Video:
.mp4,.mov,.avi,.mkv
The default provider is OpenAI or Azure OpenAI. A local OpenAI-compatible provider is also available for Ollama, vLLM, LM Studio, and similar servers.
Installation
pip install llm-feature-gen
Supported targets are CPython 3.9, 3.11, and 3.13 on Linux, macOS, and Windows. See SUPPORT.md for the current support matrix.
Some file formats need optional runtime dependencies:
pip install pypdf python-docx beautifulsoup4 openpyxl xlrd pyarrow
Video audio extraction also requires the ffmpeg system binary.
Configure a Provider
Create a .env file in the directory where you run your script. For open-source-first and offline-friendly experiments, start with LocalProvider.
Local Provider Setup
LocalProvider talks to any server that exposes an OpenAI-compatible chat-completions API, including Ollama, vLLM, LM Studio, and llama.cpp-compatible gateways.
The provider has separate model settings for text and vision:
| Variable | Default | Purpose |
|---|---|---|
LOCAL_OPENAI_BASE_URL |
http://localhost:11434/v1 |
OpenAI-compatible local API endpoint |
LOCAL_OPENAI_API_KEY |
ollama |
Placeholder key required by the OpenAI SDK; many local servers ignore it |
LOCAL_MODEL_TEXT |
llama3 |
Model used for text discovery and generation |
LOCAL_MODEL_VISION |
llava |
Model used for image and video-frame workflows |
LOCAL_WHISPER_MODEL_SIZE |
base |
Faster-Whisper model size for local audio transcription |
LOCAL_WHISPER_DEVICE |
cpu |
cpu, cuda, or auto for Faster-Whisper |
Ollama Example
Install and start Ollama, then pull one text model and one vision model:
ollama pull llama3
ollama pull llava
ollama serve
Use this .env:
LOCAL_OPENAI_BASE_URL=http://localhost:11434/v1
LOCAL_OPENAI_API_KEY=ollama
LOCAL_MODEL_TEXT=llama3
LOCAL_MODEL_VISION=llava
LOCAL_WHISPER_MODEL_SIZE=base
LOCAL_WHISPER_DEVICE=cpu
Then pass the provider explicitly to both discovery and generation:
from llm_feature_gen import discover_features_from_texts, generate_features_from_texts
from llm_feature_gen.providers import LocalProvider
provider = LocalProvider()
discovered = discover_features_from_texts(
texts_or_file="discover_texts",
provider=provider,
)
csv_paths = generate_features_from_texts(
root_folder="texts",
provider=provider,
merge_to_single_csv=True,
)
print(discovered)
print(csv_paths)
LM Studio or vLLM
Point LOCAL_OPENAI_BASE_URL at the server's OpenAI-compatible /v1 endpoint and set the model names to the identifiers exposed by that server:
LOCAL_OPENAI_BASE_URL=http://localhost:8000/v1
LOCAL_OPENAI_API_KEY=local
LOCAL_MODEL_TEXT=your-text-model
LOCAL_MODEL_VISION=your-vision-model
Video and Audio Locally
Video workflows extract frames and use LOCAL_MODEL_VISION for visual analysis. If use_audio=True, LocalProvider uses faster-whisper for transcription.
Install local transcription support only if you need audio:
pip install faster-whisper
If you do not need audio, or want to avoid the extra dependency, call video helpers with use_audio=False.
Reproducibility Notes
For papers and benchmarks, report the local backend, model names, model versions or hashes, quantization, hardware, and decoding settings. The package defaults to temperature=0.0 in both built-in providers, but local servers can still differ in tokenizer, context length, JSON-mode support, and multimodal formatting.
Local models vary more than hosted APIs in their ability to return strict JSON. For best results, use instruction-tuned models with reliable JSON output and keep discovery batches small enough for the model context window.
OpenAI and Azure OpenAI Setup
Use OpenAIProvider when you want a hosted backend. It auto-detects Azure mode when AZURE_OPENAI_ENDPOINT is set. Otherwise it uses the standard OpenAI API.
For OpenAI:
OPENAI_API_KEY=your_api_key
OPENAI_MODEL=gpt-4.1-mini
OPENAI_AUDIO_MODEL=whisper-1
For Azure OpenAI:
AZURE_OPENAI_API_KEY=your_api_key
AZURE_OPENAI_API_VERSION=your_api_version
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_GPT41_DEPLOYMENT_NAME=your_chat_deployment
AZURE_OPENAI_WHISPER_DEPLOYMENT=your_audio_deployment
AZURE_OPENAI_WHISPER_DEPLOYMENT is only needed for audio transcription (for example, video workflows with use_audio=True).
Completion and structured-output options
from llm_feature_gen.providers import OpenAIProvider
provider = OpenAIProvider(
max_completion_tokens=4096,
reasoning_effort="low", # opt in for reasoning models
)
reasoning_effort defaults to None, so requests use temperature unless reasoning is explicitly enabled. You can choose "none", "minimal", "low", "medium", "high", "xhigh", or "max" when the selected model supports that level. Deployments that reject reasoning_effort are retried without it. max_tokens remains a supported alias for max_completion_tokens; do not pass both. OpenAI and Azure providers use JSON Schema when the selected deployment supports it and automatically fall back to JSON-object mode otherwise. Local and other compatible providers use the JSON shape included in the prompts.
All discovery and generation helpers accept both prompt and system_prompt.
Use prompt for the discovery or generation task and system_prompt for the
model's role and behavior. Generation always appends the discovered feature
specification to a custom task prompt.
Quickstart
This example creates a tiny text dataset, discovers a shared schema, and generates feature-value CSVs.
from pathlib import Path
from llm_feature_gen import discover_features_from_texts, generate_features_from_texts
samples = {
"demo_discover_texts/sample1.txt": "The dish was rich, spicy, and served in a deep bowl.",
"demo_discover_texts/sample2.txt": "The dessert was light, creamy, and topped with fresh fruit.",
"demo_texts/positive/review1.txt": "The meal was vibrant, aromatic, and beautifully plated.",
"demo_texts/negative/review1.txt": "The service was slow and the food arrived cold.",
}
for file_name, text in samples.items():
path = Path(file_name)
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(text, encoding="utf-8")
discovered = discover_features_from_texts("demo_discover_texts")
csv_paths = generate_features_from_texts(
root_folder="demo_texts",
merge_to_single_csv=True,
)
print(discovered)
print(csv_paths)
Expected outputs:
outputs/discovered_text_features.jsonoutputs/positive_feature_values.csvoutputs/negative_feature_values.csvoutputs/all_feature_values.csv
Generation expects one subfolder per class:
demo_texts/
positive/
review1.txt
negative/
review1.txt
Core API
Import the common helpers directly from llm_feature_gen:
from llm_feature_gen import (
discover_features_from_images,
discover_features_from_tabular,
discover_features_from_texts,
discover_features_from_videos,
generate_features_from_images,
generate_features_from_tabular,
generate_features_from_texts,
generate_features_from_videos,
)
Discovery helpers write JSON schemas to outputs/ by default:
| Helper | Default output |
|---|---|
discover_features_from_texts |
outputs/discovered_text_features.json |
discover_features_from_images |
outputs/discovered_image_features.json |
discover_features_from_tabular |
outputs/discovered_tabular_features.json |
discover_features_from_videos |
outputs/discovered_video_features.json |
Generation helpers read the matching schema by default and write one CSV per class. Set merge_to_single_csv=True to also create outputs/all_feature_values.csv.
Text
from llm_feature_gen import discover_features_from_texts, generate_features_from_texts
discover_features_from_texts("discover_texts", min_features=10)
generate_features_from_texts(
root_folder="texts",
merge_to_single_csv=True,
)
scikit-learn Transformer
Install the optional extra when you want to use generated features inside an sklearn pipeline:
pip install "llm-feature-gen[sklearn]"
from llm_feature_gen import LLMFeatureTransformer
from llm_feature_gen.providers import OpenAIProvider
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import OneHotEncoder
from sklearn.linear_model import LogisticRegression
provider = OpenAIProvider(reasoning_effort="low")
pipe = Pipeline([
("llm_features", LLMFeatureTransformer(
provider=provider,
discovery_prompt="Discover useful predictive features.",
generation_prompt="Infer values only from explicit evidence.",
)),
("onehot", OneHotEncoder(handle_unknown="ignore")),
("classifier", LogisticRegression()),
])
pipe.fit(train_texts, train_labels)
predictions = pipe.predict(test_texts)
By default, each fit() discovers a new feature schema, which incurs an LLM call and can vary between runs. For cross-validation or parameter search, pass a saved discovered_features schema to avoid repeated discovery and schema changes.
Images
from llm_feature_gen import discover_features_from_images, generate_features_from_images
discover_features_from_images("discover_images")
generate_features_from_images(
root_folder="images",
merge_to_single_csv=True,
)
Tabular Data
from llm_feature_gen import discover_features_from_tabular, generate_features_from_tabular
discover_features_from_tabular(
file_or_folder="discover_tabular",
text_column="text",
)
generate_features_from_tabular(
root_folder="tabular",
text_column="text",
label_column="label",
merge_to_single_csv=True,
)
Video
from llm_feature_gen import discover_features_from_videos, generate_features_from_videos
discover_features_from_videos(
videos_or_folder="discover_videos",
num_frames=5,
use_audio=True,
)
generate_features_from_videos(
root_folder="videos",
use_audio=True,
merge_to_single_csv=True,
)
Set use_audio=False if you only want visual frames or do not have audio transcription configured.
Batch and Multi-Class Text Workflows
For larger text datasets, use batched generation with an on-disk cache:
from llm_feature_gen import generate_features_from_texts_cached
generate_features_from_texts_cached(
root_folder="texts",
discovered_features_path="outputs/discovered_text_features.json",
batch_size=8,
)
For three or more classes, use the multi-class helpers:
from llm_feature_gen import discover_features_multiclass, generate_features_multiclass
classes = ["billing", "technical", "account"]
discover_features_multiclass(
texts_or_file="discover_texts",
classes=classes,
)
generate_features_multiclass(
root_folder="texts",
discovered_features="outputs/discovered_text_features.json",
classes=classes,
)
End-to-End Example
The repository includes a complete text-to-tabular example with checked-in expected outputs:
python examples/text_to_tabular_pipeline.py --provider auto
For the offline replay path used by tests:
python examples/text_to_tabular_pipeline.py --provider replay --check
See examples/README.md for details.
Development
From a repository checkout:
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest
Build the documentation locally with:
pip install -e ".[docs]"
mkdocs serve
Useful project links:
- Documentation: https://juliayershova.github.io/llm-feature-gen/
- Changelog: CHANGELOG.md
- Contributing guide: CONTRIBUTING.md
- Issues: https://github.com/JuliaYershova/LLM-feature-gen/issues
License
MIT. See LICENSE.
Metadata
Release files for llm-feature-gen 0.1.14
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| llm_feature_gen-0.1.14.tar.gz | 89.7 kB | Without provenance | Details for llm_feature_gen-0.1.14.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| llm_feature_gen-0.1.14-py3-none-any.whl | Python 3 | none | any | Details for llm_feature_gen-0.1.14-py3-none-any.whl |
Total release size: 149.9 kB
Release files / llm_feature_gen-0.1.14.tar.gz
| Download URL | llm_feature_gen-0.1.14.tar.gz |
|---|---|
| Size | 89.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b959f4152ecd764d861306b91ae31a4f084b00fb93692f74a60b281a9ebb94fd
|
|
BLAKE2b-256 checksum How to use checksums |
aaa8c8decfc4f924a7da9392cd71d94990d81aaf10d385a20e9389125cd153c6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.17
|
Release files / llm_feature_gen-0.1.14-py3-none-any.whl
| Download URL | llm_feature_gen-0.1.14-py3-none-any.whl |
|---|---|
| Size | 60.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cf5f40aef6b79d800fa30e6564b59621e5f2a6002a9cad05c864594e2a5a09e7
|
|
BLAKE2b-256 checksum How to use checksums |
f620350fe9d0a7927b16c3b26d936bf5fef681e929a8cc9cbc3e9b764e4630d0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.17
|
Security for llm-feature-gen 0.1.14
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.