architext 0.1.3

The Context Engineering framework for building smarter, more reliable AI Agents.

Architext

Architext: The Context Engineering framework for building smarter, more reliable AI Agents.

---

Architext (源自 "Architecture" + "Text") 是一个为大语言模型（LLM）应用设计的、专注于上下文工程 (Context Engineering) 的 Python 库。它提供了一套优雅、强大且面向对象的工具，让您能够像软件工程师设计架构一样，精确、动态地构建和重组 LLM 的输入上下文。

告别散乱的字符串拼接和复杂的构建逻辑，进入一个将上下文视为可操作、可组合、可演进的工程化实体的新时代。

🤔 什么是上下文工程 (Context Engineering)？

在构建复杂的 AI Agent 时，提供给 LLM 的上下文（即 messages 列表）的质量和结构直接决定了其性能的上限。上下文工程是一门新兴的学科，它关注于：

• 结构化（Structuring）: 如何将来自不同数据源（文件、代码、数据库、API）的信息，组织成 LLM 最易于理解的结构？
• 动态化（Dynamism）: 如何根据对话的进展，实时地添加、移除或重排上下文内容，以保持其相关性和时效性？
• 优化（Optimization）: 如何在有限的上下文窗口内，智能地筛选和呈现最高价值的信息，以最大化性能并最小化成本？

Architext 正是为解决这些工程化挑战而生。

✨ Architext: 为上下文工程而生

Architext 的核心理念是将上下文的构建过程从临时的“手工艺”提升为系统化的“工程学”。

• 将上下文模块化 (Modularize Context): 每个信息源（如文件内容、工具列表）都是一个独立的 ContextProvider，负责生产标准化的 ContentBlock。
• 视消息为可变结构 (Messages as Mutable Structures): 消息不再是静态的文本，而是一个可被实时操作的对象容器。您可以像操作精密组件一样，对其内部的内容块进行精确的 pop, insert, append。
• 以架构师的思维构建提示 (Think like an Architect): 您可以像设计软件架构一样，清晰地布局 SystemMessage 和 UserMessage 的结构，并通过统一的接口动态调整，以应对不同的任务场景。

🚀 核心特性 (Features)

• 面向对象的上下文建模: 将 SystemMessage, UserMessage 等视为可操作的一等公民。
• 原子化的内容块 (ContentBlock): 将上下文分解为可独立操作和移动的最小单元。
• 列表式动态操作: 通过 pop(), insert() 等方法，实现对上下文内容的实时、精确控制。
• 提供者驱动架构: 通过可扩展的 ContextProvider 体系，轻松接入任何数据源。
• 智能缓存与按需刷新: 内置高效的缓存机制，仅在数据源变化时才刷新，显著提升性能。
• 统一的穿透式接口: 通过顶层 Messages 对象，直接访问和控制任何底层的 ContextProvider，实现状态的集中管理。

📦 安装 (Installation)

pip install architext

🚀 快速上手：一次上下文工程实践

Architext 的核心在于其直观、灵活的 API。下面通过一系列独立的示例，展示如何利用它进行高效的上下文工程。

示例 1: 基础布局与首次渲染

这是最基础的用法。我们声明式地构建一个包含 System 和 User 消息的对话结构。

# --- 示例 1: 基础布局 ---
import asyncio
from architext import Messages, SystemMessage, UserMessage, Texts, Tools

async def example_1():
    # 1. 定义你的上下文提供者
    tools_provider = Tools(tools_json=[{"name": "run_test"}])
    system_prompt = Texts("system_prompt", "你是一个专业的AI代码审查员。")

    # 2. 声明式地构建消息列表
    messages = Messages(
        SystemMessage(system_prompt, tools_provider),
        UserMessage(Texts("user_input", "请帮我审查以下Python代码。"))
    )

    # 3. 渲染最终的 messages 列表
    print("--- 示例 1: 渲染结果 ---")
    for msg in await messages.render():
        print(msg)

