ai-character-engine 1.0.0__tar.gz

ai_character_engine-1.0.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

ai_character_engine-1.0.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md README.*.md LICENSE
+prune tests
+prune examples
+global-exclude *.pyc *.pyo .DS_Store
+recursive-include docs/assets *.svg
+recursive-include skills/ai-character-engine *.md *.yaml

ai_character_engine-1.0.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: ai-character-engine
+Version: 1.0.0
+Summary: A modular open-source engine for building stateful LLM-powered characters.
+License-Expression: Apache-2.0
+Project-URL: Repository, https://github.com/weryk153/ai-character-engine
+Project-URL: Documentation, https://github.com/weryk153/ai-character-engine/blob/main/docs/README.md
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai>=1.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: httpx<1,>=0.27; extra == "dev"
+Requires-Dist: tzdata>=2024.1; sys_platform == "win32" and extra == "dev"
+Provides-Extra: service
+Requires-Dist: fastapi<1,>=0.115; extra == "service"
+Requires-Dist: uvicorn<1,>=0.30; extra == "service"
+Requires-Dist: pydantic<3,>=2.7; extra == "service"
+Provides-Extra: qdrant
+Requires-Dist: qdrant-client<2,>=1.10; extra == "qdrant"
+Provides-Extra: local
+Requires-Dist: httpx<1,>=0.27; extra == "local"
+Provides-Extra: voice-audio
+Requires-Dist: sounddevice<0.6,>=0.5; extra == "voice-audio"
+Requires-Dist: httpx<1,>=0.27; extra == "voice-audio"
+Provides-Extra: voice-sherpa
+Requires-Dist: httpx<1,>=0.27; extra == "voice-sherpa"
+Requires-Dist: sounddevice<0.6,>=0.5; extra == "voice-sherpa"
+Requires-Dist: sherpa-onnx==1.13.8; extra == "voice-sherpa"
+Requires-Dist: sherpa-onnx-core==1.13.8; sys_platform == "darwin" and extra == "voice-sherpa"
+Requires-Dist: numpy<3,>=1.26; extra == "voice-sherpa"
+Provides-Extra: voice-mac
+Requires-Dist: httpx<1,>=0.27; extra == "voice-mac"
+Requires-Dist: sounddevice<0.6,>=0.5; extra == "voice-mac"
+Requires-Dist: faster-whisper<2,>=1.1; extra == "voice-mac"
+Requires-Dist: numpy<3,>=1.26; extra == "voice-mac"
+Provides-Extra: training
+Requires-Dist: datasets<5,>=3; extra == "training"
+Requires-Dist: transformers<6,>=4.48; extra == "training"
+Requires-Dist: peft<1,>=0.14; extra == "training"
+Requires-Dist: trl<2,>=0.15; extra == "training"
+Requires-Dist: accelerate<2,>=1; extra == "training"
+Provides-Extra: training-qlora
+Requires-Dist: datasets<5,>=3; extra == "training-qlora"
+Requires-Dist: transformers<6,>=4.48; extra == "training-qlora"
+Requires-Dist: peft<1,>=0.14; extra == "training-qlora"
+Requires-Dist: trl<2,>=0.15; extra == "training-qlora"
+Requires-Dist: accelerate<2,>=1; extra == "training-qlora"
+Requires-Dist: bitsandbytes<1,>=0.45; extra == "training-qlora"
+Dynamic: license-file
+
+<p align="center">
+  <img src="docs/assets/readme-banner.svg" alt="AI Character Engine — A Python SDK for characters with memory, goals and tools" width="100%" />
+</p>
+
+<h1 align="center">AI Character Engine</h1>
+
+<p align="center"><strong>A Python SDK for AI characters with memory, tools and ongoing conversations.</strong></p>
+
+<p align="center">
+  <a href="pyproject.toml"><img src="docs/assets/badge-version.svg" alt="Version 1.0.0" /></a>
+  <a href="LICENSE"><img src="docs/assets/badge-license.svg" alt="License: Apache-2.0" /></a>
+  <a href="docs/getting-started.md"><img src="docs/assets/badge-python.svg" alt="Python 3.11–3.13" /></a>
+  <a href="https://github.com/weryk153/ai-character-engine/actions/workflows/ci.yml"><img src="docs/assets/badge-platforms.svg" alt="Linux, macOS, Windows" /></a>
+</p>
+
+<blockquote>
+  <p align="center"><strong>Build companions, game NPCs and virtual assistants with a shared character runtime.</strong></p>
+</blockquote>
+
+<p align="center">
+  <strong><a href="README.md">English</a> &nbsp;|&nbsp; <a href="README.zh-TW.md">繁體中文</a> &nbsp;|&nbsp; <a href="README.zh-CN.md">简体中文</a> &nbsp;|&nbsp; <a href="README.ja.md">日本語</a> &nbsp;|&nbsp; <a href="README.ko.md">한국어</a><br />
+  <a href="README.es.md">Español</a> &nbsp;|&nbsp; <a href="README.fr.md">Français</a> &nbsp;|&nbsp; <a href="README.de.md">Deutsch</a> &nbsp;|&nbsp; <a href="README.pt-BR.md">Português (Brasil)</a></strong>
+</p>
+
+<p align="center">
+  <strong><a href="docs/README.md">Documentation</a> &nbsp;|&nbsp; <a href="docs/getting-started.md">Installation</a> &nbsp;|&nbsp; <a href="examples/README.md">Examples</a> &nbsp;|&nbsp; <a href="docs/architecture.md">Architecture</a> &nbsp;|&nbsp; <a href="skills/ai-character-engine/SKILL.md">Agent Skill</a></strong>
+</p>
+
+---
+
+## About
+
+AI Character Engine helps you build AI companions, game NPCs and virtual assistants. Give a character a personality, let it remember interactions and keep track of unfinished work, then connect tools so it can act inside your application.
+
+The engine manages the character’s data: conversations and long-term memories, emotion and relationship state, reflections, beliefs and ongoing goals. The model generates responses. Character records live outside the model, where you can inspect, revise and persist them, and keep using them when you change models.
+
+Start with text chat or connect the engine to an existing desktop character, voice interface or game. The core works independently of any particular model or renderer; the VRM adapter is an optional package. Supports Linux, macOS and Windows with Python 3.11–3.13.
+
+## ✨ Features
+
+### 🧠 Memory and character state
+
+- **Long-term memory:** Store useful moments from interactions and retrieve memories relevant to the current conversation. Includes correction, consolidation and forgetting.
+- **Reflection and beliefs:** Build interpretations from past events and keep their supporting evidence. Insufficient or conflicting evidence has its own handling; repeating a model output does not turn it into a fact.
+- **Emotion and relationships:** Track emotion, energy, trust, favorability and relationship stage. Your policies decide how interactions update them.
+- **Saved sessions:** Save and restore conversation and relationship data so users can pick up where they left off.
+
+### 🎯 Goals and actions
+
+- **Ongoing goals:** Track what the character is working on, its motivation, and active, blocked, paused or completed status. Goals can remain after the topic changes.
+- **Tool calls:** Register data lookups, game-state queries or application actions as tools the model can use during a turn. Your app owns the handlers and permissions.
+- **Proactive interaction:** The autonomy host provides triggers and scheduling for interactions under your configured conditions. You supply the allowed actions and timing policies.
+
+### ⚡ Background cognition and multiple models
+
+- **Chat while processing experience:** Foreground turns handle conversation while background tasks summarize, reflect or perform other work, with concurrency limits, timeouts and cancellation.
+- **Models by role:** Dialogue, summary, reflection and vision can share one model or use different endpoints with configured fallback.
+- **Specialist collaboration:** An optional planner, specialists and verifier flow delegates a bounded task to different roles and collects their results.
+
+### 🌍 Multiple characters and world interaction
+
+- **Individual memories and perspectives:** Characters keep separate state and cognitive records, communicating through explicit messages.
+- **Observations by character:** Perception rules determine who receives a world event. An NPC that sees a door open can receive that observation without making every other NPC aware of it.
+- **Connect your world:** Interfaces cover world state, events and observations. Movement, physics and rendering stay in your application.
+
+### 🎙️ Voice, vision and avatars
+
+- **Live input:** Feed text and normalized visual or audio observations into the live runtime.
+- **Voice conversations:** Interfaces and integration flows cover recognition, streaming synthesis, playback and interruption. Configure providers and devices before use.
+- **Expression and lip-sync:** Produce expression, behavior and lip-sync cues for your host to map to its character model. The VRM adapter provides an optional connection.
+
+Also included: event traces, persistence replay, cognitive evaluation, HTTP/SSE/WebSocket service interfaces and offline SFT/LoRA training tools. These modules are optional. Start with a text character and add the pieces you need.
+
+## 🏗️ Architecture
+
+`CharacterRuntime` is the entry point for one character. It assembles context, calls models and tools, and records the turn’s result. Profile, current state, memory, beliefs and goals are stored separately and included within their context budgets.
+
+```mermaid
+flowchart TD
+    App["Your app, game or character interface"] <--> Runtime["CharacterRuntime"]
+    Context["Profile · State · Memory · Beliefs · Goals"] --> Runtime
+    Runtime <--> Models["Models and cognitive-role routing"]
+    Runtime <--> Tools["Application tools"]
+    Runtime --> Record["Turn recording and state updates"]
+    Record --> Context
+    Runtime --> Snapshot["Read-only snapshot"]
+    Snapshot --> Workers["Background summaries, reflection and cognition"]
+    Workers --> Commit["Proposal validation and commit"]
+    Commit --> Context
+```
+
+Background workers operate on snapshots. Their proposals are checked for provenance and revision before being committed, so an old task cannot simply overwrite newer character state. Models, speech services and renderers connect through interfaces; the runtime and commit flow coordinate writes to character data.
+
+The [architecture guide](docs/architecture.md) covers foreground/background flows, character isolation, world perception and extension interfaces.
+
+## 🚀 Quick start
+
+You need **Python 3.11–3.13**.
+
+```sh
+git clone https://github.com/weryk153/ai-character-engine.git
+cd ai-character-engine
+python -m venv .venv
+```
+
+Activate the environment with `source .venv/bin/activate` on macOS/Linux or `.venv\Scripts\Activate.ps1` in Windows PowerShell, then install:
+
+```sh
+python -m pip install .
+```
+
+Start a local OpenAI-compatible model server, such as LM Studio. Replace `your-loaded-model` below with the loaded model’s identifier and adjust the URL to your server. Both calls use the same character, so the second receives the earlier exchange.
+
+```python
+import asyncio
+from ai_character_engine import CharacterProfile, CharacterRuntime
+from ai_character_engine.llm.local import OpenAICompatibleChatClient
+
+async def main():
+    llm = OpenAICompatibleChatClient(
+        base_url="http://127.0.0.1:1234/v1",
+        model="your-loaded-model",
+    )
+    character = CharacterRuntime(
+        character=CharacterProfile(
+            id="mei", name="Mei",
+            description="A friendly companion who gives concise answers.",
+        ),
+        llm=llm,
+    )
+    try:
+        print((await character.run_turn("Call me Alex.")).text)
+        print((await character.run_turn("What name did I ask you to use?")).text)
+    finally:
+        await llm.client.close()
+
+asyncio.run(main())
+```
+
+This example uses conversation history. For continuity across restarts, add [session save/restore](examples/session_runtime.py). Long-term memory, reflection and goals require their own configuration. See the [installation guide](docs/getting-started.md) for the full setup.
+
+A host that talks to one character — a chat window, a voice application, a desktop avatar — can skip that configuration: [`CharacterCompanion`](docs/companion.md) is the engine assembled with memory, mood, goals, reflection and interruption already wired, behind a single `reply()`. Its context is written into the conversation as it grows, so a local model’s prompt cache stays usable from turn to turn. See [`examples/companion_chat.py`](examples/companion_chat.py).
+
+## 🔌 Models and integrations
+
+- **LLMs:** OpenAI Responses and OpenAI-compatible Chat Completions, including compatible LM Studio, Ollama and vLLM endpoints. You can also implement your own client. See [provider examples](examples/README.md).
+- **Voice and avatars:** Install audio extras or the [VRM adapter](packages/renderer-vrm/README.md) as needed. Installing a package does not download models or start services.
+- **Local or remote:** The core does not require a cloud service or API key. Local models can use local endpoints; your chosen providers and tools determine network use.
+
+## 📂 Examples and docs
+
+- [Character companion](examples/companion_chat.py): a terminal chat with one character that remembers what you tell it and changes over time, on a local OpenAI-compatible endpoint.
+- [Interactive chat](examples/basic_chat.py) / [tool calls](examples/tool_chat.py): configure the model and credentials in `.env` before running.
+- [Sessions](examples/session_runtime.py): save and restore using temporary storage and an offline client.
+- [HTTP/SSE/WebSocket](examples/character_service.py): a service example for web or mobile clients. Uses an offline client by default; configure inference and authentication for deployment.
+- [Autonomy](examples/autonomy_host.py): integrate character triggers and lifecycle.
+- [Memory revision](tests/scenarios/memory_revision.py), [reflection and beliefs](tests/scenarios/reflection_long_term_cognition.py), [goals](tests/scenarios/goal_motivation_runtime.py), [world perception](tests/scenarios/world_environment.py): executable regression scenarios showing cognitive configuration and expected results.
+
+[API reference](docs/api-reference.md) · [Configuration](docs/configuration.md) · [Deployment and operations](docs/operations.md) · [Extensions](docs/extensions.md)
+
+## Development and license
+
+Current version: **1.0.0**. CI covers Linux/macOS/Windows × Python 3.11/3.12/3.13, plus API compatibility, persistence replay, failure injection, same-environment performance and package installation. See [CI](https://github.com/weryk153/ai-character-engine/actions/workflows/ci.yml), [validation](VALIDATION.md) and [compatibility](docs/compatibility.md).
+
+Issues and fixes are welcome; see [CONTRIBUTING](CONTRIBUTING.md). Licensed under [Apache-2.0](LICENSE). Third-party models, voices and assets retain their own licenses.

ai_character_engine-1.0.0/README.de.md

@@ -0,0 +1,165 @@
+<p align="center">
+  <img src="docs/assets/readme-banner.svg" alt="AI Character Engine — A Python SDK for characters with memory, goals and tools" width="100%" />
+</p>
+
+<h1 align="center">AI Character Engine</h1>
+
+<p align="center"><strong>Ein Python-SDK für KI-Charaktere mit Gedächtnis, Werkzeugen und fortlaufenden Gesprächen.</strong></p>
+
+<p align="center">
+  <a href="pyproject.toml"><img src="docs/assets/badge-version.svg" alt="Version 1.0.0" /></a>
+  <a href="LICENSE"><img src="docs/assets/badge-license.svg" alt="License: Apache-2.0" /></a>
+  <a href="docs/getting-started.md"><img src="docs/assets/badge-python.svg" alt="Python 3.11–3.13" /></a>
+  <a href="https://github.com/weryk153/ai-character-engine/actions/workflows/ci.yml"><img src="docs/assets/badge-platforms.svg" alt="Linux, macOS, Windows" /></a>
+</p>
+
+<blockquote>
+  <p align="center"><strong>Entwickle KI-Begleiter, NPCs und virtuelle Assistenten mit einer gemeinsamen Charakter-Runtime.</strong></p>
+</blockquote>
+
+<p align="center">
+  <strong><a href="README.md">English</a> &nbsp;|&nbsp; <a href="README.zh-TW.md">繁體中文</a> &nbsp;|&nbsp; <a href="README.zh-CN.md">简体中文</a> &nbsp;|&nbsp; <a href="README.ja.md">日本語</a> &nbsp;|&nbsp; <a href="README.ko.md">한국어</a><br />
+  <a href="README.es.md">Español</a> &nbsp;|&nbsp; <a href="README.fr.md">Français</a> &nbsp;|&nbsp; <a href="README.de.md">Deutsch</a> &nbsp;|&nbsp; <a href="README.pt-BR.md">Português (Brasil)</a></strong>
+</p>
+
+<p align="center">
+  <strong><a href="docs/README.md">Dokumentation</a> &nbsp;|&nbsp; <a href="docs/getting-started.md">Installation</a> &nbsp;|&nbsp; <a href="examples/README.md">Beispiele</a> &nbsp;|&nbsp; <a href="docs/architecture.md">Architektur</a> &nbsp;|&nbsp; <a href="skills/ai-character-engine/SKILL.md">Agent Skill</a></strong>
+</p>
+
+---
+
+## Über das Projekt
+
+Mit AI Character Engine entwickelst du KI-Begleiter, NPCs und virtuelle Assistenten. Gib ihnen eine Persönlichkeit, lass sie sich an Interaktionen erinnern und offene Aufgaben verfolgen. Über Werkzeuge können sie in deiner Anwendung handeln.
+
+Die Engine verwaltet Gespräche, Langzeitgedächtnis, Emotionen, Beziehungen, Reflexionen, Überzeugungen und Ziele. Das Modell erzeugt Antworten. Charakterdaten liegen außerhalb des Modells: Du kannst sie prüfen, korrigieren, speichern und nach einem Modellwechsel weiterverwenden.
+
+Beginne mit Textchat oder integriere die Engine in einen Desktop-Charakter, eine Sprachoberfläche oder ein Spiel. Der Kern ist unabhängig von einem bestimmten Modell oder Renderer. Der VRM-Adapter ist optional. Unterstützt Linux, macOS und Windows mit Python 3.11–3.13.
+
+## ✨ Funktionen
+
+### 🧠 Gedächtnis und Charakterzustand
+
+- **Langzeitgedächtnis:** Speichert relevante Erlebnisse und ruft zum aktuellen Thema passende Erinnerungen ab. Mit Korrektur, Konsolidierung und Vergessen.
+- **Reflexion und Überzeugungen:** Ordnet Deutungen vergangener Ereignisse und behält ihre Belege. Unzureichende und widersprüchliche Belege werden gesondert behandelt; Modellwiederholungen erzeugen keine Tatsachen.
+- **Emotionen und Beziehungen:** Verwaltet Emotion, Energie, Vertrauen, Zuneigung und Beziehungsphase. Deine Regeln bestimmen, wie sie sich ändern.
+- **Gespeicherte Sitzungen:** Speichert Gespräche und Beziehungsdaten und stellt sie wieder her, für den nächsten Besuch.
+
+### 🎯 Ziele und Handlungen
+
+- **Fortbestehende Ziele:** Hält Aufgaben, Motivation sowie aktiven, blockierten, pausierten oder abgeschlossenen Status fest, auch nach einem Themenwechsel.
+- **Werkzeugaufrufe:** Registriere Datenabfragen, Spielzustandsabfragen oder Anwendungsaktionen. Implementierung und Berechtigungen liegen bei deiner App.
+- **Proaktive Interaktion:** Der Autonomie-Host bietet Auslöser und Zeitplanung. Erlaubte Aktionen und Ausführungszeitpunkte konfigurierst du.
+
+### ⚡ Hintergrundkognition und mehrere Modelle
+
+- **Sprechen und Erfahrungen verarbeiten:** Gesprächsrunden im Vordergrund, Zusammenfassungen und Reflexionen im Hintergrund, mit Parallelitätsgrenzen, Zeitlimits und Abbruch.
+- **Modelle nach Rolle:** Dialog, Zusammenfassung, Reflexion und Bildverarbeitung können ein Modell teilen oder verschiedene Endpunkte mit konfiguriertem Fallback nutzen.
+- **Spezialisten:** Ein optionaler Ablauf aus Planer, Spezialisten und Prüfer verteilt eine begrenzte Aufgabe und sammelt Ergebnisse.
+
+### 🌍 Mehrere Charaktere und Weltinteraktion
+
+- **Eigene Erinnerungen und Sichtweisen:** Jeder Charakter behält seinen Zustand und seine Kognitionsdaten. Die Kommunikation erfolgt durch ausdrückliche Nachrichten.
+- **Beobachtungen nach Charakter:** Wahrnehmungsregeln bestimmen die Empfänger von Weltereignissen. Ein NPC kann beobachten, wie sich eine Tür öffnet, ohne dass alle anderen davon wissen.
+- **Deine Welt anbinden:** Schnittstellen für Weltzustand, Ereignisse und Beobachtungen. Bewegung, Physik und Darstellung bleiben beim Host.
+
+### 🎙️ Sprache, Bild und Avatare
+
+- **Live-Eingabe:** Text und normalisierte Bild- oder Audiobeobachtungen an die Live-Runtime übergeben.
+- **Sprachgespräche:** Schnittstellen und Abläufe für Erkennung, Streaming-Synthese, Wiedergabe und Unterbrechung. Anbieter und Geräte müssen eingerichtet sein.
+- **Mimik und Lippensynchronisation:** Erzeugt Ausdrucks-, Verhaltens- und Mundbewegungssignale für das Charaktermodell des Hosts. Der VRM-Adapter ist optional.
+
+Außerdem enthalten: Ereignis-Traces, Persistenz-Replay, Kognitionsevaluation, HTTP/SSE/WebSocket-Services sowie SFT/LoRA-Werkzeuge für Offline-Training. Die Module sind optional. Starte mit Text und ergänze die benötigten Teile.
+
+## 🏗️ Architektur
+
+`CharacterRuntime` ist der Einstiegspunkt für einen Charakter. Die Runtime baut Kontext auf, ruft Modelle und Werkzeuge auf und zeichnet das Ergebnis auf. Profil, Zustand, Gedächtnis, Überzeugungen und Ziele werden getrennt gespeichert und innerhalb ihrer Kontextbudgets eingebunden.
+
+```mermaid
+flowchart TD
+    App["Anwendung, Spiel oder Charakteroberfläche"] <--> Runtime["CharacterRuntime"]
+    Context["Profil · Zustand · Gedächtnis · Überzeugungen · Ziele"] --> Runtime
+    Runtime <--> Models["Modelle und Routing kognitiver Rollen"]
+    Runtime <--> Tools["Anwendungswerkzeuge"]
+    Runtime --> Record["Rundenaufzeichnung und Zustandsänderung"]
+    Record --> Context
+    Runtime --> Snapshot["Schreibgeschützte Momentaufnahme"]
+    Snapshot --> Workers["Zusammenfassung, Reflexion und Hintergrundkognition"]
+    Workers --> Commit["Vorschlagsprüfung und Commit"]
+    Commit --> Context
+```
+
+Hintergrund-Worker arbeiten mit Momentaufnahmen. Herkunft und Revision werden vor dem Commit geprüft, damit eine alte Aufgabe keinen neueren Zustand einfach überschreibt. Modelle, Sprachdienste und Renderer werden über Schnittstellen angebunden; Runtime und Commit-Ablauf koordinieren Schreibzugriffe.
+
+Der [Architekturleitfaden](docs/architecture.md) beschreibt Datenflüsse, Charaktertrennung, Weltwahrnehmung und Erweiterungen.
+
+## 🚀 Schnellstart
+
+Du brauchst **Python 3.11–3.13**.
+
+```sh
+git clone https://github.com/weryk153/ai-character-engine.git
+cd ai-character-engine
+python -m venv .venv
+```
+
+Aktiviere die Umgebung mit `source .venv/bin/activate` unter macOS/Linux oder `.venv\Scripts\Activate.ps1` in Windows PowerShell. Danach installieren:
+
+```sh
+python -m pip install .
+```
+
+Starte einen lokalen OpenAI-kompatiblen Modellserver, etwa LM Studio. Ersetze `your-loaded-model` durch die Kennung des geladenen Modells und passe die URL an. Beide Aufrufe verwenden denselben Charakter; der zweite erhält den vorherigen Austausch.
+
+```python
+import asyncio
+from ai_character_engine import CharacterProfile, CharacterRuntime
+from ai_character_engine.llm.local import OpenAICompatibleChatClient
+
+async def main():
+    llm = OpenAICompatibleChatClient(
+        base_url="http://127.0.0.1:1234/v1",
+        model="your-loaded-model",
+    )
+    character = CharacterRuntime(
+        character=CharacterProfile(
+            id="mei", name="Mei",
+            description="A friendly companion who gives concise answers.",
+        ),
+        llm=llm,
+    )
+    try:
+        print((await character.run_turn("Call me Alex.")).text)
+        print((await character.run_turn("What name did I ask you to use?")).text)
+    finally:
+        await llm.client.close()
+
+asyncio.run(main())
+```
+
+Das Beispiel nutzt den Gesprächsverlauf. Für die Fortsetzung nach einem Neustart ergänze [Sitzungsspeicherung](examples/session_runtime.py). Langzeitgedächtnis, Reflexion und Ziele werden separat konfiguriert. Siehe [Installationsanleitung](docs/getting-started.md).
+
+Ein Host, der mit einem einzigen Charakter spricht – ein Chatfenster, eine Sprachanwendung, ein Desktop-Avatar –, kann sich diese Konfiguration sparen: [`CharacterCompanion`](docs/companion.md) ist die Engine, in der Gedächtnis, Stimmung, Ziele, Reflexion und Unterbrechung bereits verdrahtet sind, hinter einem einzigen `reply()`. Ihr Kontext wird fortlaufend in das Gespräch geschrieben, sodass der Prompt-Cache eines lokalen Modells von Runde zu Runde nutzbar bleibt. Siehe [`examples/companion_chat.py`](examples/companion_chat.py).
+
+## 🔌 Modelle und Integrationen
+
+- **LLM:** OpenAI Responses und OpenAI-kompatible Chat Completions, darunter kompatible Endpunkte von LM Studio, Ollama und vLLM. Eigene Clients sind ebenfalls möglich. [Provider-Beispiele](examples/README.md).
+- **Sprache und Avatare:** Audio-Extras und [VRM-Adapter](packages/renderer-vrm/README.md) nach Bedarf. Paketinstallation lädt keine Modelle herunter und startet keine Dienste.
+- **Lokal oder entfernt:** Der Kern verlangt weder Cloud noch API-Schlüssel. Lokale Modelle können lokale Endpunkte nutzen; Anbieter und Werkzeuge bestimmen die Netzwerknutzung.
+
+## 📂 Beispiele und Dokumentation
+
+- [Begleiter-Charakter](examples/companion_chat.py): ein Terminal-Chat mit einem Charakter, der sich merkt, was du erzählst, und sich mit der Zeit verändert, an einem lokalen OpenAI-kompatiblen Endpunkt.
+- [Interaktiver Chat](examples/basic_chat.py) / [Werkzeuge](examples/tool_chat.py): Modell und Zugangsdaten in `.env` konfigurieren.
+- [Sitzungen](examples/session_runtime.py): Speichern und Wiederherstellen mit temporärem Speicher und Offline-Client.
+- [HTTP/SSE/WebSocket](examples/character_service.py): Servicebeispiel für Web und Mobilgeräte, standardmäßig mit Offline-Client. Für den Einsatz Inferenz und Authentifizierung konfigurieren.
+- [Autonomy](examples/autonomy_host.py): Auslöser und Lebenszyklus integrieren.
+- [Erinnerungskorrektur](tests/scenarios/memory_revision.py), [Reflexion und Überzeugungen](tests/scenarios/reflection_long_term_cognition.py), [Ziele](tests/scenarios/goal_motivation_runtime.py), [Wahrnehmung](tests/scenarios/world_environment.py): ausführbare Regressionsszenarien mit Konfiguration und erwarteten Ergebnissen.
+
+[API-Referenz](docs/api-reference.md) · [Konfiguration](docs/configuration.md) · [Bereitstellung und Betrieb](docs/operations.md) · [Erweiterungen](docs/extensions.md)
+
+## Entwicklung und Lizenz
+
+Aktuelle Version: **1.0.0**. CI prüft Linux/macOS/Windows × Python 3.11/3.12/3.13 sowie API-Kompatibilität, Persistenz-Replay, Fehlerinjektion, Leistung in gleicher Umgebung und Paketinstallation. [CI](https://github.com/weryk153/ai-character-engine/actions/workflows/ci.yml) · [Validierung](VALIDATION.md) · [Kompatibilität](docs/compatibility.md).
+
+Fehlerberichte und Korrekturen sind willkommen; siehe [CONTRIBUTING](CONTRIBUTING.md). Lizenz: [Apache-2.0](LICENSE). Modelle, Stimmen und Assets Dritter behalten ihre eigenen Lizenzen.