Skip to content
El1mirPublic

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

6 Commits

Folders and files

Repository files navigation

⚗️ elixir(贤者之石)

emotion-first 的会话式双核智能体 SDK

License Python Version

当前版本:0.1.1 · 开发环境 CPython 3.14.3 · 包管理 uv


目录

上手指南(开发)

开发前的配置要求

  1. Python ≥ 3.10(本地开发用 CPython 3.14.3)
  2. uv(包管理器)——安装 uv

安装步骤

  1. 克隆本仓库(或直接使用当前目录)
    git clone https://github.com/El1mir/Elixir.git
    cd elixir
  2. 创建虚拟环境并安装依赖(uv 会自动按 pyproject.toml / uv.lock 复现)
    uv sync
  3. 验证安装
    uv run python -c "import elixir; print(elixir.__version__)"

多模态消息与视觉能力探测

Message 兼容 OpenAI Chat Completions 的文本和图片输入。纯文本调用保持不变;图片可以使用 SDK 类型,也可以直接使用 OpenAI part 字典:

from elixir import ImagePart, TextPart

user_content = [
    TextPart("请描述这张图"),
    ImagePart("https://example.com/photo.png", detail="high"),
]
async for sentence in session.start_turn(user_content):
    print(sentence)

图片 URL 支持 http(s) 和 base64 data:image/...。当前输入会在每次分析步骤中附带,最近历史轮中的图片也会随重水合恢复;rounds 记录同时保留 user_content,而 user 字段仍是用于展示的纯文本。

模型能力需要通过真实请求探测,而不是依据模型名猜测:

result = await llm.test_vision()
# result.supported / result.response / result.error

check_vision_capability() 是同一接口的语义化别名。探测使用内置最小图片,也可以传入自己的图片 URL 和提示词。

参与开发

跑测试

无外部服务依赖(LLM 用确定性 fake;真实 Provider 用 httpx.MockTransport 拦截)。一条命令跑全部:

uv run python -m unittest discover -s tests -t .

贡献流程

贡献使开源社区成为一个学习、激励和创造的绝佳场所。你所做的任何贡献都非常感谢。

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

版本管理

该项目使用 Git + uv 进行版本管理(pyproject.toml 的 version 为当前版本,当前 0.1.1)。

文件目录说明

树形图已按 .gitignore 排除忽略目录(.venv、docs、.scratch、.idea、elixir.egg-info) 及运行时生成目录(demo/data、demo/logs、__pycache__、dist)。 每行 # 后为该文件/目录的一句话用途。

