ACE Roleplay

ACE Roleplay adapts the ACE method to deterministic, multi-turn roleplay conversations. It stores short "bullets" in SQLite with FTS5 for fast retrieval, runs a generator → reflector → curator loop, and exposes both CLI and API interfaces.

+---------+       +-------------+       +----------+
| User    |  -->  | ChatSession |  -->  | Generator|
+---------+       +------+------+       +----+-----+
                         |                  |
                         v                  v
                    +----+-----+       +----+-----+
                    | Retriever|       | Evaluators|
                    +----+-----+       +----+-----+
                         |                  |
                         v                  v
                    +----+-----+       +----+-----+
                    | Reflector|  -->  | Curator  |
                    +----------+       +----------+

Features

• SQLite playbook with deterministic migrations and FTS5 search.
• Retrieval combines persona canon, tactics, continuity, antipatterns, and user preferences.
• Generator produces roleplay responses and traces without requiring network access.
• Evaluators catch out-of-character slips, contradictions, repetition, and boundary risk.
• Reflector proposes small deltas, curator applies them deterministically.
• CLI (Typer) and FastAPI server for integration.
• Example persona seed for immediate use.

Installation

pip install -e .

Optional MinHash deduplication support:

pip install -e .[minhash]

Environment

Set the following environment variables or edit .env:

• ACE_OPENAI_API_KEY
• ACE_OPENAI_BASE_URL

Usage

Seed the database and start chatting:

ace-roleplay seed
ace-roleplay chat

Inspect or search bullets:

ace-roleplay search --text "hooks"
ace-roleplay stats

Run the FastAPI server:

uvicorn ace_roleplay.api:app --reload

Call the chat endpoint:

curl -X POST localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"user_message": "The guards are coming!"}'

Testing

pytest -q

Linting suggestions:

ruff check .
black --check .
mypy .

Contributing

1. Fork and create a topic branch.
2. Add tests for new behavior.
3. Ensure pytest -q and linters pass.
4. Submit a pull request describing the change and test coverage.

MIT License. See LICENSE for details.