TokNology

Our front end page
General UI and chatbot
Audit Log and evidence trail

Inspiration

Regulations move faster than most product teams can ship. Every new feature raises the same questions: Does this need region-specific logic? What’s the risk if we miss something? We wanted a small, practical tool that helps an engineer (not a lawyer) get to an initial answer in minutes, with reasoning they can show to a PM or counsel.

What it does

TokNology is a multi-agent orchestrator for compliance triage. You paste a feature description or policy text; the backend fans it out to two lightweight agents:

LawFinder pulls likely obligations and jurisdictional notes (e.g., geolocation, youth safety, data transfer).

Risk Evaluator scores impact × likelihood and explains the score in plain language.

The backend merges the results and the React dashboard presents: obligations by region, a risk level with rationale, and follow-ups to investigate. It’s not a legal opinion—it’s a fast, traceable starting point.

How we built it

Stack. Node/Express backend (port 5050), two Python microservices for the agents (8000 and 18002), and a Vite/React frontend (5173). Everything runs via Docker Compose or with simple npm run dev/uvicorn commands.

Orchestration. The backend accepts /analyze, validates inputs, calls both agents in parallel, and normalizes their outputs into a single schema. We added /healthz, /a1-test, and /a2-test endpoints to keep debugging simple.

Prompting & parsing. Each agent uses a small prompt template and a strict JSON schema. We reject malformed JSON and ask the agent to retry with a shorter, steadier answer.

Long docs. For longer policies, we chunk text, run map-reduce summaries in the agent, and only surface the parts that affected the final recommendation.

UI. The dashboard keeps to three questions: What’s required? What’s the risk? What should I check next? We avoided dense tables in favor of concise bullets and expandable details.

Challenges we ran into

Containers couldn’t see each other. We initially called localhost inside containers (facepalm). Switching to Docker service names + explicit ports fixed networking. We also added simple healthz checks so Compose wouldn’t race the startup.

CORS & preflight. The browser’s OPTIONS request failed until we added an explicit handler and narrowed allowed origins/headers.

Token limits. Long regulations blew up requests; chunking plus “map-reduce” summaries solved it without changing models.

Inconsistent JSON from LLMs. We hardened the contract with JSON schema validation and a single retry path that strips prose.

Merging results. Agents occasionally disagreed. We show both views and label the merge logic so reviewers can see how we combined them.

Accomplishments we’re proud of

An end-to-end demo from paste → obligations/risk → next steps that anyone on the team can run locally.

Operational sanity: health checks, clear logs, and test hooks that make debugging fast under hackathon pressure.

A UI that stays out of the way such that engineers can copy obligations into tickets, PMs get a one-screen summary, and legal can drill into the reasoning if they want.

Low ceremony setup: sensible .env files and Docker Compose for a one-command start.

What we learned

Multi-agent systems are less about “more models” and more about clear contracts between them.

Small DevOps details (ports, health checks, service names) save hours when you’re sleep-deprived.

The difference between a neat demo and a useful tool is explainability: show where a claim came from and what to verify next.

You don’t need a huge model if the prompt, schema, and chunking are disciplined.

What’s next

More agents: content moderation, youth safety, app-store policy checks, and jurisdiction-specific packs.

Production hardening: retries, timeouts, circuit breakers, and a metrics page (latency, error rate, token usage).

Batch mode: CSV upload for multiple features, with exportable results.

Deeper domain packs: finance and healthcare, where obligations are strict and fast triage is valuable.

Closing thought

TokNology won’t replace counsel. It gives teams a fast, defensible first read, so engineers can design responsibly, PMs can plan region-specific work, and legal can spend time on the hard parts instead of copy-pasting the obvious.