🔭 tmam

OpenTelemetry-native observability for LLMs, Agents & GPUs

Quick Start · Self-Host with Docker · Features · Cloud · Docs

---

What is tmam?

tmam is an open-source observability platform that gives you deep, real-time visibility into your entire AI stack — from every LLM call and agent trace to GPU utilization and vector database performance.

Built on OpenTelemetry, tmam instruments your existing code automatically with zero changes to your business logic. Every token, latency, cost, exception, and trace flows into a powerful dashboard you can run fully on your own machine or in the cloud.

Why teams use tmam

• 🧠 Full LLM tracing — capture prompts, completions, tokens, cost, and latency across 40+ providers
• 🤖 Agent observability — trace multi-step workflows across CrewAI, LangChain, LlamaIndex, AG2, and more
• ⚡ GPU monitoring — track real-time GPU memory, utilization, and performance metrics
• 🛡️ Guardrails & evals — automated quality checks and AI-arbiter scoring on your outputs
• 📊 Rich analytics — visualize model usage, costs, scores, and vector DB performance
• 👥 Team & org management — invite teammates, assign roles, and collaborate across organizations
• 🔐 Secure by default — RSA-signed JWTs, bcrypt-hashed API keys, and encrypted secrets
• 📦 Runs fully local — your data never has to leave your machine

---

🚀 Quick Start

1. Install the Python SDK

pip install tmam

2. Initialize with 2 lines

from tmam import init

init(
    url="http://localhost:5050/api/sdk",  # your local or cloud endpoint
    public_key="your-public-key",
    secrect_key="your-secret-key",
    application_name="my-app",
    environment="production",
    collect_gpu_stats=True,              # optional: enable GPU monitoring
)

tmam auto-detects and instruments every supported library you have installed.

3. Use your LLM as normal

from openai import OpenAI

@tmam.trace
def ask_ai(self, q: str) -> dict:
    logger.info(f"{Fore.CYAN}Sending question to AI:{Style.RESET_ALL} {q}")
    try:
        response = self.client.chat.completions.create(
            model="gpt-4o-mini",
            messages=[{"role": "user", "content": q}],
        )
        result = response.json() if hasattr(response, "json") else response
        pretty_log("🤖 AI Response", result, Fore.GREEN)
        return result
    except Exception as exc:
        logger.error(f"{Fore.RED}AI request failed:{Style.RESET_ALL} {exc}")
        return {"error": str(exc)}

Every call is automatically traced — tokens, cost, latency, and content — with zero additional code.

---

🧩 Supported Integrations

tmam instruments 40+ frameworks and providers out of the box:

LLM Providers OpenAI · Anthropic · Cohere · Mistral · Groq · Google AI Studio · Vertex AI · AWS Bedrock · Azure AI Inference · Ollama · vLLM · Together AI · GPT4All · Reka · PremAI · AI21 · LiteLLM

Agent Frameworks LangChain · LlamaIndex · CrewAI · AG2 · Haystack · Phidata · Dynamiq · ControlFlow · Julep · Mem0 · EmbedChain · MultiOn · Letta · OpenAI Agents

Vector Databases Chroma · Pinecone · Qdrant · Milvus · Astra

Other ElevenLabs · AssemblyAI · Transformers · Crawl4AI · FireCrawl · GPU Metrics

---

🖥️ Self-Hosting with Docker

Run the full tmam stack — dashboard, API server, and database — on your own machine with a single command.

Prerequisites

• Docker v20+
• Docker Compose v2+

Step 1 — Clone the repo

git clone https://github.com/tmam-dev/tmam.git
cd tmam

Step 2 — Configure the server

Open server/src/.env and update the values for your setup:

# ── Database ──────────────────────────────────────────
DB_TYPE=Local
DB_LOCAL_URI=mongodb://mongo:27017/

# ── Security (required: change these before deploying) ─
EDCRYPT_PASS=change_me_to_something_strong
PBECRYPT_PASS=change_me_to_something_strong

# ── Email via SendGrid ─────────────────────────────────
# Used for: email confirmation, password reset, and team invitations
SENDGRID_API_KEY=your_sendgrid_api_key
SENDGRID_SENDER=support@yourdomain.com
FRONTEND_URL=http://localhost:3001

# ── Google OAuth (optional) ───────────────────────────
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

Tip: The JWT private/public key pair in .env is pre-generated for local development. For production, replace it with your own RSA key pair (see Security).

Step 3 — Configure the web client

Open web-client/.env and set:

# Generate with: openssl rand -base64 32
NEXTAUTH_SECRET=your_generated_secret

NEXTAUTH_URL=http://localhost:3001/
EXTERNAL_API_URL=http://server:5050/

# Must match the Google Client ID in server/.env
GOOGLE_CLIENT_ID=your_google_client_id

Step 4 — Start everything

docker compose up --build

Service	URL	Description
Dashboard	http://localhost:3001	Web UI for observability
API Server	http://localhost:5050	Backend API
SDK Endpoint	http://localhost:5050/api/sdk	Point your SDK url here
MongoDB	localhost:27018	Internal database

