persona-chat 0.1.1
A sophisticated CLI application for generating authentic multi-turn conversations using 50+ distinct user personas
License: MIT
Requires Python: >=3.8
Keywords: conversation generation, personas, multi-language, CLI, AI, NLP

# Persona-Based Conversation Generator CLI

A sophisticated Python CLI application that generates authentic multi-turn conversations using 50+ distinct user personas across multiple languages.

## Installation

### Option 1: Install from PyPI (Recommended)

You can install the package directly from PyPI without cloning the repository:

```bash
pip install persona-chat
```

After installation, the `persona-chat` CLI command will be available globally:

```bash
persona-chat --help
```

You can now use all CLI features as described below, including batch and multi-persona generation.

### Option 2: Clone the Repository (Development/Latest)

```bash
git clone <repository-url>
cd persona-chat

# Install dependencies
pip install -r requirements.txt

# Install the package in editable mode
pip install -e .
```

## Usage

After installation (from PyPI or from source), you can use the CLI:

```bash
persona-chat generate --help
persona-chat batch --help
```

See below for example commands and advanced usage.

## Batch Generation Examples

### Multi-Persona Batch Generation (NEW)
Batch now supports all persona options, including multi-persona, matching the generate command.

```bash
persona-chat batch --conversations 3 --turns 3 --language ar --multi-persona --persona-names "Teacher,Student,Parent" --persona-roles "primary,participant,observer" --llm-backend openai --llm-model gemma2:2b --llm-api-url http://localhost:11434/v1 --output json --output-filename test_multi_persona_batch
```

### Arabic Batch with a Single Dynamic Technology Persona (All Conversations)
```bash
persona-chat batch --conversations 3 --turns 4 --language ar --create-persona --persona-name "مهندس برمجيات" --persona-role "مهندس برمجيات" --persona-domain technology --persona-expertise expert --persona-communication-style technical --llm-backend openai --llm-model gemma2:2b --llm-api-url http://localhost:11434/v1 --output json --output-filename test_arabic_batch_dynamic_it
```

### Multi-Persona Conversation (Single)
```bash
persona-chat generate --multi-persona --persona-names "Chef,Waiter,Customer" --persona-roles "primary,participant,observer" --language ar --turns 3 --llm-backend openai --llm-model gemma2:2b --llm-api-url http://localhost:11434/v1 --output markdown --output-filename test_multi_persona_restaurant
```

> **Note:** All persona options (including multi-persona, persona names, roles, and dynamic persona creation) are now supported in both batch and generate commands.

<!--
### Arabic Batch with Random Personas (NOT SUPPORTED)
```bash
persona-chat batch --conversations 3 --turns 4 --language ar --personas random --llm-backend openai --llm-model gemma2:2b --llm-api-url http://localhost:11434/v1 --output json --output-filename test_arabic_batch_random
```

### Arabic Batch with IT Personas (Random per Conversation, NOT SUPPORTED)
```bash
persona-chat batch --conversations 3 --turns 4 --language ar --personas technology --llm-backend openai --llm-model gemma2:2b --llm-api-url http://localhost:11434/v1 --output json --output-filename test_arabic_batch_it
```
-->

> **Troubleshooting:**
> - If you see `No valid persona available for conversation generation`, use the `--create-persona` and `--persona-name` options as shown above.
> - If you want random personas per conversation, you must restore the static persona files or update the code to support dynamic random persona generation.

## Export Formats
- `--output json` (default): Structured JSON
- `--output csv`: Tabular CSV
- `--output markdown`: Human-readable Markdown
- `--output text`: Plain text

## LLM Backend Support (OpenAI, Ollama, Transformers)

You can use OpenAI-compatible APIs (including local Ollama) or HuggingFace Transformers as the backend for all message generation.

### Configuration
- `--llm-backend`: Choose the backend (`openai`, `transformers`, or `none`)
- `--llm-model`: Model name (e.g., `gemma2:2b` for Ollama)
- `--llm-api-key`: (For OpenAI) Your OpenAI API key (use any dummy value for local Ollama)
- `--llm-api-url`: (For OpenAI) Custom API URL for self-hosted or alternative OpenAI-compatible APIs (e.g., `http://localhost:11434/v1` for Ollama)

### Example: Local Ollama API
```bash
persona-chat generate --llm-backend openai --llm-model gemma2:2b --llm-api-key dummy --llm-api-url http://localhost:11434/v1 --persona-name "Senior Software Engineer" --turns 5
```

### Notes
- All user and assistant messages are generated using the selected LLM backend if enabled.
- For local Ollama, use `--llm-backend openai` and provide a dummy API key.
- For Transformers, the model must be available locally or downloadable from HuggingFace.
- You can set defaults in a config file or via environment variables for convenience.

## Multi-Persona Conversations
- Use `--multi-persona` to enable multi-persona mode
- Specify persona names and roles with `--persona-names` and `--persona-roles`
- Example:
  ```bash
  persona-chat generate --multi-persona --persona-names "Artist,Designer,Client" --persona-roles "primary,participant,observer" --language ar --turns 3
  ```

## Documentation

- [Installation Guide](docs/installation.md)
- [Quick Start Guide](docs/quick_start.md)
- [User Guide](docs/user_guide/)
- [Developer Guide](docs/developer_guide/)
- [Examples](docs/examples/)

## Project Structure

```
persona-chat/
├── persona_chat/          # Main application package
├── config/               # Configuration files
├── output/               # Output files
├── tests/                # Test suite
├── docs/                 # Documentation
├── examples/             # Example files
└── tools/                # Development tools
```

## Contributing

Please read [CONTRIBUTING.md](docs/developer_guide/contributing.md) for details on our code of conduct and the process for submitting pull requests.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.