Metadata-Version: 2.3
Name: hyprchan
Version: 0.1.1
Summary: An anime girl that lives in your Hyprland and chills.
Author: Zahcoder34
Author-email: Zakhriw@gmail.com
Requires-Python: >=3.11,<3.14
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: aiogram (>=3.26.0,<4.0.0)
Requires-Dist: aiosqlite (>=0.20.0,<0.21.0)
Requires-Dist: ascender-alp (>=0.0.2,<0.0.3)
Requires-Dist: ascender-framework (>=2.1.0,<3.0.0)
Requires-Dist: asyncpg (>=0.31.0,<0.32.0)
Requires-Dist: faster-whisper (>=1.1.1,<2.0.0)
Requires-Dist: httpx (>=0.27.0,<0.29.0)
Requires-Dist: hyprland (>=0.2.54,<0.3.0)
Requires-Dist: langchain (>=0.3.0,<0.4.0)
Requires-Dist: langchain-core (>=0.3.78,<0.4.0)
Requires-Dist: langchain-openai (>=0.3.0,<0.4.0)
Requires-Dist: opencv-python-headless (>=4.10.0.84,<5.0.0.0)
Requires-Dist: pgvector (>=0.3.6,<0.4.0)
Requires-Dist: pygobject (>=3.56.0,<4.0.0)
Requires-Dist: pygobject-stubs (>=2.16.0,<3.0.0)
Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
Requires-Dist: questionary (>=2.1.1,<3.0.0)
Requires-Dist: redis (>=7.2.1,<8.0.0)
Requires-Dist: sounddevice (>=0.5.1,<0.6.0)
Requires-Dist: textual (>=0.70.0,<1.0.0)
Requires-Dist: tiktoken (>=0.8.0,<0.9.0)
Requires-Dist: tweepy (>=4.16.0,<5.0.0)
Project-URL: Repository, https://github.com/AscenderTeam/Hyprchan
Description-Content-Type: text/markdown

<div align="center">

<img src="https://github.com/AscenderTeam/Hyprchan/raw/feature/memory-update/public/assets/readme/hyprchan_pixel.png" width="250" alt="Hyprchan Pixel Art">

# 🌌 HyprAI OS: Hyprchan

**The homeostatic system companion that lives in your Hyprland workspace.**

[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue.svg?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/)
[![FastAPI](https://img.shields.io/badge/FastAPI-005571?style=for-the-badge&logo=fastapi)](https://fastapi.tiangolo.com/)
[![Hyprland](https://img.shields.io/badge/Hyprland-CC1111?style=for-the-badge&logo=linux&logoColor=white)](https://hyprland.org/)
[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-336791?style=for-the-badge&logo=postgresql&logoColor=white)](https://www.postgresql.org/)
[![License](https://img.shields.io/badge/license-MIT-green.svg?style=for-the-badge)](LICENSE)

---

**Hyprchan** is a homeostatic system entity driven by a continuous kernel loop, multimodal perception, and a layered memory stack. She observes your workspaces, listens to your voice, and reacts to your presence with dynamic mood shifts and pixel-art animations.

[**Quick Start**](#-quick-start) • [**Features**](#-features) • [**Architecture**](#-architecture) • [**Commands**](#-cli-commands)

</div>

---

## 📸 Visuals

<div align="center">
  <table border="0">
    <tr>
      <td width="50%">
        <img src="https://github.com/AscenderTeam/Hyprchan/raw/feature/memory-update/public/assets/readme/tui_screenshot.png" width="100%" alt="Rich TUI Interface">
        <p align="center"><i>Live Rich TUI with telemetry and memory snapshots.</i></p>
      </td>
      <td width="50%">
        <img src="https://github.com/AscenderTeam/Hyprchan/raw/feature/memory-update/public/assets/readme/overlay_example.png" width="100%" alt="Hyprland Overlay">
        <p align="center"><i>Animated Hyprland overlay with tool-calling capabilities.</i></p>
      </td>
    </tr>
  </table>
</div>

---

## 🚀 Quick Start

Getting Hyprchan running is simple. Just install and run the setup wizard.

### 1. Installation
```bash
pip install hyprchan
```

### 2. Setup Wizard
Run the interactive setup to configure your LLM provider, memory (Postgres/Redis), and system services.
```bash
hyprchan wizard setup
```

### 3. Launch the TUI
Once setup is complete, wake her up and start chatting:
```bash
hyprchan tui
```

---

## ✨ Features

*   **🧠 Layered Memory Stack:** Brain-inspired architecture with **Short-Term (Redis)**, **Long-Term (Postgres + pgvector)**, and **Working Memory**.
*   **🌙 Sleep & Dreaming:** Automatically distills events into semantic facts during consolidation cycles. She literally *dreams* about your interactions.
*   **🎭 Dynamic Mood Dynamics:** Internal scalars (`valence`, `energy`, `fatigue`) drive her personality. Sustained interaction or rudeness shifts her stance in real-time.
*   **👁️ Multimodal Perception:**
    *   **Vision:** Webcam face/motion detection and periodic desktop snapshots.
    *   **Audio:** Continuous speech-to-text via **Faster-Whisper** with auto-language detection.
    *   **OS:** Monitors Hyprland workspace switches and window focus events.
*   **🎨 LLM-Driven Animations:** The assistant can trigger poses (`idle`, `depressed`, `sleeping`) and move herself across your screen using custom tools.

---

## 🏗️ Architecture

Hyprchan operates on a **Continuous Kernel Loop** where perception preempts cognition.

### The Perception-to-Mood Pipeline
1.  **Controllers:** Emit raw OS/Voice/Vision events.
2.  **Toggle Detector:** Filters high-frequency "noise" from actual activity.
3.  **Activity Detector:** Calculates macro-pressure on her attention.
4.  **Mood Engine:** Updates internal scalars based on interaction quality ($d$ delta) and phase fatigue.
5.  **Logit Bias:** Mood scalars are projected into token-level biases, subtly altering her speech patterns.

---

## 💻 CLI Commands

Hyprchan comes with a powerful CLI for management and interaction.

| Command | Description |
| :--- | :--- |
| `hyprchan wizard setup` | Launches the interactive configuration master. |
| `hyprchan tui` | Opens the live Rich terminal interface. |
| `hyprchan serve` | Starts the FastAPI backend daemon. |
| `hyprchan extensions` | Manage built-in extensions (Hyprgram, HyprX). |
| `hyprchan status` | Check the health of the kernel and perception services. |

---

<div align="center">
  <sub>Built with the <b>Ascender Framework</b>. Maintained by <b>Ascender Team</b> and <b>Hyprland Community Enthusiasts</b>.</sub>
</div>

