Metadata-Version: 2.4
Name: IlinaEngine
Version: 0.8.2
Summary: Ilina Engine 是一个以对话树为核心的 AI 聊天后端系统。支持树状对话、读写文件、MCP 和 Skills
Project-URL: Repository, https://github.com/Foves7017/IlinaEngine
Author: Foves7017
License: MIT License
        
        Copyright (c) 2026 Foves7017
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: fovesconfig
Requires-Dist: foveslog
Requires-Dist: mcp
Requires-Dist: openai
Description-Content-Type: text/markdown

# IlinaEngine
Ilina Engine 是一个以对话树为核心的 AI 聊天后端系统。支持树状对话、读写文件、MCP 和 Skills

## 重要说明
当前版本 (0.8.x) 还是一个开发中版本，许多功能也许不稳定，也有可能会增删接口，请务必注意。

关于版本更新的详细内容请见后文。

## 安装方法
Ilina Engine 已经发布到 PyPI，你可以使用下面的命令安装：

```
pip install IlinaEngine
```

你也可以前往这个页面，看看我为 Ilina Engine 开发的 GUI，然后直接使用。
https://github.com/Foves7017/IlinaGUI

本项目的地址：
https://github.com/Foves7017/IlinaEngine

# 配置 IlinaEngine
首次启动后，IlinaEngine会使用默认配置创建 `./configs/ai.json`，你可以在启动前手动创建它，也可以启动后手动修改，但之后可能需要重新运行程序。
[这里](./docs/config.md)介绍了所有的配置项。

请首先至少配置可用的主要模型和辅助模型。
# 对话引擎
对于对话树的操作全部可以通过 Engine 模块实现，Engine 模块同时也提供了直接调用 API 生成回复的能力。
[这里](./docs/engine.md)记录了所有引擎可以调用的接口，上述的 GUI 则是使用这些接口的示例。

# 对话树（Conversation Tree）

与传统聊天软件的线性消息列表不同，IlinaEngine 使用**树结构（Tree）**存储整个对话。

每一条消息都是一个节点（Node），节点之间通过父子关系连接，形成一棵完整的对话树。

## 基本结构

```text
System
└── User：你好
    └── Assistant：你好，请问有什么可以帮助你？
        ├── User：介绍一下 Python
        │   └── Assistant：Python 是一种...
        │
        └── User：介绍一下 C++
            └── Assistant：C++ 是一种...
```

每个节点都可以是：

* User（用户消息）
* Assistant（模型回复）
* Tool（工具调用结果）
* System（系统提示词）
* Error（错误节点）

树中的每一条路径都代表一次完整的对话上下文。

---

## 分支机制

在任意节点上：

* 修改消息
* 重新生成回答
* 从历史节点继续对话

都不会覆盖原有内容。

系统会创建一个新的子节点作为新的分支。

例如：

```text
User：推荐一本书
└── Assistant：推荐《三体》
    ├── User：为什么？
    │   └── Assistant：因为...
    │
    └── User：换一本
        └── Assistant：推荐《银河帝国》
```

原始对话会被完整保留。

你可以随时切换到任意分支继续对话。

---

## 当前分支

每个节点都记录一个指向子节点的指针（Pointer）。

Pointer 用来标记：

> “当前正在使用哪一条分支”。

例如：

```text
User
└── Assistant
    ├── User A
    │   └── Assistant A
    │
    └▶ User B
        └▶ Assistant B
```

带有 `▶` 标记的路径就是当前活跃分支。

当模型生成回复时，系统会沿着这条路径向下收集消息，构造发送给模型的上下文。

---

## 修改历史

由于所有旧节点都会被保留，因此：

* 可以查看任意历史版本
* 可以比较不同回答
* 可以回到过去的任意时间点
* 可以从任意节点创建新的对话路线

整个对话过程类似于 Git 的提交树：

```text
A
└── B
    ├── C
    │   └── D
    │
    └── E
        └── F
```

不同的是，这里的节点不是代码提交，而是一次次对话消息。

---

## 优势

相比传统线性聊天记录，对话树能够：

* 保留所有历史版本
* 支持无限分支探索
* 支持多次重新生成而不丢失旧结果
* 支持修改任意历史消息
* 支持从任意节点继续对话
* 为 AI Agent、工具调用与长期记忆提供更灵活的上下文管理能力

对话不再是一条线，而是一张不断生长的思维树。