Useful Docker commands

# Run in the background
docker compose up --build -d

# Stream logs
docker compose logs -f

# Stop all services
docker compose down

# Stop and wipe all data (database included)
docker compose down -v

---

🌟 Platform Features

🔑 Authentication

tmam supports multiple authentication methods out of the box:

Email & Password signup/signin Users register with their email and are sent a confirmation email before gaining access. All passwords are hashed with bcrypt using configurable salt rounds.

Google Sign-In One-click sign-in with a Google account. No password required. Configure your Google OAuth credentials in both the server and web client .env files to enable it.

Forgot Password Flow Users can request a password reset link via email. The link is time-limited and delivered through SendGrid, containing a secure token to verify the request.

---

📧 Email Notifications (SendGrid)

tmam sends transactional emails for key events through SendGrid:

Trigger	Email Sent
New user registration	Email confirmation link
Forgot password request	Password reset link (24-hour expiry)
Team member invitation	Invite email with assigned role and org name

Configure your SendGrid credentials in server/src/.env:

SENDGRID_API_KEY=your_sendgrid_api_key
SENDGRID_SENDER=support@yourdomain.com
FRONTEND_URL=https://your-deployment-url.com

Email confirmation is gracefully skipped if SENDGRID_API_KEY is not set, making local development friction-free.

---

🔐 Security

tmam is built with security as a first-class concern:

RSA-signed JWT tokens All user sessions use JWTs signed with an RSA private key (RS256) and verified with the corresponding public key. Tokens are cross-validated against the database on every request — a revoked or logged-out token is rejected immediately.

API key authentication for the SDK SDK connections authenticate via a public/secret key pair. The secret key is never stored in plaintext — only a bcrypt hash is persisted server-side and compared at runtime.

Role-based access control Every API route checks the user's role before granting access. Endpoints are protected by stacked middleware that verifies the token, confirms the account is active and verified, and checks role permissions — in that order.

Encrypted secrets vault Sensitive values like LLM API keys can be stored in tmam's encrypted vault using AES-192-CBC (IV-based) or PBE encryption.

To generate a fresh RSA key pair for production:

# Generate private key
openssl genrsa -out private.pem 2048

# Derive public key
openssl rsa -in private.pem -pubout -out public.pem

Then paste the keys (with \n as line separators) into JWT_PRIVATE_SECRET and JWT_PUBLIC_SECRET in server/src/.env.

---

🏢 Organizations & Teams

tmam is built for collaboration. Every workspace is organized around organizations, and each organization can have multiple team members with distinct roles.

Creating an organization

From the dashboard, navigate to Settings → Organizations and create a new org with a name and description. You can create and manage multiple organizations from a single account.

Inviting team members

Add members to your organization by email directly from the dashboard. When you invite someone:

1. They receive an automated invitation email with their assigned role and your organization name
2. Once they register or log in, they appear as a pending member
3. The org admin can approve or reject their join request

Member roles

Each member is assigned a role that determines their access level across the organization. Role changes can be made at any time by an admin from the Members settings page.

Membership lifecycle

The full membership state is tracked — invited → pending → granted/rejected → active/left — giving admins full visibility and control over who has access to what.

---

📊 Observability Dashboard

Once your traces are flowing, the dashboard provides:

• Tracing — full request timelines with nested spans, latency breakdowns, and input/output content
• Exceptions — dedicated view for errors and exceptions captured during LLM calls
• LLM Analytics — token usage over time, cost per model, top models, requests per application
• GPU Analytics — real-time GPU memory and utilization charts
• Vector DB Analytics — query performance and operation-level breakdowns
• Guardrails — define rules to automatically flag unsafe or off-policy outputs
• Evaluations — run AI-arbiter scoring and track dataset evaluation results
• Prompt Management — version-controlled prompts with an OpenGround playground for comparison
• Scores & Feedback — collect and trend user feedback and quality scores

---

☁️ Don't want to self-host?

Try cloud.tmam.ai — zero setup, instant access to all features. Sign up, generate your API keys, and point your SDK at the cloud endpoint:

init(
    url="https://cloud.tmam.ai/api/sdk",
    public_key="your-cloud-public-key",
    secrect_key="your-cloud-secret-key",
    application_name="my-app",
)

---

🏗️ Project Structure

tmam/
├── server/           # Node.js/TypeScript backend API
├── web-client/       # Next.js dashboard frontend
├── python-sdk/       # Python auto-instrumentation SDK
├── mongo-init/       # MongoDB initialization scripts
├── nginx/            # Nginx reverse proxy config (production)
└── docker-compose.yml

---

📚 Documentation

Full documentation, SDK reference, and integration guides at docs.tmam.ai

---

🤝 Contributing

Contributions are welcome! Open an issue, submit a pull request, or suggest new integrations. Every star on the repo helps the project grow. ⭐

---

License

MIT — built with ❤️ by the tmam team.