swarmtrace

finally live on vercel but still in deployment you can check it guys go on swarmtrace.vercel.app

dev vlog #4
builders just finished the backend work for today / rest work tomorrow i will make the frontend connected to clerk for auth and neon for database . byee👍

dev vlog 3”What’s up, builders! Today we are fundamentally changing how SwarmTrace works. We’re tearing out the local SQLite restrictions and turning this project into a distributed, multi-tenant AI agent monitoring platform. The goal? Anyone can install our package, drop in an API key, and instantly view their agent’s execution traces on a sleek, hosted Next.js dashboard powered by Clerk and Supabase—without hosting a single thing themselves.”

What We’re Solving Today:
The “Localhost” Trap: Right now, the FastAPI backend expects to live on the same machine as the SQLite database. If a user runs an agent on their machine, they can’t easily see it on a globally hosted dashboard.

Multi-Tenancy: We need to make sure User A never sees User B’s logs. Every single trace must be bound to an organization or user ID.

Zero-Infra for the User: The developer using tracely should only have to pip-install it, provide a SWARMTRACE_API_KEY, and let our remote backend handle the rest.

📐 The SaaS Architecture Blueprint
Here is how data will flow across the internet from your user’s local python script straight to your Vercel-hosted frontend dashboard:

[ User’s Local Machine ]
└── Running AI Agent (LangChain/CrewAI/AutoGen)
└── Tracely SDK (Decorators)
│
▼ (Async Background HTTP POST /ingest)
[ Vercel Serverless / API Gateway ] ─── (Validates SWARMTRACE_API_KEY)
│
▼ (Writes Log Payload)
[ Hosted Database: Supabase / Postgres ]
└── traces table (Schema: id, user_id, execution_time, trace_payload)
▲
│ (Fetches user-specific traces via Clerk JWT auth)
[ Vercel Frontend: Next.js + Clerk ]
└── Protected Dashboard View (Only shows rows matching user_id)
🗂️ The Technical Roadmap
To pull this off, we have to transform four key elements of your repository:

1. The SDK (tracely/scraper.py & tracer.py)
   Current: Writes to a local SQLite database via storage.py.

SaaS Modification: Introduce a background background-worker thread or async pool. When a trace finishes, it sends an HTTP POST request to https://api.swarmtrace.dev/v1/ingest carrying the payload and an Authorization: Bearer st_live_… header.

1. The Backend Engine (api.py)
   Current: Reads from local SQLite.

SaaS Modification: Drop SQLite. Migrate to a hosted Postgres instance (Supabase is perfect here).

Add an /ingest route for incoming agent metrics.

Add middleware to validate incoming user requests from the frontend using Clerk JWT tokens.

1. The Authentication Layer (Clerk)
   Wrap your frontend-next/ layout inside a .

Set up a pipeline where a user logs in, generates an “Agent API Key” from their settings dashboard, and pastes that key into their Python .env file.
also tracely is maded by me it is the part of swarm trace.

🐝 SwarmTrace DevLog #3 — Wiring the Dashboard to Real Data
June 6, 2026
///////////////////////////////////////////////////////
Today was all plumbing. No new features, no design work — just making the two halves of this project actually talk to each other.
///////////////////////////////////////////////////////
Where Things Stood
I had two things running independently.
On one side, the FastAPI server — started it up this morning, it boots clean, the @observe decorator has been collecting real traces into SQLite every time an agent function runs. The data is there. It’s been there.
On the other side, the dashboard UI — five pages, looks exactly like the design mockups, dark theme, all the charts and tables and drawers. Finished that yesterday.
The problem is they had never spoken to each other. The UI was showing hardcoded numbers I typed in by hand. The API was sitting there with real data and nothing asking for it.

The Work
Spent today closing that gap.
First thing I did was map out what each page actually needs from the backend. Overview needs health stats and an activity feed. Traces needs the full call list. Agents needs a registry of everything that’s been observed. Metrics needs cost and token breakdowns. Settings needs API key management and integration status.
Then I went into the API and built those endpoints out one by one. The good news — all the underlying data was already in the database from the decorator. I wasn’t inventing anything, just exposing it in the right shape.
The annoying part was that the frontend and backend had grown slightly different vocabularies. The UI expected fields named one way, the API had them named another. Duration in milliseconds vs latency in seconds. function_name vs function. Small things, but they all had to be aligned or every fetch would silently return nothing.
CORS was the other thing that caught me — frontend on one port, backend on another, browser refuses to talk between them without the right middleware. Quick fix once I remembered that’s what was happening.

