airoles 0.5.7__tar.gz

airoles-0.5.7/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: airoles
+Version: 0.5.7
+Summary: AI Role 树 — 约束 LLM 防致幻（Role / Policy 唯一源码）
+License-Expression: MIT
+Project-URL: Homepage, https://gitee.com/wangguoran/airoles
+Project-URL: Repository, https://gitee.com/wangguoran/airoles.git
+Keywords: ai,llm,prompt,rag,anti-hallucination,dify
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.25; extra == "anthropic"
+
+# airoles
+
+**Model-Agnostic Agent Role Framework** — 防致幻规则 + PromptBuilder + Runtime。
+
+```bash
+pip install airoles
+export AIROLES_API_KEY=sk-...
+export AIROLES_BASE_URL=https://api.deepseek.com/v1
+export AIROLES_MODEL=deepseek-chat
+```
+
+```python
+from airoles import Planner
+
+result = Planner.from_env().run(
+    "帮我规划一套 ERP 系统",
+    policy_mode="planning",
+)
+print(result["need_confirmation"], result["plan"]["summary"])
+```
+
+**无 API Key 测试**（Mock Provider）:
+
+```python
+from airoles import Agent, CallableProvider
+
+agent = Agent(CallableProvider(your_mock_fn))
+out = agent.plan("...", skip_clarify=True)
+```
+
+## 三层
+
+| 层 | API | 版本 |
+|----|-----|------|
+| Prompt | `ROLE_*`, `POLICY_*`, `templates` | v0.1+ |
+| 组装 | `PromptBuilder` + `PolicySelector` + `compiled/` | v0.5 |
+| Runtime | `Planner.from_env().run()` + Provider + Adapters | v0.3+ |
+
+- [ARCHITECTURE.md](./ARCHITECTURE.md) — 六层架构 + P4 路线图
+- [OPERATION.md](./OPERATION.md) — 发版

airoles-0.5.7/README.md

@@ -0,0 +1,40 @@
+# airoles
+
+**Model-Agnostic Agent Role Framework** — 防致幻规则 + PromptBuilder + Runtime。
+
+```bash
+pip install airoles
+export AIROLES_API_KEY=sk-...
+export AIROLES_BASE_URL=https://api.deepseek.com/v1
+export AIROLES_MODEL=deepseek-chat
+```
+
+```python
+from airoles import Planner
+
+result = Planner.from_env().run(
+    "帮我规划一套 ERP 系统",
+    policy_mode="planning",
+)
+print(result["need_confirmation"], result["plan"]["summary"])
+```
+
+**无 API Key 测试**（Mock Provider）:
+
+```python
+from airoles import Agent, CallableProvider
+
+agent = Agent(CallableProvider(your_mock_fn))
+out = agent.plan("...", skip_clarify=True)
+```
+
+## 三层
+
+| 层 | API | 版本 |
+|----|-----|------|
+| Prompt | `ROLE_*`, `POLICY_*`, `templates` | v0.1+ |
+| 组装 | `PromptBuilder` + `PolicySelector` + `compiled/` | v0.5 |
+| Runtime | `Planner.from_env().run()` + Provider + Adapters | v0.3+ |
+
+- [ARCHITECTURE.md](./ARCHITECTURE.md) — 六层架构 + P4 路线图
+- [OPERATION.md](./OPERATION.md) — 发版

airoles-0.5.7/airoles/__init__.py

