Pinta AI SDK for Python agents

Pinta adds observability, telemetry masking and local tool-call policy evaluation to Python agents. LangChain integration uses middleware; no sidecar is required.

Requirements: Python 3.12 or newer. LangChain integration requires langchain >= 1.0 with create_agent.

The distribution name is pinta-ai-sdk; the Python import remains pinta. It is not the unrelated pinta distribution on PyPI. If you installed an earlier private pinta-ai wheel, uninstall that distribution before installing this one: both use the same Python namespace.

Install

If your application already has a compatible LangChain installation:

python -m pip install pinta-ai-sdk

To install LangChain dependencies as well:

python -m pip install "pinta-ai-sdk[langchain]"

Check the installed version and run the bundled offline self-check:

python -c "import pinta; print(pinta.__version__)"
python -m pinta.selfcheck

The self-check requires LangChain. It uses a deterministic local model and in-memory tools, does not contact a model provider or the Pinta backend, and does not prove that your application's telemetry has reached the management console.

Offline installation into an existing LangChain application

On an internet-connected computer using the same Python minor version as the target server, download the SDK and its dependencies. Replace VERSION with the selected release number:

python -m pip download "pinta-ai-sdk==VERSION" -d sdk --only-binary=:all: --platform any

Transfer the entire sdk directory through your approved file-transfer channel. In the target application's Python environment:

python -m pip install --no-index --find-links=sdk "pinta-ai-sdk==VERSION"
python -m pinta.selfcheck

This path deliberately omits the langchain extra: the application already provides LangChain. --platform any accepts platform-independent wheels only, instead of accidentally downloading a workstation-specific native dependency. Installing or upgrading LangChain itself requires a separate bundle compatible with the server's Python version, operating system and architecture.

Connect an application

Set PINTA_BACKEND_URL and PINTA_API_KEY in the application process using your organization's approved endpoint and secret-management mechanism. Start with PINTA_GUARD_MODE=monitor; switch to enforce only after reviewing policies and normal application behavior.

At process startup, configure Pinta. Add middleware at the agent factory and provide the authenticated application's user identity around each invocation:

from langchain.agents import create_agent
from pinta import PintaSettings, configure, get_runtime, pinta_context
from pinta.langchain import PintaMiddleware

configure(PintaSettings.from_env())
agent = create_agent(model, tools=tools, middleware=[PintaMiddleware()])

async def answer(user, session_id, messages):
    async with pinta_context(
        user_id=user.id, user_email=user.email, session_id=session_id,
    ):
        return await agent.ainvoke({"messages": messages})

# In the application's async shutdown hook:
# await get_runtime().ashutdown()

Here model, tools and user are supplied by your application. Installation alone does not instrument an agent or enable telemetry transmission. Outbound HTTPS to the configured Pinta endpoint is required for export and policy refresh; local evaluation and the self-check do not require that connection.

Scope and limitations

• Masking protects Pinta telemetry, not original business inputs, tool results or prompts sent to a model provider.
• monitor evaluates without blocking. enforce blocks DENY and REVIEW before the selected tool handler executes.
• Policy evaluation errors fail open with diagnostics; masking errors redact the affected telemetry value and are reported as failures.
• Detection depends on configured policies and supported input shapes. This SDK is not universally equivalent to every TypeScript runtime extractor and does not guarantee detection of every credential or unsafe action.
• Treat this alpha SDK as a version-pinned integration and validate your own normal and violation cases before enforcement.

MIT licensed. Learn more at pinta.sh.