How to Build Apps for VaultSafe

Sat, 08 Mar 2025 00:00:00 +0000

How to Build Apps for VaultSafe

VaultSafe’s app ecosystem lets you build applications that run on document metadata—extracting birthdays, invoices, deadlines, or any structured data—and present it through configurable widgets. No code in the repo. All app definitions live in the cloud. Here’s how it works and how to create your first app.

The Pipeline

User uploads a file → VaultSafe’s AI analyzes it (document type, description, entities, key-value content).
Your app’s agent prompt runs on that metadata → extracts structured data (e.g. birthdays, due dates).
Data is stored per user, per app.
A widget renders the data (list, table, or card view).

Critical: Apps never see raw files. They only receive pre-extracted metadata. This keeps the system secure and fast.

Three Pieces of an App

1. Schema

Define what your app extracts. Example (Birthdays):

{
 "extraction": {
 "birthdays": [
 { "person_name": "string", "date": "string", "source": "string", "file_id": "string" }
 ]
 }
}

2. Agent Prompt

Instructions for the LLM. The input is JSON: suggested_file_name, type_of_file, description, main_person, other_persons, full_content, file_id.

Birthday example:

You extract birthday-related information from document metadata. Only use information explicitly present in the input; do not infer or guess.

Input is a JSON object with: suggested_file_name, type_of_file, description, main_person, other_persons, full_content (key-value from document).

Return a JSON object with:

“birthdays”: list of { “person_name”: string, “date”: string (YYYY-MM-DD or partial like “15 March”), “source”: string, “file_id”: string }

If no birthday is explicitly present, return { “birthdays”: [] }. Do not fabricate dates.

How to display the data:

Field	Example
type	`list_by_date`, `table`, or `card`
list_key	`birthdays` (key in extracted JSON)
sort_field	`date`
display_fields	`["person_name", "date", "source"]`
title	“Birthdays”
empty_message	“No birthdays extracted yet. Upload documents…”

App Status: Enable for All vs. Marketplace

When you publish an app, you choose:

Enable for all — Automatically enabled for every user. Good for core features (e.g. Birthdays).
Enabled by user — App appears in the marketplace. Users browse and enable it themselves.

Users can disable any app at any time.

Generic Widgets

Type	Use case
list_by_date	Sorted list, ideal for dates (birthdays, deadlines)
table	Tabular view, rows = items, columns = display_fields
card	Card layout, one card per item

More widget types (tree, timeline, etc.) can be added over time.

Publishing

Use the VaultSafe Admin app (local only, never deployed).
Create a new app with app_id, name, developer, agent_prompt, schema, widget.
Set status: enable_for_all or enabled_by_user.
Save. If enable_for_all, a backfill runs to add the app for all users.

User Data & RAG

Extracted data is stored in user_app (user_id + app_id + data).
Users can update or delete items in the Apps UI.
App data is also embedded and stored in pgvector for LLM chat context. On update/delete, those chunks are kept in sync.

Full Example: Birthdays App

{
 "app_id": "birthday",
 "name": "Birthdays",
 "developer": "vaultsafe",
 "cost": 0,
 "price_display": "Free",
 "status": "enable_for_all",
 "agent_prompt": "...",
 "schema": { "extraction": { "birthdays": [...] } },
 "widget": {
 "type": "list_by_date",
 "list_key": "birthdays",
 "sort_field": "date",
 "display_fields": ["person_name", "date", "source"],
 "title": "Birthdays",
 "empty_message": "No birthdays extracted yet."
 }
}

Next Steps

Read the for full specs.
Check for the ecosystem overview.
Contact for the developer program.

Developer | VaultSafe | Chat with Your Files — AI Document Assistant

How to Build Apps for VaultSafe

How to Build Apps for VaultSafe

The Pipeline

Three Pieces of an App

1. Schema

2. Agent Prompt

3. Widget Config

App Status: Enable for All vs. Marketplace

Generic Widgets

Publishing

User Data & RAG

Full Example: Birthdays App

Next Steps