# GEMINI.md - Project Context: Thon

## Project Overview
**Thon** is a Python library for converting and processing Telegram sessions. It is designed to be integrated into other projects as a dependency. It leverages `telethon` to handle `.session` files, converting them into a structured JSON format and providing an asynchronous framework for automated session management.

### Main Technologies
- **Python 3.10+**
- **Telethon**: Core library for Telegram interaction.
- **aiofiles**: Asynchronous file operations.
- **asyncio**: Powers the asynchronous iterator and processing logic.
- **Setuptools**: Build system for packaging.

---

## Architecture and Key Modules
- **`thon.Thon`**: The main class and asynchronous iterator. Orchestrates the flow from raw session files to an active, authorized client.
- **`thon.converter.Converter`**: Internal module that transforms raw `.session` files into JSON metadata files (containing `string_session` and proxy info).
- **`thon.process.ProcessThon`**: A context manager that wraps a `telethon.TelegramClient`. It handles connection, authorization checks, and provides high-level methods like `search_code`.
- **`thon.models`**: Organized data structures:
    - `ThonOptions`: Configuration for retries, timeouts, and checks.
    - `ThonSession`: The object yielded by the iterator, containing both metadata and the processing instance.
- **`thon.utils`**: Shared utilities for JSON I/O, regex extraction, and file system management.

---

## Usage and Integration
### Installation
Install as a library:
```bash
pip install git+https://github.com/your-username/thon.git
```

### Core Pattern
The library is designed around the `async for` pattern:
```python
from thon import Thon
from thon.models.options import ThonOptions

async def run():
    options = ThonOptions(retries=5)
    async for ts in Thon(options, sessions_folder=Path("path/to/sessions")):
        async with ts.thon as client:
            # client is an authorized Telethon instance
            pass
```

---

## Development Conventions
- **Asynchronous Flow**: All I/O and network calls must be `async`.
- **Session Management**: Automatically handles "banned" status by moving files if configured.
- **Proxy Support**: Integrated into the connection logic via `thon.proxy`.
- **Zero CLI**: The project does not provide a CLI entry point by design.

---

## Important Notes
- The library uses a hardcoded `api_id` and `api_hash` in `Converter` for internal session string generation, but allows external apps to use their own via session data.
- Banned sessions are moved to a `banned` subfolder relative to the sessions directory by default.