Boring Python API 開發與整合指南 (V10.26)

將 Boring 的智慧 (Intelligence)、評估 (Judge) 與安全 (Shadow Mode) 直接嵌入您的 Python 應用程式中。

Boring-Gemini 不僅僅是一個 CLI 工具，它也是一個模組化的 Python 庫。您可以將其核心模組導入到您自己的 AI 應用程式或自動化腳本中。

📦 安裝

pip install boring-aicoding

🧠 Intelligence API (大腦與記憶)

boring.intelligence 模組提供了知識管理、模式學習和向量記憶功能。

1. 管理知識庫 (BrainManager)

使用 BrainManager 來存取或更新 .boring/brain 中的長期記憶與學習模式。

from boring.intelligence.brain_manager import BrainManager, LearnedPattern

# 初始化 (自動載入 .boring/brain)
brain = BrainManager(project_path="./my_project")

# 1. 查詢已學習的模式 (Pattern Mining)
patterns = brain.get_patterns(category="error_handling")
for p in patterns:
    print(f"Pattern [{p.confidence}]: {p.description}")

# 2. 記錄新學到的知識
new_pattern = LearnedPattern(
    trigger="ConnectionError",
    solution="Implement exponential backoff in retry logic",
    confidence=0.9
)
brain.learn_pattern(new_pattern)

2. 混合 RAG (RAGRetriever)

使用高階的 RAGRetriever 進行語義搜尋與依賴擴展。

from boring.rag.rag_retriever import RAGRetriever

retriever = RAGRetriever(project_path=".")

# 語義搜尋 (RAG)
results = retriever.search("safe file handling", top_k=3)
for res in results:
    print(f"Found in {res['path']}: {res['snippet']}")

---

⚖️ Judge API (評估與準則)

boring.judge 模組提供了結構化的評估框架，適合用於 LLM 輸出的品質控管。

定義評估準則 (Rubric)

您可以定義自己的 Rubric 並將其應用於評估流程。

from boring.judge.rubrics import Rubric, Criterion

# 1. 定義準則
security_rubric = Rubric(
    name="API Security",
    criteria=[
        Criterion(name="Auth", description="Standard OIDC/OAuth2 usage", weight=1.0),
        Criterion(name="Validation", description="Input sanitization", weight=0.8),
        Criterion(name="Logging", description="No secrets in logs", weight=1.0),
    ]
)

# 2. 導出為 Markdown (供 LLM 使用)
print(security_rubric.to_markdown())

# 3. 程式化評分 (如果已有 Score 物件)
# score = evaluator.evaluate(code, security_rubric)

---

🛡️ Loop API (工作流與安全)

boring.loop 模組提供了安全防護和原子操作，非常適合構建強健的自動化腳本。

1. Shadow Mode 保護 (ShadowModeGuard)

將您的腳本包裹在 Shadow Mode 中，防止意外的毀滅性操作。

from boring.loop.shadow_mode import ShadowModeGuard, OperationSeverity, ShadowModeLevel

# 初始化守衛 (嚴格模式)
guard = ShadowModeGuard(level=ShadowModeLevel.STRICT)

# 嘗試執行操作
def delete_database():
    op = guard.create_operation(
        type="delete",
        target="./data.db",
        severity=OperationSeverity.CRITICAL
    )

    if guard.allow(op):
        print("Deleting...")
        # os.remove("./data.db")
    else:
        print(f"Operation blocked: {op.reason}")

delete_database()
# Output: Operation blocked: High severity requires approval in STRICT mode

2. 原子交易 (TransactionManager)

確保一組檔案操作要麼全部成功，要麼全部回滾。

from boring.loop.transactions import TransactionManager

tx = TransactionManager(project_path=".")

with tx.begin() as transaction:
    try:
        # 這些操作會先寫入暫存區
        transaction.write("config.py", "DEBUG = False")
        transaction.write("src/main.py", "import config")

        # 提交 (原子寫入)
        transaction.commit()
        print("原子更新成功")

    except Exception as e:
        # 自動回滾 (不修改任何檔案)
        transaction.rollback()
        print(f"更新失敗，已回滾: {e}")