elixir/                                   # 项目根
│
├── .github/                              # GitHub Actions CI
│   └── workflows/
│       └── release.yml                   # push 到 main:测试 → uv build → 以 v<版本>-<短提交id> 为 tag 发 Release
│
├── elixir/                               # SDK 源码包(主代码)
│   ├── __init__.py                       # 包出口:new_session / Session / Settings / 类型 / OpenAIProvider
│   ├── session.py                        # Session 运行时 + 装配:单 active 轮、打断令牌、轮初注入、三层工具合并、轮序落盘
│   ├── context.py                        # Live 会话上下文 SessionContext:K 轮窗口、round_id 分配、淘汰、重水合 restore
│   ├── driver.py                         # 双人设 function-calling 驱动循环:四控制函数 + 步数/自循环预算
│   ├── synthesizer.py                    # 第四者回复合成:分句符切流(字面转义容错)、逐句 yield
│   ├── roles.py                          # 心核 / 智核 / 合成默认提示词(宿主可经 role_prompt_overrides 整段覆盖)
│   ├── memory.py                         # 记忆器抽象 + LongTermMemory(日记/压缩/检索) + EmotionMemory(情绪流水)
│   ├── store.py                          # Store:内存真源 + 领域读写 + 定时/退出 flush + 重水合
│   ├── datasource.py                     # DataSourceProvider 持久后端抽象
│   ├── datasources/                      # 数据源后端实现
│   │   ├── __init__.py                   # 数据源包标记
│   │   └── jsonl.py                      # jsonl 默认后端(每 session 一个追加文件)
│   ├── llm.py                            # LLMProvider 抽象:complete + stream_text
│   ├── providers/                        # 真实厂商 Provider 适配器(OpenAI 官方 SDK)
│   │   ├── __init__.py                   # 适配器包标记
│   │   └── openai.py                     # OpenAI 兼容(官方 SDK:tools + 流式;disable_thinking 关推理思考)
│   ├── settings.py                       # Settings 全字段默认值(K/M/预算/情绪/打字节奏/分句/日志等)
│   ├── tools.py                          # 用户扩展 Tool 基类(schema + allowed_in 门控)
│   ├── logger.py                         # Logger 运行日志抽象 + StdLogger(stdlib 按天 .txt)
│   ├── types.py                          # 公共类型(Round/ToolSchema/ToolCall/AssistantMessage/Message 等)
│   └── exceptions.py                     # 会话级异常(ActiveTurnError / DuplicateToolError …)
│
├── demo/                                 # 最小行式 TUI 对话演示(独立于 SDK 打包;运行方式见 demo/README)
│   ├── chat.py                           # 入口:读环境变量 → 注入 demo 人设 → 建 Provider/Session → 逐句对话 → 退出 flush/close
│   ├── personas.py                       # demo 专属精简双核人设(经 Settings.role_prompt_overrides 注入,不写进框架)
│   ├── README.md                         # demo 的配置与运行说明
│   ├── run.ps1                           # Windows 一键运行模板(密钥为占位,按需自填)
│   └── .env.example                      # 环境变量模板(密钥等,demo 不自动读取)
│
├── tests/                                # 标准库 unittest 测试(无 pytest / 外部服务,LLM 用确定性 fake)
│   ├── __init__.py                       # 测试包标记
│   ├── fake_llm.py                       # 测试用 ScriptedLLM(脚本队列 + 逐次流文本)
│   ├── test_foundation.py                # 01 工程地基:类型/Settings/Logger/Tool/异常
│   ├── test_store.py                     # 02 持久化:Store + jsonl 往返
│   ├── test_session_turn.py              # 03 最小会话轮:驱动/合成/打字/预算/单 active
│   ├── test_interrupts.py                # 04 打断语义:interject / force_stop
│   ├── test_memory.py                    # 05 记忆器框架 + EmotionMemory
│   ├── test_longterm.py                  # 07 LongTermMemory:压缩/日记/检索
│   ├── test_rehydration.py               # 08 重水合与多会话隔离
│   ├── test_user_tools.py                # 06 用户 Tool 三层合并与门控
│   ├── test_providers.py                 # 12 OpenAI Provider(官方 SDK + MockTransport,含 thinking 开关)
│   ├── test_demo.py                      # 13 demo 最小 TUI 离线冒烟(含运行日志落盘)
│   └── test_e2e.py                       # 09 端到端聚合回归网
│
├── pyproject.toml                        # 构建与依赖清单(uv 管理)
├── uv.lock                               # uv 锁定的依赖版本
├── README.md                             # 本文件
└── LICENSE                               # Apache-2.0 许可证全文

构建与发布

当前版本:0.1.1(与 pyproject.toml 的 version 一致;升版时同步修改)。

本地构建并发布到 PyPI

uv build        # 产出 dist/elixir-0.1.1-py3-none-any.whl 与 .tar.gz
uv publish      # 发布到 PyPI(需 UV_PUBLISH_TOKEN / PYPI_TOKEN,或按提示登录)

自动构建 → GitHub Release(CI)

.github/workflows/release.yml:每次 push 到 main 自动执行:

  1. uv run 跑全部测试;
  2. uv build 构建 PyPI 包(sdist + wheel);
  3. 以 v<版本>-<短提交id>(如 v0.1.1-689722c)为 tag 创建 GitHub Release,附件 = dist/*。

不能直接用完整 github.sha 作 tag:GitHub 禁止纯 40/64 位十六进制的 tag 名。

CI 只把包发到 GitHub Release;发布到 PyPI 仍为手动 uv publish (如需 CI 自动推 PyPI:在仓库 Secrets 配好 token,并在工作流末尾加一步发布)。

升版步骤:改 pyproject.toml 的 version → uv lock 刷新 → 同步 elixir/__init__.py 与本 README 版本号 → push main 触发新 Release。

作者

El1mir @ 2247335689@qq.com · GitHub

版权说明

本项目采用 Apache License 2.0(见 LICENSE)。

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages