ecodynalyze 2025.12.20201125
A new package designed to analyze and summarize ecological studies, specifically focusing on the dynamics of species interactions. Users input text excerpts from research papers or field notes, and th
License: MIT
Requires Python: >=3.9

# **ecodynalyze** – Ecological Study Analysis Package

![PyPI version](https://img.shields.io/pypi/v/ecodynalyze)
![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
![Downloads](https://img.shields.io/pypi/dm/ecodynalyze)
![LinkedIn](https://img.shields.io/badge/LinkedIn-connect-blue)

**Standardize and analyze ecological research data with structured insights.**

---

## **Overview**
`ecodynalyze` is a Python package designed to extract, structure, and summarize key findings from ecological studies. By analyzing text excerpts (e.g., research papers, field notes), it identifies **species interactions, dominance hierarchies, and environmental impacts**, enabling researchers to compare and synthesize data across diverse sources.

The package leverages **LLM7** (default) or custom LLMs (via LangChain) to parse unstructured text and return structured outputs, ensuring consistency and comparability.

---

## **Key Features**
✅ **Structured Data Extraction** – Parses species interactions, dominance patterns, and ecological outcomes.
✅ **Flexible LLM Integration** – Works with **LLM7 (default)**, OpenAI, Anthropic, Google Vertex AI, or any LangChain-compatible model.
✅ **Regex-Pattern Validation** – Ensures extracted data matches predefined formats.
✅ **Environment-Friendly** – Optimized for lightweight, high-accuracy analysis.

---

## **Installation**
```bash
pip install ecodynalyze
```

---

## **Usage Examples**

### **Basic Usage (Default LLM7)**
```python
from ecodynalyze import ecodynalyze

user_input = """
In a 2023 study, researchers observed that species A dominated interactions
with species B in 85% of recorded events, while species C showed minimal
competitive behavior due to habitat constraints.
"""

response = ecodynalyze(user_input)
print(response)
```

### **Custom LLM Integration**
#### **Using OpenAI**
```python
from langchain_openai import ChatOpenAI
from ecodynalyze import ecodynalyze

llm = ChatOpenAI(model="gpt-4")
response = ecodynalyze(user_input, llm=llm)
```

#### **Using Anthropic (Claude)**
```python
from langchain_anthropic import ChatAnthropic
from ecodynalyze import ecodynalyze

llm = ChatAnthropic(model="claude-2")
response = ecodynalyze(user_input, llm=llm)
```

#### **Using Google Vertex AI**
```python
from langchain_google_genai import ChatGoogleGenerativeAI
from ecodynalyze import ecodynalyze

llm = ChatGoogleGenerativeAI(model="gemini-pro")
response = ecodynalyze(user_input, llm=llm)
```

---

## **Parameters**
| Parameter | Type | Description |
|-----------|------|-------------|
| `user_input` | `str` | Text excerpt (e.g., research paper, field notes) to analyze. |
| `api_key` | `Optional[str]` | LLM7 API key (defaults to `LLM7_API_KEY` env var). |
| `llm` | `Optional[BaseChatModel]` | Custom LangChain LLM (e.g., `ChatOpenAI`, `ChatAnthropic`). |

---

## **LLM7 API Key**
- **Default:** Uses `LLM7_API_KEY` environment variable.
- **Manual Override:** Pass via `api_key` parameter.
- **Free Tier:** Sufficient for most use cases (rate limits apply).
- **Upgrade:** Get a custom API key at [LLM7 Token](https://token.llm7.io/).

---

## **Output Format**
The function returns a **list of structured dictionaries** containing:
- Species names
- Interaction types (e.g., competition, predation)
- Dominance patterns
- Environmental context

Example output:
```python
[
    {
        "species1": "A",
        "species2": "B",
        "interaction": "competition",
        "dominance": "A > B (85%)",
        "environment": "habitat-constrained"
    }
]
```

---

## **Contributing & Support**
📢 **Issues & Feedback:** [GitHub Issues](https://github.com/chigwell/ecodynalyze/issues)
📧 **Author:** Eugene Evstafev ([LinkedIn](https://linkedin.com/in/chigwell))
📧 **Contact:** [hi@euegne.plus](mailto:hi@euegne.plus)

---

## **License**
[MIT](https://github.com/chigwell/ecodynalyze/blob/main/LICENSE)