@@ -0,0 +1,159 @@
+"""airoles — AI Role 约束树 + PromptBuilder + Agent Runtime."""
+
+from airoles.adapters import (
+    AutoGenAdapter,
+    CrewAIAdapter,
+    DifyAdapter,
+    FlowiseAdapter,
+    LangGraphAdapter,
+)
+from airoles.builder import PromptBuilder, default_builder
+from airoles.prompt_profiler import PromptProfiler, estimate_tokens, policy_token_weights
+from airoles.prompt_trace import PromptTrace
+from airoles.phrases import (
+    RAG_ENTERPRISE_SYSTEM_PROMPT,
+    RAG_FORBIDDEN_PATTERNS,
+    RAG_REFUSAL_PHRASES,
+)
+from airoles.policies import (
+    POLICY_ANTI_HALLUCINATION,
+    POLICY_ANTI_HALLUCINATION_MIN,
+    POLICY_CLARIFY_THRESHOLD,
+    POLICY_CLARIFY_THRESHOLD_MIN,
+    POLICY_DAG_VALIDATION,
+    POLICY_EXECUTION_GATE,
+    POLICY_EXPERIENCE_GUIDED_REASONING,
+    POLICY_HYPOTHESIS_DRIVEN,
+    POLICY_NO_GUESS,
+    POLICY_PLANNING_MODE,
+    POLICY_RAG_ENTERPRISE,
+    POLICY_SAFETY,
+    POLICY_SOP_ENFORCEMENT,
+    POLICY_SUMMARIZER_GROUNDING,
+    POLICY_SUMMARIZER_GROUNDING_MIN,
+    POLICY_TOOL_SELECTION,
+)
+from airoles.providers import (
+    AnthropicProvider,
+    CallableProvider,
+    OllamaProvider,
+    OpenAICompatibleProvider,
+    load_config,
+    provider_from_config,
+    provider_from_env,
+)
+from airoles.registry import (
+    PROMPT_REGISTRY,
+    PromptRule,
+    export_metadata,
+    get_prompt,
+    list_prompt_ids,
+)
+from airoles.selector import (
+    PolicyContext,
+    PolicySelector,
+    PlannerSelection,
+    RoleContext,
+    select_planner_from_profile,
+    select_planner_policies,
+    tier_from_env,
+)
+from airoles.session import SESSION_GLOBAL_CONSTRAINTS, SessionContext
+from airoles.roles import (
+    ROLE_CLARIFIER,
+    ROLE_PLANNER,
+    ROLE_ROUTER,
+    ROLE_SUMMARIZER,
+    ROLE_TASK_PROFILER,
+)
+from airoles.runtime import (
+    Agent,
+    Clarifier,
+    Planner,
+    Router,
+    Summarizer,
+    TaskProfiler,
+)
+from airoles.runtime.json_utils import extract_json, parse_json
+from airoles.runtime.validators import (
+    validate_clarifier_output,
+    validate_planner_plan,
+    validate_router_route,
+)
+from airoles.task_types import TASK_TYPES
+
+_PROMPT_EXPORTS = [
+    "ROLE_ROUTER",
+    "ROLE_CLARIFIER",
+    "ROLE_PLANNER",
+    "ROLE_SUMMARIZER",
+    "ROLE_TASK_PROFILER",
+    "TASK_TYPES",
+    "POLICY_ANTI_HALLUCINATION",
+    "POLICY_ANTI_HALLUCINATION_MIN",
+    "POLICY_CLARIFY_THRESHOLD",
+    "POLICY_CLARIFY_THRESHOLD_MIN",
+    "POLICY_NO_GUESS",
+    "POLICY_SAFETY",
+    "POLICY_EXECUTION_GATE",
+    "POLICY_PLANNING_MODE",
+    "POLICY_TOOL_SELECTION",
+    "POLICY_SOP_ENFORCEMENT",
+    "POLICY_EXPERIENCE_GUIDED_REASONING",
+    "POLICY_HYPOTHESIS_DRIVEN",
+    "POLICY_DAG_VALIDATION",
+    "POLICY_RAG_ENTERPRISE",
+    "POLICY_SUMMARIZER_GROUNDING",
+    "POLICY_SUMMARIZER_GROUNDING_MIN",
+    "RAG_ENTERPRISE_SYSTEM_PROMPT",
+    "RAG_REFUSAL_PHRASES",
+    "RAG_FORBIDDEN_PATTERNS",
+]
+
+_RUNTIME_EXPORTS = [
+    "PromptBuilder",
+    "default_builder",
+    "PromptTrace",
+    "PromptProfiler",
+    "estimate_tokens",
+    "policy_token_weights",
+    "Agent",
+    "Router",
+    "TaskProfiler",
+    "Clarifier",
+    "Planner",
+    "Summarizer",
+    "CallableProvider",
+    "OpenAICompatibleProvider",
+    "AnthropicProvider",
+    "OllamaProvider",
+    "provider_from_env",
+    "provider_from_config",
+    "load_config",
+    "extract_json",
+    "parse_json",
+    "DifyAdapter",
+    "LangGraphAdapter",
+    "CrewAIAdapter",
+    "AutoGenAdapter",
+    "FlowiseAdapter",
+    "PromptRule",
+    "PROMPT_REGISTRY",
+    "get_prompt",
+    "list_prompt_ids",
+    "export_metadata",
+    "PolicyContext",
+    "PolicySelector",
+    "PlannerSelection",
+    "select_planner_policies",
+    "select_planner_from_profile",
+    "RoleContext",
+    "tier_from_env",
+    "SessionContext",
+    "SESSION_GLOBAL_CONSTRAINTS",
+    "validate_planner_plan",
+    "validate_router_route",
+    "validate_clarifier_output",
+]
+
+__all__ = _PROMPT_EXPORTS + _RUNTIME_EXPORTS

airoles-0.5.7/airoles/adapters/__init__.py