asyncio.run(example_1())

预期输出:

--- 示例 1: 渲染结果 ---
{'role': 'system', 'content': '你是一个专业的AI代码审查员。\n\n<tools>[{\'name\': \'run_test\'}]</tools>'}
{'role': 'user', 'content': '请帮我审查以下Python代码。'}

---

示例 2: 穿透更新与自动刷新

Architext 的强大之处在于您可以随时更新底层的上下文源，而系统会在下次渲染时自动、高效地刷新内容。

# --- 示例 2: 穿透更新 ---
import asyncio
from architext import Messages, UserMessage, Files

async def example_2():
    # 1. 初始化一个包含文件提供者的消息
    files_provider = Files()
    messages = Messages(
        UserMessage(files_provider)
    )

    # 2. 此刻文件内容为空，渲染结果为空列表
    print("--- 初始状态 (文件内容为空) ---")
    print(await messages.render())

    # 3. 通过穿透接口更新文件内容
    # 这会自动将 files_provider 标记为“过期”
    print("\n>>> 通过 messages.provider 更新文件...")
    file_instance = messages.provider("files")
    if file_instance:
        file_instance.update("main.py", "def main():\n    pass")

    # 4. 再次渲染，Architext 会自动刷新已过期的 provider
    print("\n--- 更新后再次渲染 ---")
    for msg in await messages.render():
        print(msg)

asyncio.run(example_2())

预期输出:

--- 初始状态 (文件内容为空) ---
[]

>>> 通过 messages.provider 更新文件...

--- 更新后再次渲染 ---
{'role': 'user', 'content': "<files>\n<file path='main.py'>def main():\n    pass...</file>\n</files>"}

---

示例 3: 动态重构上下文 (pop 和 insert)

这是上下文工程的核心实践。您可以像操作列表一样，动态地将一个内容块从一条消息移动到另一条消息，以适应不同的任务需求。

# --- 示例 3: 动态重构 ---
import asyncio
from architext import Messages, SystemMessage, UserMessage, Texts, Tools

async def example_3():
    # 1. 初始布局：工具在 SystemMessage 中
    tools_provider = Tools(tools_json=[{"name": "run_test"}])
    messages = Messages(
        SystemMessage(tools_provider),
        UserMessage(Texts("user_input", "分析代码并运行测试。"))
    )
    print("--- 初始布局 ---")
    for msg in await messages.render(): print(msg)

    # 2. 运行时决策：为了更强的指令性，将工具上下文移动到用户消息中
    print("\n>>> 重构上下文：将 'tools' 块移动到 UserMessage...")

    # a. 从任何消息中全局弹出 'tools' 提供者
    popped_tools_provider = messages.pop("tools")

    # b. 通过索引精确定位到 UserMessage (messages[1])，并插入它
    if popped_tools_provider:
        messages[1].content.insert(0, popped_tools_provider)

    # 3. 查看重构后的结果
    print("\n--- 重构后的最终布局 ---")
    for msg in await messages.render(): print(msg)

asyncio.run(example_3())

预期输出:

--- 初始布局 ---
{'role': 'system', 'content': "<tools>[{'name': 'run_test'}]</tools>"}
{'role': 'user', 'content': '分析代码并运行测试。'}

>>> 重构上下文：将 'tools' 块移动到 UserMessage...

--- 重构后的最终布局 ---
{'role': 'system', 'content': ''}
{'role': 'user', 'content': "<tools>[{'name': 'run_test'}]</tools>\n\n分析代码并运行测试。"}

(注意: SystemMessage 的内容变为空，因为它唯一的块被移走了，所以在最终渲染时可能会被过滤掉)

🤝 贡献 (Contributing)

上下文工程是一个激动人心的新领域。我们欢迎任何形式的贡献，共同探索构建更智能、更高效的 AI Agent。无论是报告 Bug、提出新功能，还是提交代码，您的参与都至关重要。

📄 许可证 (License)

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。