Query: Powering Tally’s Agentic Applications

The final layer of the Tally architecture enables applications to query and reason over the connected dataset. Tally’s LCG serves as the semantic intelligence layer for all downstream workflows.

To query this network, we utilize Graph RAG, which bypasses the limitations of standard vector embeddings or BM25 keyword search. Rather than retrieving isolated documents based on text similarity, our querying agent performs deterministic graph traversal. It follows explicit edges, hopping from a Party node to a Shipment node, assessing Charge nodes, and validating against Document nodes. This multi-hop traversal allows the system to synthesize precise answers to complex supply chain queries that would break traditional search architectures.

Graph RAG: Natural Language Queries

Graph RAG, is a retrieval architecture where an AI agent dynamically generates and executes Cypher queries against the LCG in response to natural language inputs. Rather than retrieving documents by text similarity, the agent traverses explicit graph edges — following relationships from a Shipment node through its Charge nodes, validating against source Document nodes — to synthesize precise, provenance-backed answers. Because the agent introspects the schema at query time, it adapts to new entity types and relationships without retraining.

The agent is equipped with tools to:

Tool	Purpose
Schema discovery	Understand the graph's current shape — entity types, relationships, and properties — so queries are always accurate
Graph query	Execute structured queries with automatic tenant scoping and safety validation
Identifier search	Fuzzy search across all reference numbers (tracking numbers, BOLs, POs)
Party search	Fuzzy search across company names to resolve informal references

The schema is introspected dynamically, so as your data evolves, the agent's understanding evolves with it.

REST API

The system exposes a structured API for direct access, some examples:

Endpoint	What You Get
GET /graph/shipments	Paginated shipment list with filters like status, mode, date range, origin, destination, carrier, and customer
GET /graph/shipments/:shipmentId	Complete shipment detail: identifiers, parties, route legs, cargo, charges, milestones, related documents, and linked communications
GET /graph/shipments/:shipmentId/timeline	Shipment timeline combining estimated, planned, and actual milestone events
GET /graph/shipments/:shipmentId/evidence	Provenance graph showing where each fact came from: email, attachment, document, or upstream system record

Each endpoint exposes the following search parameters:

Search Parameter	Purpose
q	Free-text query such as a bill of lading number, company name, container number, invoice number, or phrase from an email
types	Restrict search to entity classes like shipment, identifier, party, document, or email
filters	Narrow results by tenant-safe dimensions such as date range, shipment mode, customer, carrier, status, or source system
limit / cursor	Paginate results for UI workflows and agent tooling
includeEvidence=true	Return snippets, matched fields, and provenance so users can see why a result matched