@@ -0,0 +1,13 @@
+from airoles.adapters.autogen import AutoGenAdapter
+from airoles.adapters.crewai import CrewAIAdapter
+from airoles.adapters.dify import DifyAdapter
+from airoles.adapters.flowise import FlowiseAdapter
+from airoles.adapters.langgraph import LangGraphAdapter
+
+__all__ = [
+    "DifyAdapter",
+    "LangGraphAdapter",
+    "CrewAIAdapter",
+    "AutoGenAdapter",
+    "FlowiseAdapter",
+]

airoles-0.5.7/airoles/adapters/autogen.py

@@ -0,0 +1,54 @@
+"""Microsoft AutoGen Assistant 配置导出."""
+from __future__ import annotations
+
+from typing import Any
+
+from airoles.builder import PromptBuilder, default_builder
+
+
+class AutoGenAdapter:
+    """导出 AutoGen ConversableAgent / AssistantAgent 配置片段."""
+
+    def __init__(self, builder: PromptBuilder | None = None) -> None:
+        self.builder = builder or default_builder
+
+    def export(self) -> dict[str, Any]:
+        return {
+            "framework": "autogen",
+            "agents": [
+                {
+                    "name": "router",
+                    "system_message": self.builder.router(),
+                    "human_input_mode": "NEVER",
+                    "description": "意图路由，输出 JSON",
+                },
+                {
+                    "name": "clarifier",
+                    "system_message": self.builder.clarifier(),
+                    "human_input_mode": "ALWAYS",
+                    "description": "澄清缺失参数",
+                },
+                {
+                    "name": "task_profiler",
+                    "system_message": self.builder.task_profiler(),
+                    "human_input_mode": "NEVER",
+                },
+                {
+                    "name": "planner",
+                    "system_message": self.builder.planner(policy_mode="free_form"),
+                    "human_input_mode": "NEVER",
+                    "description": "产出需用户 confirm 的计划 JSON",
+                },
+                {
+                    "name": "summarizer",
+                    "system_message": self.builder.summarizer(),
+                    "human_input_mode": "NEVER",
+                },
+            ],
+            "group_chat_suggestion": [
+                "User → router",
+                "router → clarifier (if needs_clarification)",
+                "router → task_profiler → planner",
+                "executor (external) → summarizer",
+            ],
+        }

airoles-0.5.7/airoles/adapters/crewai.py

@@ -0,0 +1,74 @@
+"""CrewAI Agent 定义导出."""
+from __future__ import annotations
+
+from typing import Any
+
+from airoles.builder import PromptBuilder, default_builder
+from airoles.roles import (
+    ROLE_CLARIFIER,
+    ROLE_PLANNER,
+    ROLE_ROUTER,
+    ROLE_SUMMARIZER,
+    ROLE_TASK_PROFILER,
+)
+
+
+class CrewAIAdapter:
+    """导出 CrewAI Agent 的 role / goal / backstory / system_prompt."""
+
+    def __init__(self, builder: PromptBuilder | None = None) -> None:
+        self.builder = builder or default_builder
+
+    def export(self) -> dict[str, Any]:
+        return {
+            "framework": "crewai",
+            "agents": [
+                {
+                    "name": "router",
+                    "role": "任务路由器",
+                    "goal": "理解用户意图并结构化提取参数，判断是否需要澄清",
+                    "backstory": ROLE_ROUTER.strip(),
+                    "system_prompt": self.builder.router(),
+                    "allow_delegation": False,
+                },
+                {
+                    "name": "task_profiler",
+                    "role": "任务画像分析师",
+                    "goal": "深度理解用户真实目标、能力与质量标准",
+                    "backstory": ROLE_TASK_PROFILER.split("\n")[0],
+                    "system_prompt": self.builder.task_profiler(),
+                    "allow_delegation": False,
+                },
+                {
+                    "name": "clarifier",
+                    "role": "任务澄清专家",
+                    "goal": "在信息不足时提出最关键的问题",
+                    "backstory": ROLE_CLARIFIER.strip(),
+                    "system_prompt": self.builder.clarifier(),
+                    "allow_delegation": False,
+                },
+                {
+                    "name": "planner",
+                    "role": "任务规划师",
+                    "goal": "在经验约束下产出可确认的结构化执行计划",
+                    "backstory": ROLE_PLANNER.strip()[:200],
+                    "system_prompt": self.builder.planner(policy_mode="free_form"),
+                    "allow_delegation": False,
+                },
+                {
+                    "name": "summarizer",
+                    "role": "结果汇总员",
+                    "goal": "基于步骤真实输出生成简洁报告，禁止编造",
+                    "backstory": ROLE_SUMMARIZER.strip(),
+                    "system_prompt": self.builder.summarizer(),
+                    "allow_delegation": False,
+                },
+            ],
+            "suggested_crew_flow": [
+                "router",
+                "clarifier?",
+                "task_profiler",
+                "planner",
+                "summarizer",
+            ],
+        }

