Chronologue uses a standardized response envelope for all API interactions. This design ensures consistency across endpoints, simplifies client handling, and enables integration with language model agents. Each response includes clearly defined fields for success, error, traceability, and metadata. Additionally, Chronologue supports LLM-aware responses for token-efficient summaries and function-call interoperability, including OpenAI-compatible formats.

​
1. Why It Matters

A consistent response schema allows:
  • Developers to reliably parse success and failure outcomes
  • LLMs to consume context-aware memory or planning responses
  • API clients to trace, audit, and retry requests with a known trace_id
  • Calendar integrations to generate .ics files with structured summary and description content

​
2. Core Response Envelope

All Chronologue responses use the following format:
FieldTypeDescription
statusstring"success" or "error"
dataobject/arrayMain payload if the request succeeded
errorstringError name/code (if status = error)
detailstringHuman-readable explanation of error
trace_idstringUnique request ID for auditing/debugging
metaobjectOptional: timing, token usage, version, model info

​
3. Success Response Format

Returned when a request completes successfully. Example: 
  "status": "success",
  "data": [
    {
      "uid": "trace-001",
      "type": "reflection",
      "content": "Evening planning helped me sleep easier.",
      "timestamp": "2025-05-08T22:30:00Z"
    }
  ],
  "trace_id": "req-abc123",
  "meta": {
    "execution_time_ms": 32,
    "token_count": 126
  }
}

​
4. Error Response Format

Returned when validation, authentication, or internal logic fails. Example: 
{
  "status": "error",
  "error": "InvalidTempoToken",
  "detail": "The tempo_token 'Morning@Night' is not recognized.",
  "status_code": 400,
  "trace_id": "req-def456",
  "hint": "Use a defined tempo tag like <tempo:MondayMorning>."
}

​
5. LLM-Aware Responses

To support LLM function calls and prompt injection, Chronologue formats summary and description fields using OpenAI-compatible language:
FieldDescription
summaryShort, token-efficient title derived from content or task label
descriptionRich context block including content, chat_url, agent/source note
These fields are generated using either:
  • Rule-based logic
  • OpenAI function call (e.g., summarize_trace, describe_event)
  • User-editable overrides via interface or patch request
Example for .ics generation: SUMMARY:Deep Work Block
DESCRIPTION:Wrote CUDA kernels from 9–11am.
Chat log: https://chat.openai.com/share/example-id

​
6. Example Endpoint Responses

​
Memory Pull

GET /memory/pull 
{
  "status": "success",
  "data": [
    {
      "uid": "obs-001",
      "type": "observation",
      "content": "Worked on CUDA kernels.",
      "timestamp": "2025-05-12T10:00:00Z"
    }
  ],
  "trace_id": "req-x123",
  "meta": {
    "source": "planner_agent"
  }
}

​
Function Call (via LLM or client)

POST /functions/call 
  "name": "schedule_task",
  "arguments": {
    "content": "Call Mom",
    "scheduled_for": "2025-05-12T10:00:00Z",
    "duration_minutes": 30
  }
}
Response: 
{
  "status": "success",
  "data": {
    "uid": "evt-222",
    "type": "calendar_event",
    "scheduled_for": "2025-05-12T10:00:00Z",
    "summary": "Call Mom",
    "description": "Scheduled via agent. Chat log: https://chat.openai.com/share/example"
  },
  "trace_id": "req-y789",
  "meta": {
    "model": "gpt-4-1106-preview"
  }
}

​
7. Traceability and Logging

All responses include a trace_id field which can be logged by:
  • Frontend clients (for debugging or support)
  • Backend logs (FastAPI logger)
  • Audit trails in MemPort
Use trace_id to correlate between agent outputs, feedback loops, and execution latency.

​
8. Future Enhancements

  • warnings[]: for soft schema mismatches, unsafe tempo tokens
  • stream: true: for SSE or WebSocket responses from agents
  • actions[]: suggested next functions or trace-level prompts
  • cached: true|false: mark responses from Redis or MemPort cache

​
9. Best Practices

  • Always parse status before accessing data
  • Log trace_id on both success and error
  • Use summary for .ics calendar event titles
  • Use description for rich trace exports or downstream LLM use
  • Keep all time fields in UTC ISO format