Python API Integration Guide (V10.26)

Embed Boring's Intelligence, Judge, and Shadow Mode directly into your Python apps.

Boring-Gemini is not just a CLI tool; it's a modular Python library. You can import its core modules into your own AI applications or automation scripts.

📦 Installation

pip install boring-aicoding

🧠 Intelligence API (Brain & Memory)

The boring.intelligence module provides knowledge management, pattern learning, and vector memory capabilities.

1. Knowledge Base Management (BrainManager)

Use BrainManager to access or update long-term memory and learned patterns in .boring/brain.

from boring.intelligence.brain_manager import BrainManager, LearnedPattern

# Initialize (automatically loads .boring/brain)
brain = BrainManager(project_path="./my_project")

# 1. Query learned patterns (Pattern Mining)
patterns = brain.get_patterns(category="error_handling")
for p in patterns:
    print(f"Pattern [{p.confidence}]: {p.description}")

# 2. Record new knowledge
new_pattern = LearnedPattern(
    trigger="ConnectionError",
    solution="Implement exponential backoff in retry logic",
    confidence=0.9
)
brain.learn_pattern(new_pattern)

2. Hybrid RAG (RAGRetriever)

Use the high-level RAGRetriever for semantic search and dependency expansion.

from boring.rag.rag_retriever import RAGRetriever

retriever = RAGRetriever(project_path=".")

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

---

⚖️ Judge API (Evaluation & Rubrics)

The boring.judge module provides a structured evaluation framework, perfect for controlling LLM output quality.

Defining Rubrics

You can define your own Rubric and apply it to evaluation processes.

from boring.judge.rubrics import Rubric, Criterion

# 1. Define Rubric
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. Export to Markdown (for LLM context)
print(security_rubric.to_markdown())

# 3. Programmatic scoring usage
# score = evaluator.evaluate(code, security_rubric)

---

🛡️ Loop API (Workflow & Security)

The boring.loop module provides security guards and atomic operations, ideal for building robust automation scripts.

1. Shadow Mode Protection (ShadowModeGuard)

Wrap your scripts in Shadow Mode to prevent accidental destructive operations.

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

# Initialize Guard (Strict Mode)
guard = ShadowModeGuard(level=ShadowModeLevel.STRICT)

# Attempt operation
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. Atomic Transactions (TransactionManager)

Ensure a set of file operations either all succeed or all roll back.

from boring.loop.transactions import TransactionManager

tx = TransactionManager(project_path=".")

with tx.begin() as transaction:
    try:
        # Operations are staged first
        transaction.write("config.py", "DEBUG = False")
        transaction.write("src/main.py", "import config")

        # Commit (Atomic Write)
        transaction.commit()
        print("Update successful")

    except Exception as e:
        # Auto-rollback (No files modified)
        transaction.rollback()
        print(f"Update failed, rolled back: {e}")