airoles-0.5.7/airoles/adapters/dify.py

@@ -0,0 +1,29 @@
+"""框架适配器 — 导出可直接粘贴的 Prompt 片段."""
+from __future__ import annotations
+
+from airoles.builder import PromptBuilder, default_builder
+
+
+class DifyAdapter:
+    """Dify 应用 / 知识库 Prompt 导出."""
+
+    def __init__(self, builder: PromptBuilder | None = None) -> None:
+        self.builder = builder or default_builder
+
+    def rag_system_prompt(self) -> str:
+        """知识库 RAG 应用 System Prompt."""
+        return self.builder.rag_enterprise()
+
+    def export(self) -> dict[str, str]:
+        """各环节 system prompt 字典，可直接复制到 Dify 节点."""
+        return {
+            "version": "airoles",
+            "rag_knowledge_base": self.rag_system_prompt(),
+            "router": self.builder.router(),
+            "task_profiler": self.builder.task_profiler(),
+            "clarifier": self.builder.clarifier(),
+            "planner_free_form": self.builder.planner(policy_mode="free_form"),
+            "planner_planning": self.builder.planner(policy_mode="planning"),
+            "summarizer": self.builder.summarizer(),
+            "hypothesis": self.builder.hypothesis(),
+        }

airoles-0.5.7/airoles/adapters/flowise.py

@@ -0,0 +1,44 @@
+"""Flowise Chatflow 节点 Prompt 导出."""
+from __future__ import annotations
+
+from typing import Any
+
+from airoles.builder import PromptBuilder, default_builder
+
+
+class FlowiseAdapter:
+    """导出 Flowise Custom Tool / Chat Prompt Template 节点配置."""
+
+    def __init__(self, builder: PromptBuilder | None = None) -> None:
+        self.builder = builder or default_builder
+
+    def export(self) -> dict[str, Any]:
+        return {
+            "framework": "flowise",
+            "nodes": [
+                {
+                    "type": "ChatPromptTemplate",
+                    "label": "airoles_router",
+                    "systemMessagePrompt": self.builder.router(),
+                    "input": "{{userInput}}",
+                },
+                {
+                    "type": "ChatPromptTemplate",
+                    "label": "airoles_planner",
+                    "systemMessagePrompt": self.builder.planner(policy_mode="free_form"),
+                    "input": "{{userInput}}\n\nRouter: {{routerOutput}}",
+                },
+                {
+                    "type": "ChatPromptTemplate",
+                    "label": "airoles_rag",
+                    "systemMessagePrompt": self.builder.rag_enterprise(),
+                    "input": "Context:\n{{context}}\n\nQuestion:\n{{question}}",
+                },
+                {
+                    "type": "ChatPromptTemplate",
+                    "label": "airoles_summarizer",
+                    "systemMessagePrompt": self.builder.summarizer(),
+                    "input": "步骤结果:\n{{stepOutputs}}",
+                },
+            ],
+        }

airoles-0.5.7/airoles/adapters/langgraph.py

@@ -0,0 +1,47 @@
+"""LangGraph 节点 Prompt 导出."""
+from __future__ import annotations
+
+from typing import Any
+
+from airoles.builder import PromptBuilder, default_builder
+
+
+class LangGraphAdapter:
+    """导出 LangGraph StateGraph 各节点的 system prompt 与建议边."""
+
+    def __init__(self, builder: PromptBuilder | None = None) -> None:
+        self.builder = builder or default_builder
+
+    def export(self) -> dict[str, Any]:
+        return {
+            "framework": "langgraph",
+            "nodes": {
+                "router": {
+                    "system": self.builder.router(),
+                    "output": "json",
+                },
+                "clarifier": {
+                    "system": self.builder.clarifier(),
+                    "output": "json",
+                },
+                "task_profiler": {
+                    "system": self.builder.task_profiler(),
+                    "output": "json",
+                },
+                "planner": {
+                    "system_free_form": self.builder.planner(policy_mode="free_form"),
+                    "system_planning": self.builder.planner(policy_mode="planning"),
+                    "output": "json",
+                },
+                "summarizer": {
+                    "system": self.builder.summarizer(),
+                    "output": "text",
+                },
+            },
+            "suggested_edges": [
+                {"from": "router", "to": "clarifier", "when": "needs_clarification"},
+                {"from": "router", "to": "task_profiler", "when": "not needs_clarification"},
+                {"from": "task_profiler", "to": "planner"},
+                {"from": "planner", "to": "END", "when": "need_confirmation"},
+            ],
+        }