Metadata-Version: 2.4
Name: eco-num-extract
Version: 2025.12.22085323
Summary: eco-num-extract turns natural science text into structured numeric data using llmatch-guided outputs.
Author-email: eco-num-extract <hi@eugene.plus>
License: MIT
Project-URL: Homepage, https://github.com/chigwell/eco-num-extract
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: langchain-llm7>=0.0.0
Requires-Dist: llmatch-messages>=0.0.0
Requires-Dist: langchain-core>=0.3.0

# eco-num-extract
[![PyPI version](https://badge.fury.io/py/eco-num-extract.svg)](https://badge.fury.io/py/eco-num-extract)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Downloads](https://static.pepy.tech/badge/eco-num-extract)](https://pepy.tech/project/eco-num-extract)
[![LinkedIn](https://img.shields.io/badge/LinkedIn-blue)](https://www.linkedin.com/in/eugene-evstafev-716669181/)


Extract structured numerical data from natural phenomenon descriptions using AI-powered pattern matching.

## Overview
A Python package that converts qualitative ecological/natural descriptions into structured quantitative insights. Uses `llmatch-messages` to enforce numerical output schemas from LLM responses.

## Installation

```bash
pip install eco_num_extract
```

## Usage

### Basic Usage
```python
from eco_num_extract import eco_num_extract

# Default usage with LLM7
response = eco_num_extract(
    user_input="The forest had 120 trees with 45% canopy cover and 3.2m average height"
)
```

### Custom LLM Integration
Pass your preferred LLM instance (OpenAI, Anthropic, etc.):

```python
from langchain_openai import ChatOpenAI
from eco_num_extract import eco_num_extract

llm = ChatOpenAI()
response = eco_num_extract(
    user_input="Sample text",
    llm=llm  # Your custom LLM instance
)
```

## Parameters

- `user_input` (str): Textual description containing numerical patterns
- `api_key` (str, optional): LLM7 API key (defaults to environment variable)
- `llm` (BaseChatModel, optional): Custom LLM instance (defaults to ChatLLM7)

## Features
- Regex-enforced numerical output structure
- Supports any LLM via LangChain interface
- Environment variable fallback for API keys
- Free tier compatible with LLM7

## Rate Limits
LLM7 free tier provides sufficient throughput. For higher limits:
```python
# Via environment variable
os.environ["LLM7_API_KEY"] = "your_key"

# Or direct parameter
eco_num_extract(api_key="your_key")
```

## Getting Started
1. Install package
2. Get free API key at [LLM7 Token Dashboard](https://token.llm7.io/)
3. Process your ecological descriptions

## Issues
Report problems at [GitHub Issues](https://github.com/chigwell/eco-num-extract/issues)

## Author
Eugene Evstafev - [GitHub](https://github.com/chigwell) | [Email](mailto:hi@euegne.plus)