The Moment it Clicked
Started both servers. Opened the dashboard. Traces page loaded with real function names — execute_task, plan_steps, fetch_data — things I’d actually run this week. Real latencies. Real token counts. Real errors with the actual error messages.
Turned on Live Mode. Ran an agent task in a separate terminal. Watched the row appear in the table a couple seconds later.
That’s the thing you build toward.

What’s Still Hardcoded
A few things I haven’t gotten to yet. The Overview stat cards are still static numbers — need to write proper aggregation logic for those. The per-agent token sparklines are placeholder data because I’m storing traces, not time-bucketed token history per agent. Something to fix this week.

Tomorrow
Get the Overview cards pulling from real DB aggregations. Then figure out deployment — right now this whole thing requires running two local servers which isn’t great for a demo. Want a single public URL before the submission deadline.
///////////////////////////////////////////////////////
SwarmTrace — open-source observability for multi-agent AI systems. Built for AMD Hackathon 2026.

🐝 SwarmTrace — Developer Log 1
Project: SwarmTrace
Version: 0.1.7
Built for: AMD Hackathon
Author: Ravi Kumar

What is it?
SwarmTrace is a tracing and observability library for LLM-based multi-agent systems — essentially “pytest for AI agents.” The core idea: AI swarms are unpredictable, and existing tools give you no visibility into what happened, where it broke, or whether a prompt change caused a regression. SwarmTrace fixes that.

What it does
Tracing — wrap any Python function (sync or async) with @observe and every call is automatically recorded: inputs, outputs, latency, token usage, cost, errors, and parent–child relationships between nested agent calls.
Token Budget — the @budget decorator tracks cumulative token usage across calls and warns you (or hard-stops) before an agent blows past its limit.
Regression Detection — the compare() function runs two prompt versions against the same inputs and uses an LLM to score output similarity, flagging regressions automatically.
Tool Attention (ISO Scoring) — implements the technique from arXiv:2604.21816. Instead of injecting all tool schemas into every prompt, it uses FAISS + sentence embeddings to select only the top-k relevant tools per query — reducing tool token overhead by up to 95%.
Web Scraping Traces — scraper.scrape(url) wraps Scrapling with full trace recording so scrape calls show up in the call tree like any other agent action.
CLI — swarmtrace prints a rich call tree with costs and statuses. swarmtrace-replay replays any individual trace. swarmtrace-export dumps everything to JSON or CSV.

Frontend Dashboard
A React + TanStack Router frontend visualises live traces from the FastAPI backend:

Stat bar — total traces, cumulative tokens, total cost, error count at a glance
Call Tree — hierarchical view of parent→child agent calls for a full run
Waterfall — timeline view showing which agents ran in parallel vs sequentially
Token Chart — per-trace token usage over time
Failures page — isolated view of every errored trace with its call chain and error message
Detail Drawer — click any trace to inspect its full args, output, latency, and lineage
Live Mode — polls the backend every 2 seconds for real-time trace updates

Storage
All traces land in a local SQLite database (~/.tracely.db) with WAL mode enabled. Auto-purges oldest rows beyond 10,000 to stay bounded. Indexed on timestamp for fast ordered reads. Export to JSON/CSV available via CLI.

Stack
LayerTechnologyCore libraryPython 3.8+, SQLite, contextvarsRegression LLMClaude Haiku via litaiTool selectionFAISS + sentence-transformersAPIFastAPI + PydanticFrontendReact, TanStack Router/Start, Tailwind, RechartsCLI displayrichPackagingsetuptools, pip-installable

Key design decisions
contextvars for parent tracking — parent IDs propagate automatically through async and threaded code without any manual wiring. Nested @observe calls build the tree on their own.
SQLite over a hosted DB — zero setup for the user; works offline; the auto-purge keeps it from growing unboundedly.
Graceful degradation everywhere — if sentence-transformers/FAISS aren’t installed, Tool Attention falls back to returning the first k tools. If tiktoken isn’t installed, budget tracking falls back to len // 4. Storage errors never crash the agent being traced.

Current limitations

Failures page still uses static demo data instead of the live API
swarm_module_0–4.py are five identical placeholder files (to be collapsed into one)
No authentication on the API (development only)
pyproject.toml is incomplete; setup.py not yet migrated.
i have to complete ui first now then i will do other api work because it will be connected to ui because it was originally built a python frame work.byee