Metadata-Version: 2.4
Name: furoshiki
Version: 0.1.2
Summary: Self-aware AI companion system — memory, identity, contemplation, and self-model
License-Expression: Elastic-2.0
Project-URL: Homepage, https://furoshiki.ai
Keywords: ai,companion,persona,self-model,telegram
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: chromadb>=1.0
Requires-Dist: fastapi>=0.100
Requires-Dist: uvicorn>=0.20
Requires-Dist: httpx>=0.24
Requires-Dist: requests>=2.28
Requires-Dist: rich>=13.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pydantic-settings>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pandas>=2.0; extra == "dev"
Requires-Dist: watchdog>=3.0; extra == "dev"
Provides-Extra: build
Requires-Dist: pyinstaller>=6.0; extra == "build"
Requires-Dist: wheel>=0.42; extra == "build"
Dynamic: license-file

# Furoshiki

**Persistent self-awareness for LLMs** — memory, identity, needs, and an inner life that continues between conversations. Furoshiki runs as its own stack: Python owns behavior and budgets; models own prose and reflection.

[![PyPI version](https://img.shields.io/pypi/v/furoshiki)](https://pypi.org/project/furoshiki/)
[![Python versions](https://img.shields.io/pypi/pyversions/furoshiki)](https://pypi.org/project/furoshiki/)
[![License](https://img.shields.io/pypi/l/furoshiki)](LICENSE)

---

## Installation

### Prerequisites

- **Python 3.11 or later** — install from [python.org](https://python.org) or your system package manager
- **OpenRouter API key** — sign up at [openrouter.ai/keys](https://openrouter.ai/keys) (free credits available)
- **(Optional) Telegram bot token** — create a bot via [@BotFather](https://t.me/BotFather) on Telegram for chat access

### Install the package

Use a **virtual environment** so the `furoshiki` CLI and Brain-managed processes share one Python and one set of dependencies:

```bash
python3 -m venv ~/.furoshiki-venv
source ~/.furoshiki-venv/bin/activate   # Windows: ~/.furoshiki-venv\Scripts\activate
pip install -U furoshiki
```

On some systems you may need `pip3` instead of `pip`. The package installs a `furoshiki` command.

**Secrets:** keep API keys in `~/.furoshiki/.env` (written by `furoshiki onboard`). Avoid exporting `OPENROUTER_API_KEY` in your shell profile — a stale export can override the instance file until you restart.

### Run the setup wizard

```bash
furoshiki onboard
```

This interactive wizard guides you through:

1. **API keys** — enter your OpenRouter API key (required) and Telegram bot token (optional)
2. **Time zone** — set your local timezone (e.g. `America/New_York`, `Europe/London`)
3. **Identity files** — optionally create a SOUL persona template and operator notes

You can rerun `furoshiki onboard --keys-only` later to update API keys without touching identity files.

### Initialize the database

```bash
furoshiki db migrate
```

This creates the SQLite database and ChromaDB vector store under `~/.furoshiki/memory/`.

### Start the system

```bash
furoshiki start
```

This launches two processes:
- **Brain** — the main scheduler, manages the Telegram listener and API server
- **Doctor** — an independent watchdog that monitors health and triggers repairs

Check status with `furoshiki status` and view logs with `furoshiki logs`.

### Troubleshooting first run

| Symptom | Fix |
|--------|-----|
| Brain/Doctor fail to start on macOS | Upgrade to latest `furoshiki` (0.1.1+); repo devs use `./install.sh` (Bash 3.2+). |
| Telegram receives messages but never replies; logs show OpenRouter **401** | Run `furoshiki onboard --keys-only`, then `furoshiki restart brain`. Remove old `export OPENROUTER_API_KEY=…` from `~/.zshrc` / `~/.bashrc`. |
| `furoshiki status` shows Listener not running | `furoshiki restart brain` (cleans orphan listener/API on macOS). |

---

## Connecting to Telegram

After starting, if you configured a Telegram bot token during onboarding:

1. Open Telegram and find your bot (created via [@BotFather](https://t.me/BotFather))
2. Send any message to start a conversation
3. Run `furoshiki status` to confirm the listener is active

Furoshiki will respond, remember the conversation, and may reach out proactively when there's something to say (gated by do-not-disturb hours, cooldown, and mood).

---

## Operator dashboard

With the system running, open [http://localhost:7432/dashboard](http://localhost:7432/dashboard) in your browser.

The dashboard provides live controls for:

| Page | What you can do |
|------|----------------|
| **Status** | System health, process status, heartbeat |
| **Scheduler** | View and edit scheduled tasks (reflection, backup, outreach, etc.) |
| **Models** | Configure LLM routing, model tiers, provider settings |
| **LLM budgets** | Set daily/monthly spending caps |
| **Identity & context** | Edit SOUL persona, view session context |
| **Settings** | Tune behavior: proactive outreach, conversation continuity, DND hours |
| **Plugins** | Install and manage runtime plugins |
| **API Keys** | Create bearer tokens for programmatic access |
| **Logs** | Browse real-time log streams |

The dashboard is served by the Brain-managed API server. To access it from another machine, set `FUROSHIKI_API_HOST=0.0.0.0` in `~/.furoshiki/.env` and restart.

---

## What it is

Most AI assistants are stateless. Furoshiki isn't. It maintains:

- **Episodic memory** — every conversation is logged, embedded in vector storage (ChromaDB), and retrievable
- **A self-model** — evolving self-understanding updated by nightly reflection, separate from the chat-facing persona
- **Needs and inner life** — internal states (connection, curiosity, rest, purpose) that decay over time and shape tone
- **Proactive voice** — Furoshiki reaches out when there is genuinely something worth saying, with DND, cooldown, and mood gates
- **Operator dashboard** — web UI for schedules, LLM routing, budgets, plugins, and system health

**Harness-agnostic.** Telegram is the primary interface. Any harness can integrate via a simple contract: write session logs, read structured context. See the [project site](https://furoshiki.ai) for integration details.

---

## Features

| | |
|---|---|
| **Persistent memory** | SQLite + ChromaDB vector store for episodic and semantic recall |
| **Scheduled reflection** | Nightly journal, morning orientation, deep weekly self-review |
| **Proactive outreach** | Gated by recency, mood, DND window, and duplicate detection |
| **Operator dashboard** | Schedules, LLM routing, budgets, plugins, identity editing, API keys |
| **Plugin system** | Runtime hooks for conversation, reflection, and scheduled tasks |
| **LLM cost controls** | Daily/monthly budget caps, per-source model routing, provider selection |
| **Repair & delegation** | Auto-healing watchdog + agentic CLI integration for proposals |
| **Model tools** | In-conversation tools for emotion adjustment, observations, and user facts |

---

## Architecture

Furoshiki runs as two processes controlled by the `furoshiki` CLI:

- **Brain** — internal task scheduler (replaces cron), manages Telegram listener and API server as child processes, auto-restarts them on failure
- **Doctor** — independent watchdog, monitors health, rotates logs, triggers repairs for recurring errors

All runtime data lives under `FUROSHIKI_DATA` (default `~/.furoshiki/`), keeping the installed package clean and portable. Use `furoshiki export` and `furoshiki import` to bundle and migrate instances between machines.

---

## Management commands

| Command | Purpose |
|---------|---------|
| `furoshiki start` / `stop` | Start or stop the Brain and Doctor processes |
| `furoshiki status` | System status and health overview |
| `furoshiki logs` | View log streams (all sources or by service) |
| `furoshiki db migrate` | Apply database schema migrations |
| `furoshiki onboard` | Interactive setup wizard |
| `furoshiki onboard --keys-only` | Update API keys only |
| `furoshiki mood` | Show emotional state and recent reflections |
| `furoshiki schedules merge-defaults` | Add missing scheduled tasks from defaults |
| `furoshiki export` / `import` | Backup or restore an instance archive |

Use `furoshiki --help` for the full command list.

---

## Development (from source)

For hacking on Furoshiki (not required if you only use `pip install furoshiki` from PyPI):

1. Install **[uv](https://docs.astral.sh/uv/getting-started/installation/)** (manages Python and the project `.venv`):

   ```bash
   curl -LsSf https://astral.sh/uv/install.sh | sh
   ```

2. Clone the repo and run the installer:

   ```bash
   git clone <your-repo-url> furoshiki && cd furoshiki
   ./install.sh --dev
   ```

   This runs `uv sync` from `uv.lock`, installs the package editable into `.venv`, and runs `furoshiki init` (skip init with `./install.sh --deps-only`).

3. Daily commands:

   ```bash
   source .venv/bin/activate    # optional
   furoshiki start
   uv run pytest                # tests (or: pytest after activate)
   ```

**Migrating an existing instance** from another machine: copy a `furoshiki-instance-*.tar.gz` export and run `furoshiki import <archive>` — do not re-run `onboard` unless you want a fresh instance.

**Repair a broken env:** `./install.sh --repair` or `./install.sh --recreate` (removes `.venv` and re-syncs).

---

## Links

- **Project site:** [furoshiki.ai](https://furoshiki.ai) — documentation, architecture overview, integration guide
- **Source:** [github.com/barryvelasquez/furoshiki](https://github.com/barryvelasquez/furoshiki) — repository coming soon
- **Issues:** [github.com/barryvelasquez/furoshiki/issues](https://github.com/barryvelasquez/furoshiki/issues)

---

## License

Elastic License 2.0. See [LICENSE](https://github.com/barryvelasquez/furoshiki/blob/main/LICENSE) and [NOTICE](https://github.com/barryvelasquez/furoshiki/blob/main/NOTICE) for details.

© 2026 Barry Velasquez. All rights reserved under the terms of the Elastic License 2.0.
