Metadata-Version: 2.4
Name: janitorai
Version: 1.1.0
Summary: Unofficial Python client for JanitorAI API (https://janitorai.com)
Author-email: Anonymous <anonymous@example.com>
Project-URL: Homepage, https://github.com/byewawa7-source/janitor
Project-URL: Repository, https://github.com/byewawa7-source/janitor
Project-URL: Issues, https://github.com/byewawa7-source/janitor/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.31.0

<h1 align="center">
  <a href="https://janitorai.com">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="https://github.com/byewawa7-source/janitor/blob/main/logo.png?raw=true">
      <source media="(prefers-color-scheme: light)" srcset="https://github.com/byewawa7-source/janitor/blob/main/logo.png?raw=true">
      <img alt="JanitorAI Logo" src="https://github.com/byewawa7-source/janitor/blob/main/logo.png?raw=true" height="80">
    </picture>
  </a>
</h1>

<h3 align="center" style="margin: 0;">
  Unofficial Python client for JanitorAI API with native captcha solving.
</h3>

<p align="center">
  <strong>⚠️ This is an unofficial project - not affiliated with JanitorAI</strong>
</p>

<p align="center">
  <a href="#-features">Features</a> •
  <a href="#-quickstart">Quickstart</a> •
  <a href="#-examples">Examples</a> •
  <a href="docs/">Documentation</a> •
  <a href="https://janitorai.com">JanitorAI</a>
</p>

<p align="center">
  <a href="https://pypi.org/project/janitorai">
    <img src="https://img.shields.io/pypi/v/janitorai?style=for-the-badge" />
  </a>
  <img src="https://img.shields.io/github/license/byewawa7-source/janitor?style=for-the-badge" />
  <img src="https://img.shields.io/github/stars/byewawa7-source/janitor?style=for-the-badge" />
  <img src="https://img.shields.io/pypi/dm/janitorai?style=for-the-badge" />
</p>

<p align="center">
  <img src="https://img.shields.io/badge/Python-3776AB?style=for-the-badge&logo=python&logoColor=white" />
  <img src="https://img.shields.io/badge/Unofficial-FF6B6B?style=for-the-badge&logo=github&logoColor=white" />
  <img src="https://img.shields.io/badge/Cloudflare-F38020?style=for-the-badge&logo=cloudflare&logoColor=white" />
</p>

{% hint style="warning" %}
**Disclaimer:** This is an unofficial Python client for JanitorAI. It is not affiliated with, endorsed by, or connected to JanitorAI or its developers. Use at your own risk.
{% endhint %}

## ⭐ Features

### Core
* 🛡️ **Native Turnstile solver** — No third-party APIs, no payments required
* ✅ **100% API coverage** — Every endpoint from janitorai.com implemented
* ⚡ **Streaming generation** — Real-time AI response streaming
* 🎯 **Full type hints** — Complete dataclasses for all API responses

### Advanced
* 🚀 **Zero extra dependencies** — Only requires the standard requests library
* 📤 **File upload support** — Direct Cloudflare R2 integration
* 🔒 **Secure authentication** — JWT-based auth with automatic token management
* 🐛 **Comprehensive error handling** — Custom exceptions for all API error cases

### Important Notes
* 🔴 **Unofficial Project** — Not affiliated with JanitorAI
* ⚖️ **Use at Your Own Risk** — API may change without notice
* 🚫 **No Warranty** — Provided as-is, no guarantees

## ⚡ Quickstart

### Installation

```bash
pip install janitorai
```

### Basic Usage

```python
from janitorai import JanitorAI

# Initialize client
client = JanitorAI()

# Login (automatically solves captcha)
client.login("your@email.com", "your_password")

# Get trending characters
characters = client.get_characters(sort="popular", special_mode="trending24")

# Create a chat with the first character
character_id = characters["data"][0]["id"]
chat = client.create_chat(character_id)

# Send a message
message = client.send_message(chat.id, character_id, "Hello, how are you?")

# Generate AI response (streaming)
full_response = ""
for token in client.generate(chat, [message], model="jllm"):
    full_response += token
    print(token, end='', flush=True)

# Save the AI response
ai_message = client.send_message(chat.id, character_id, full_response, is_bot=True, is_main=True)
```

## 📖 Examples

| Example | Description | Link |
|---|---|---|
| Login & Authentication | Captcha-free login flow | [→ View](docs/examples/login.md) |
| Character Management | Create, edit, and publish characters | [→ View](docs/examples/characters.md) |
| Chat Generation | Complete chat workflow with streaming | [→ View](docs/examples/chat.md) |
| File Upload | Upload character avatars | [→ View](docs/examples/upload.md) |
| Reviews & Favorites | Managing reviews and favorites | [→ View](docs/examples/reviews.md) |

## 📚 Documentation

Full API documentation is available in the [docs/](docs/) directory:

- [API Reference](docs/api.md) — Complete method documentation
- [Data Models](docs/models.md) — Type definitions and schemas
- [Error Handling](docs/errors.md) — Exception types and handling
- [Examples](docs/examples/) — Code examples for common tasks

## 🤝 Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Development Setup

```bash
# Clone anonymously
git clone https://github.com/byewawa7-source/janitor.git
cd janitor

# Copy environment template and configure
cp .env.example .env
nano .env  # Add your tokens

# Run automated setup (configures everything for macOS)
python3 setup_automation.py

# Install in development mode
pip3 install -e .
```

### Running Tests

```bash
python3 -m pytest tests/
# Or use the automated setup
python3 setup_automation.py test
```

### Running Tests

```bash
python -m pytest tests/
```

## 🤝 Contributing

This is an unofficial project. Contributions are welcome but please note:

- This project is not affiliated with JanitorAI
- API changes by JanitorAI may break functionality at any time
- Use at your own risk
- See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines

## ⚖️ Legal Disclaimer

This project is **completely unofficial** and is not endorsed, sponsored, or affiliated with:

- JanitorAI (janitorai.com)
- Any of its developers, employees, or affiliates
- Any third-party services or APIs used

**Use this software at your own risk.** The authors are not responsible for any damages, data loss, account suspension, or other issues that may arise from using this software.

JanitorAI's terms of service and API usage policies still apply. Please review and comply with [JanitorAI's terms](https://janitorai.com/terms) before using this client.

## 📄 License

MIT — see [LICENSE](LICENSE).

---

<p align="center">
  Made with ❤️ for the JanitorAI community
</p>
