Tozil Integration

v1.0

This page is designed to be read by AI coding assistants (Claude, Cursor, Copilot, Windsurf) and developers. One page, all instructions, no ambiguity.

For AI Agents

If you are an AI coding assistant, follow these steps exactly. The integration requires 2 changes:

1. Install the package: pip install tozil or npm install tozil
2. Add tozil.init() to the app entry point (before any LLM client is created)
3. Set the env var TOZIL_API_KEY (the user will provide this)

Optional: Add user attribution with tozil.set_user(user_id) in auth middleware for per-user cost tracking.

Install

                    Python
                    # pip

                    pip install tozil

                    # or poetry

                    poetry add tozil

                    Node.js
                    # npm

                    npm install tozil

                    # or yarn / pnpm / bun

                    bun add tozil

Initialize

Add this to your app's entry point — before any Anthropic, OpenAI, or Google AI client is created. Tozil will automatically instrument all supported LLM clients.

                    Python
                    import tozil

                    # Initialize — reads TOZIL_API_KEY from env

                    tozil.init()

                    # Your existing code stays the same

                    from anthropic import Anthropic

                    client = Anthropic() # auto-instrumented

                    Node.js
                    import tozil from 'tozil'

                    // Initialize — reads TOZIL_API_KEY from env

                    tozil.init()

                    // Your existing code stays the same

                    import Anthropic from '@anthropic-ai/sdk'

                    const client = new Anthropic() // auto-instrumented

Set the API key

Add your Tozil API key as an environment variable. The user will provide this.

                .env
                TOZIL_API_KEY=tz_ak_your_key_here
            

Optional: User Attribution

To track costs per user, set the user ID in your auth middleware or request handler. All LLM calls in that request context will be attributed to the user.

                    Python
                    # In your auth middleware or route

                    tozil.set_user(request.user.id)

                    # All LLM calls in this request

                    # are now attributed to this user

                    Node.js
                    // In your auth middleware or route

                    tozil.setUser(req.user.id)

                    // All LLM calls in this request

                    // are now attributed to this user

What this does

-- Auto-instruments Anthropic, OpenAI, Google AI SDKs
-- Reports usage async in a background thread
-- Fails silently if Tozil is unreachable
-- Adds less than 1ms latency (non-blocking)

What this does NOT do

-- Does NOT proxy your API calls
-- Does NOT read or store prompts/responses
-- Does NOT affect your app if removed
-- Does NOT require any code changes beyond init()

Framework Integrations

If the project uses a framework, use the appropriate integration:

                    FastAPI
                    from tozil.integrations import TozilMiddleware

                    app = FastAPI()

                    app.add_middleware(TozilMiddleware) # auto user attribution from request

                    Express
                    import { tozilMiddleware } from 'tozil/express'

                    app.use(tozilMiddleware()) // auto user attribution from req.user

                    Next.js
                    // middleware.ts

                    import { withTozil } from 'tozil/next'

                    export const middleware = withTozil()

                    LangChain
                    from tozil.integrations import TozilCallback

                    chain.invoke(input, config={"callbacks": [TozilCallback(user_id="user_123")]})

Uninstall

Remove the package. Remove the init() call. That's it. No config files, no side effects, zero residue.

                    Python
                    pip uninstall tozil
                

                    Node.js
                    npm uninstall tozil
                

Supported providers

Anthropic OpenAI Google AI Mistral Cohere