---
title: Kaal API Backend
emoji: π°οΈ
colorFrom: red
colorTo: gray
sdk: docker
pinned: false
---
π°οΈ KAAL
Temporal AI Agent Ecosystem β Letters to the Future, for agents.
Give any AI agent structured, temporal long-term memory.
Kaal decomposes text into Subject-Verb-Object events, stores them across dual calendars,
and lets agents query what happened, when, and why β across any connected SaaS tool.
---
## Table of Contents
- [What is Smriti?](#what-is-smriti)
- [Architecture & Deployments](#architecture--deployments)
- [Quick Start (5 Minutes)](#quick-start-5-minutes)
- [API Reference](#api-reference)
- [Dashboard Guide](#dashboard-guide)
- [Agent System](#agent-system)
- [Pricing Tiers](#pricing-tiers)
- [Configuration](#configuration)
- [Troubleshooting](#troubleshooting)
---
## Architecture & Deployments
To maximize performance while keeping the service accessible, this project uses a **decoupled, dual-deployment architecture**:
1. **Frontend Dashboard (Vercel)**: `https://smriti-kaal.vercel.app`
* Provides the blazing-fast Next.js web interface, API key generation, and visual memory management.
2. **Backend API (Hugging Face Spaces)**: `https://spy9191-chronos-api-backend.hf.space`
* Houses the heavy FastAPI inference engine, memory vector database, and LangGraph agent pipelines.
**Note for developers:** When you generate an API key on the Vercel site, you use that key to authenticate your backend requests directly to the Hugging Face API base URL. They are the same system working in tandem.
---
## What is Smriti?
**The problem:** AI agents are goldfish. They process a request, forget everything, and start from zero next time. No memory of what happened yesterday, last week, or across your other tools.
**The solution:** KAAL is a **temporal memory API** that any AI agent or SaaS product can plug into. It:
1. **Ingests** text from any source (CRM, chat, email, code commits...)
2. **Decomposes** it into structured Subject-Verb-Object events using AI (Llama 3.1 8B via Groq)
3. **Stores** events in dual calendars β Postgres for temporal queries, pgvector for semantic search
4. **Retrieves** relevant memories via natural language β "What happened with Acme Corp last quarter?"
5. **Powers** agents that actually remember β an AI that knows *your* history
### Real Example
```
INPUT: "Acme Corp signed a $50,000 contract for Q2 2026"
CHRONOS EXTRACTS:
Subject: Acme Corp
Verb: signed
Object: a $50,000 contract for Q2 2026
When: Q2 2026
LATER, ANY AGENT CAN ASK:
"What happened with contracts?"
β [2026-04-12] Acme Corp signed a $50,000 contract for Q2 2026
```
---
## Architecture
```
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β KAAL v0.1.0 β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β
β βββββββββββββββ ββββββββββββββββ ββββββββββββββββββββββ β
β β POST /ingestβ β POST /query β β POST /agent/run β β
β β Raw text β β β NL search β β β Prompt β Memory β β
β β SVO events β β Hybrid rank β β β LLM β Response β β
β ββββββββ¬βββββββ ββββββββ¬ββββββββ βββββββββββ¬βββββββββββ β
β β β β β
β ββββββββΌβββββββββββββββββΌββββββββββββββββββββββΌβββββββββββ β
β β π§ Memory Core β β
β β ββββββββββββββββββββ ββββββββββββββββββββββββββββ β β
β β β Event Calendar β β Embedding Index β β β
β β β (PostgreSQL) β β (pgvector) β β β
β β β β’ SVO tuples β β β’ Semantic vectors β β β
β β β β’ Timestamps β β β’ Cosine similarity β β β
β β β β’ Turn history β β β’ Fast pgvector scan β β β
β β ββββββββββββββββββββ ββββββββββββββββββββββββββββ β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
β ββββββββββββββββ ββββββββββββββββ ββββββββββββββββββββββ β
β β SVO Parser β β Auth + Tiers β β Razorpay Billing β β
β β GPT 120B β β API keys β β Explorer/Builder/ β β
β β + Llama 3.1 β β SHA-256 hash β β Scale β β
β ββββββββββββββββ ββββββββββββββββ ββββββββββββββββββββββ β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
### File Structure
```
chronos-hub/
βββ chronos_core/ π§ Memory Core
β βββ models.py Pydantic models, tier config, pricing
β βββ svo_parser.py AI event extraction (Groq / Llama 3.1)
β βββ memory_store.py PostgreSQL dual calendars (events + turns)
β βββ vector_store.py pgvector semantic search (sentence-transformers)
β
βββ api/ π FastAPI Gateway
β βββ main.py App entry, CORS, lifespan
β βββ auth.py API key auth, tier quota enforcement
β βββ deps.py Dependency injection (singletons)
β βββ routes/
β βββ ingest.py POST /ingest β feed events
β βββ query.py POST /query β search memory
β βββ connectors.py POST /connect β register SaaS tools
β βββ agent.py POST /agent/run β chat with memory
β βββ billing.py Razorpay checkout, usage, key generation
β
βββ agent/ π€ LangGraph Agent Runner
β βββ graph.py State graph: memory β model β response
β βββ nodes.py Processing nodes (retrieve, call LLM)
β βββ tools.py Built-in tools for agents
β
βββ chronos-ui/ π Next.js Web Dashboard
β βββ src/app Full app UI (navy+gold Chronos design)
β
βββ .env Environment variables (your keys)
βββ .env.example Template
βββ requirements.txt Python dependencies
βββ test_quick.py Integration test script
```
---
## Quick Start (5 Minutes)
### Prerequisites
- Python 3.11+
- A free Groq API key from [console.groq.com](https://console.groq.com)
### Step 1 β Install
```bash
cd chronos-hub
pip install -r requirements.txt
```
### Step 2 β Configure
```bash
# Copy the template
cp .env.example .env
# Edit .env and add your Groq key:
# GROQ_API_KEY=gsk_your_key_here
```
### Step 3 β Start the API
```bash
python -m uvicorn api.main:app --port 8000
```
You should see:
```
β
KAAL ready β all systems online
Uvicorn running on http://127.0.0.1:8000
```
### Step 4 β Start the Dashboard
```bash
# In a second terminal:
cd chronos-ui
npm install
npm run dev
```
Open **http://localhost:3000** in your browser.
### Step 5 β Test It
```bash
python test_quick.py
```
Expected output:
```
=== GENERATING API KEY ===
Key: chrn_abc123...
=== INGESTING EVENTS ===
Ingested: 4 events
SVO tuples found: 4
=== QUERYING MEMORY ===
Found: 4 results in ~80ms
=== ALL TESTS PASSED ===
```
---
## API Reference
**Base URL:** `https://spy9191-chronos-api-backend.hf.space`
**Auth:** Include your API key in the `Authorization: Bearer ` header.
**Docs:** Open `https://spy9191-chronos-api-backend.hf.space/docs` for interactive Swagger UI.
---
### `POST /billing/keys` β Generate API Key
No auth required. Creates a new API key.
```bash
curl -X POST "https://spy9191-chronos-api-backend.hf.space/billing/keys?tier=explorer"
```
**Response:**
```json
{
"api_key": "chrn_abc123...",
"source_id": "src_7277b1709a854375",
"tier": "explorer",
"message": "β οΈ Save this API key now β it cannot be retrieved later."
}
```
---
### `POST /ingest` β Feed Events
Send raw text; the AI extracts structured SVO events automatically.
```bash
curl -X POST https://spy9191-chronos-api-backend.hf.space/ingest \
-H "X-API-Key: chrn_your_key" \
-H "Content-Type: application/json" \
-d '{
"source_id": "my-crm",
"events": [
{"text": "Acme Corp signed a $50,000 contract for Q2 2026"},
{"text": "Jane was promoted to VP of Engineering on March 15"},
{"text": "Server migration completed from AWS to Railway on April 1"}
],
"parse_svo": true
}'
```
**Response:**
```json
{
"ingested_count": 3,
"event_ids": ["abc123", "def456", "ghi789"],
"svo_tuples": [
{
"subject": "Acme Corp",
"verb": "signed",
"object": "a $50,000 contract for Q2 2026",
"confidence": 0.95
}
],
"turn_ids": ["turn_1", "turn_2", "turn_3"]
}
```
**Parameters:**
| Field | Type | Required | Description |
|---|---|---|---|
| `source_id` | string | β
| Identifies the data source |
| `events` | array | β
| List of `{text, timestamp?, metadata?}` objects |
| `parse_svo` | bool | No | Enable AI extraction (default: `true`) |
---
### `POST /query` β Search Memory
Natural language search with optional time filtering.
```bash
curl -X POST https://spy9191-chronos-api-backend.hf.space/query \
-H "X-API-Key: chrn_your_key" \
-H "Content-Type: application/json" \
-d '{
"query": "What happened with contracts?",
"max_results": 10
}'
```
**Response:**
```json
{
"results": [
{
"event": {
"subject": "Acme Corp",
"verb": "signed",
"object": "a $50,000 contract for Q2 2026",
"timestamp": "2026-04-12T18:28:17Z"
},
"relevance_score": 0.92,
"provenance": "semantic"
}
],
"total_found": 1,
"query_time_ms": 80.0
}
```
**Parameters:**
| Field | Type | Required | Description |
|---|---|---|---|
| `query` | string | β
| Natural language question |
| `time_range` | object | No | `{start, end}` ISO datetimes |
| `source_ids` | array | No | Filter by specific sources |
| `max_results` | int | No | 1β100 (default: 20) |
| `semantic_weight` | float | No | 0.0β1.0 (default: 0.5) |
---
### `POST /agent/run` β Chat with Agent
Conversational AI with full temporal memory access.
```bash
curl -X POST https://spy9191-chronos-api-backend.hf.space/agent/run \
-H "X-API-Key: chrn_your_key" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Summarize everything that happened recently",
"thread_id": null
}'
```
**Response:**
```json
{
"thread_id": "thread_abc123",
"response": "Based on your temporal memory, here's what happened recently...",
"events_retrieved": 4,
"events_created": 0
}
```
---
### `POST /connect` β Register a SaaS Tool
```bash
curl -X POST https://spy9191-chronos-api-backend.hf.space/connect \
-H "X-API-Key: chrn_your_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Stripe",
"description": "Payment processing",
"base_url": "https://api.stripe.com",
"auth_header": "Authorization",
"endpoints": [
{"method": "GET", "path": "/v1/invoices", "description": "List invoices"}
]
}'
```
---
### `GET /billing/usage` β Check Usage
```bash
curl https://spy9191-chronos-api-backend.hf.space/billing/usage \
-H "X-API-Key: chrn_your_key"
```
---
### `GET /health` β Health Check
```bash
curl https://spy9191-chronos-api-backend.hf.space/health
```
```json
{
"status": "healthy",
"stores": {"postgres_events": 4, "pgvector_embeddings": 4}
}
```
---
## Dashboard Guide
The dashboard runs at **http://localhost:3000** and provides a visual interface for all Chronos features.
| Page | What It Does |
|---|---|
| π **Overview** | System health, event count, embedding count, AI status |
| π₯ **Ingest Events** | Write events in plain English β AI extracts SVO tuples |
| π **Query Memory** | Natural language search with date filters and relevance |
| π€ **Agent Chat** | Conversational AI that reasons with your temporal memory |
| π **Connect Tool** | Register any SaaS API for agent discovery |
| π **Usage & Billing** | Tier badge, usage meters, pricing table |
| π **API Keys** | Generate new keys with one click |
### How to Use the Dashboard
1. Open **http://localhost:3000**
2. Click **π API Keys** β Click **Generate Key** β Copy the key
3. Paste the key into the **π API Key** field in the sidebar
4. Go to **π₯ Ingest Events** β Type events β Click **Ingest Into Memory**
5. Go to **π Query Memory** β Ask a question β See results
6. Go to **π€ Agent Chat** β Have a conversation with memory-aware AI
---
## Agent System
Chronos includes a **LangGraph-based agent** that automatically:
1. **Retrieves** relevant memories from ChromaDB before responding
2. **Injects** temporal context into the LLM's system prompt
3. **Responds** with awareness of past events, dates, and relationships
### How It Works
```
User: "What's our biggest contract?"
β
βΌ
βββββββββββββββββββββββ
β retrieve_memory_node β β Searches pgvector + Postgres
β ("contract" β Acme) β for relevant past events
ββββββββββ¬βββββββββββββ
β
βΌ
βββββββββββββββββββββββ
β call_model_node β β GPT 120B
β System prompt + β with memory context injected
β memory context + β
β user question β
ββββββββββ¬βββββββββββββ
β
βΌ
"Based on your records, Acme Corp signed a $50K contract for Q2 2026."
```
### AI Model
| Property | Value |
|---|---|
| **Model** | GPT OSS 120B (Agent) + Llama 3.1 8B (Parsing) |
| **Provider** | Zhipu AI & Groq |
| **Speed** | 2,100+ tokens/second |
| **Daily Limit** | 1,000,000 requests/day |
| **Cost** | Free |
---
## Pricing Tiers
KAAL uses a three-tier model with metered overage:
| Feature | Explorer | Builder | Scale |
|---|---|---|---|
| **Price** | Free | $49/month | $249/month |
| **Events/month** | 10,000 | 500,000 | 5,000,000 |
| **Orchestration calls** | 100 | 10,000 | Unlimited |
| **Connected tools** | 3 | 25 | Unlimited |
| **Data retention** | 30 days | 1 year | Unlimited |
| **Agent threads** | 5 | 100 | Unlimited |
| **Event overage (per 1K)** | Hard cap | $0.05 | $0.03 |
| **Orchestration overage** | Hard cap | $0.10 | $0.07 |
| **Support** | Community | Priority email | Dedicated Slack |
---
## Configuration
### Environment Variables
| Variable | Required | Description |
|---|---|---|
| `GROQ_API_KEY` | β
| Free API key from [console.groq.com](https://console.groq.com) |
| `CHRONOS_DB_URL` | No | Postgres DB URL |
| `PGVECTOR_DB_URL` | No | Postgres DB URL for pgvector |
| `API_SECRET_KEY` | No | Secret for signing API keys |
| `RAZORPAY_KEY_ID` | No | Razorpay key ID for billing |
| `RAZORPAY_KEY_SECRET` | No | Razorpay secret key |
| `RAZORPAY_PLAN_BUILDER` | No | Razorpay plan ID for Builder tier |
| `RAZORPAY_PLAN_SCALE` | No | Razorpay plan ID for Scale tier |
| `CHRONOS_API_URL` | No | API URL for dashboard (default: `http://localhost:8000`) |
### Tech Stack
| Component | Technology |
|---|---|
| **API Framework** | FastAPI + Uvicorn |
| **Structured Storage** | Neon PostgreSQL |
| **Vector Search** | PostgreSQL pgvector + sentence-transformers |
| **Embedding Model** | all-MiniLM-L6-v2 (HuggingFace) |
| **LLM** | GPT OSS 120B & Llama 3.1 8B (Cerebras) |
| **Agent Framework** | LangGraph + LangChain |
| **Dashboard** | Next.js + React (Vercel) |
| **Billing** | Razorpay |
| **Auth** | SHA-256 hashed API keys |
---
## Troubleshooting
| Problem | Solution |
|---|---|
| **"Cannot connect to API"** | Make sure the API is running: `python -m uvicorn api.main:app --port 8000` |
| **Dashboard won't load** | Start it: `python -m streamlit run dashboard/app.py --server.port 8501` |
| **"No GROQ_API_KEY set"** | Create `.env` file with `GROQ_API_KEY=gsk_your_key` |
| **"Missing API key" on requests** | Add `X-API-Key: chrn_...` header to all API calls |
| **Query returns 0 results** | Ingest some events first via `POST /ingest` |
| **Slow first startup** | The embedding model (~80MB) downloads once from HuggingFace on first run |
| **Agent gives generic response** | Make sure there are ingested events for the agent to recall |
### Running Both Servers
You need **two terminals** running simultaneously:
**Terminal 1 β API Server:**
```bash
cd chronos-hub
python -m uvicorn api.main:app --port 8000
```
**Terminal 2 β Dashboard:**
```bash
cd chronos-ui
npm run dev
```
---
## Integration Examples
### Python SDK Usage
```python
import httpx
API = "http://localhost:8000"
KEY = "chrn_your_key_here"
HEADERS = {"X-API-Key": KEY}
# Ingest an event
httpx.post(f"{API}/ingest", headers=HEADERS, json={
"source_id": "my-app",
"events": [{"text": "User completed onboarding on April 12"}]
})
# Query memory
result = httpx.post(f"{API}/query", headers=HEADERS, json={
"query": "What did the user do?"
})
print(result.json()["results"]) # β onboarding event
# Chat with agent
response = httpx.post(f"{API}/agent/run", headers=HEADERS, json={
"prompt": "Summarize user activity"
})
print(response.json()["response"])
```
### JavaScript / Node.js
```javascript
const API = "https://spy9191-chronos-api-backend.hf.space";
const headers = { "X-API-Key": "chrn_your_key", "Content-Type": "application/json" };
// Ingest
await fetch(`${API}/ingest`, {
method: "POST", headers,
body: JSON.stringify({
source_id: "my-web-app",
events: [{ text: "Customer upgraded to Pro plan" }]
})
});
// Query
const res = await fetch(`${API}/query`, {
method: "POST", headers,
body: JSON.stringify({ query: "Who upgraded recently?" })
});
console.log(await res.json());
```
---
π°οΈ Curated with continuity in mind.
Β© 2026 Chronos Labs