Metadata-Version: 2.4
Name: fiction-vs-fact
Version: 2025.12.21083650
Summary: The package aims to help users analyze and understand nuanced narratives or statements by distinguishing between factual accounts and imaginative interpretations. Given a text input, it will process t
Author-email: fiction-vs-fact <hi@eugene.plus>
License: MIT
Project-URL: Homepage, https://github.com/chigwell/fiction-vs-fact
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

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


A Python package to help analyze and differentiate nuanced narratives or statements by identifying which parts are factual and which are imaginative or speculative. Ideal for literary analysis, scriptwriting, or clarifying misleading information by clearly distinguishing between objective reality and creative interpretation.

## Installation

Install the package via pip:

```bash
pip install fiction_vs_fact
```

## Usage

Here's an example of how to use the package in your Python code:

```python
from fiction_vs_fact import fiction_vs_fact

# Example user input
text_input = "In the story, John claims he saw a dragon flying over the city, but eyewitnesses report no such event."

# Process the input to separate facts from fictional elements
results = fiction_vs_fact(user_input=text_input)

print(results)
```

## Function Parameters

- `user_input` (str): The text containing statements or narratives to analyze.
- `llm` (Optional[BaseChatModel]): Optional. A custom language model instance to use. Defaults to using `ChatLLM7` if not provided.
- `api_key` (Optional[str]): Optional. API key for the LLM service. If not provided, it will attempt to read the `LLM7_API_KEY` environment variable.

## Underlying LLM

The package utilizes `ChatLLM7` from [langchain_llm7](https://pypi.org/project/langchain-llm7/) by default.

## Custom LLM Usage

You can pass your own language model instance to the function. For example:

```python
from langchain_openai import ChatOpenAI
from fiction_vs_fact import fiction_vs_fact

llm = ChatOpenAI()

response = fiction_vs_fact(
    user_input="Some intriguing story...",
    llm=llm
)
```

Similarly, for other providers:

```python
from langchain_anthropic import ChatAnthropic
from fiction_vs_fact import fiction_vs_fact

llm = ChatAnthropic()

response = fiction_vs_fact(
    user_input="Some intriguing story...",
    llm=llm
)
```

## Rate Limits and API Keys

The package defaults to the free tier limits of LLM7. For higher limits, obtain an API key at [LLM7 Token Service](https://token.llm7.io/) and set it via environment variable `LLM7_API_KEY` or pass it directly:

```python
response = fiction_vs_fact(
    user_input="Some input...",
    api_key="your_api_key"
)
```

## Resources

- [GitHub issues](https://github.com/your-repo/fiction-vs-fact/issues)
- Author: Eugene Evstafev
- Email: hi@evstafev.plus
- GitHub: [chigwell](https://github.com/chigwell)
