Add AI capabilities

Use application-owned ports for model calls, typed tools for machine callers, and evaluation cases for behavior you need to measure. Adopt each capability when your application needs it; they share the same plain async use cases and explicit dependency wiring as an HTTP API.

Model-generated input never supplies identity or infrastructure. Your application owns authentication, authorization, provider choice, and resource lifecycle.

Let an agent change the backend

Follow the development workflow to have an agent inspect, change, and verify your backend. The agent MCP server provides access to those development operations; application MCP exposes your use cases to callers.

Add AI behavior to the backend

Keep model calls behind an application-owned protocol, just like a database or external API:

from typing import Protocol

from .schemas import Answer, AnswerRequest


class AnswerGenerator(Protocol):
    async def answer(self, request: AnswerRequest) -> Answer: ...

The use case owns authorization, retrieval, business rules, and the decision to call that port. Infrastructure selects the provider and model at composition. The same use case can serve HTTP and an AI-facing tool:

from app.shared.errors import question_not_answerable
from tenchi.tools import tool, tool_group, tool_handler

from .schemas import Answer, AnswerRequest
from .use_cases.answer_question import answer_question


answer_tool = tool(
    "knowledge.answer",
    request=AnswerRequest,
    result=Answer,
    description="Answer from sources visible to the authenticated user.",
    errors=(question_not_answerable,),
    read_only=True,
    open_world=False,
)

tools = tool_group(
    tool_handler(answer_tool, answer_question),
)

The application-tool boundary validates input and output, publishes a deterministic manifest, and applies the application's lifespan and context to every call. It does not choose an agent SDK or model provider. Call tools in-process from your preferred AI runtime or serve them over authenticated MCP.

Keep production rules in the application

AI callers use the same production boundaries as every other caller:

• Authentication supplies identity through application-owned context wiring.
• Use cases and pure policies authorize every action.
• Tool safety annotations describe behavior but never grant permission.
• Idempotency, rate limits, deadlines, retries, jobs, and observability remain ordinary application concerns.
• Declared errors stay stable; unexpected exceptions and undeclared application errors remain behind a generic invocation failure.

This keeps model prompts and tool-selection logic from becoming an alternate authorization or transaction layer.

Gate behavior that deterministic tests cannot prove

When a provider or model can change behavior without a Python code change, declare application-owned evaluation cases and metrics:

uv run tenchi eval list
uv run tenchi eval run
uv run tenchi eval snapshot --diff evaluations.json

AI evaluations run typed cases with bounded concurrency, timeouts, thresholds, and optional token or cost budgets. The policy snapshot contains no case inputs, so it can make a weakened gate visible in review without running a model during every deterministic check.

See the complete shape

Fieldnotes combines owner-scoped ingestion, background indexing, authenticated application tools, MCP, cited answers behind a provider port, operational reindexing, preflight checks, and evaluation gates without model credentials in CI.

Choose the next page from the role AI will play:

• Let an agent change your backend
• Expose use cases as AI tools
• Gate AI behavior with evaluations
• Study the Fieldnotes reference backend