Documents

What a document is to Otis, how it relates to tasks and sessions, and what Otis works out about each one.

A document is the lasting thing a user works in, such as a project, a file, a workspace or a design. Your app names it by sending a document ID with its telemetry. Otis uses that ID to follow one piece of work across sessions and users.

For each document, Otis works out a name, a kind and a one-sentence purpose. This page explains where each of those comes from, and how a document differs from an artifact.

Purpose of documents

A session ends when the user leaves, and a task ends when the user moves on. The thing being worked on often outlasts both. A user may come back to the same project for weeks, and several users may work on it. The document ID ties that activity together, so that Otis can describe what a document is for and how work on it goes over time.

Document identity

Your app sets a document ID on the telemetry for work that belongs to a document. Context describes how to set it. Otis has no default: a span has a document only if your app gave it one.

Three properties of the ID are worth knowing:

It is stored as you send it. Otis hashes user and session IDs. It doesn't hash a document ID, and it doesn't scan one for personal data. Send an opaque ID, and keep names and email addresses out of it.
It is independent of the session and the user. One document can appear in many sessions and be worked on by several users, and one session can touch several documents.
A task has one document. A task takes the document of its first span. If the user moves to another document partway through a task, the task keeps the first one.

The document record

Otis builds a record for a document once the document has been idle for 30 minutes and contains at least one message from a user. A document that is touched only by other kinds of activity gets no record.

Name. Otis takes the name from your rename events. By default it reads a custom event named chat.rename that carries the new name in a chat.new_name property.
Kind. The kind of document, such as a landing page or a report. Otis takes it from the type your app declares for the document. If your app declares none, Otis infers the kind from the types on the document's artifact events, and then from the document's name. If none of these gives an answer, the kind is left empty.
Purpose. One sentence that states what the user is trying to accomplish with the document, with a confidence between 0 and 1. An AI model writes it from the document's early messages, its names, its artifact events and its declared type. Intent covers this in more detail.
Cluster. Otis groups documents with similar purposes once a day, and assigns each document to a group when it is a close match.

Otis writes the record again when the document is renamed, when its declared type changes, or when an artifact event of a new type arrives. New messages alone don't cause a rewrite, so the purpose reflects how the document started and may not reflect later work.

Otis keeps a document's record for 365 days.

Document properties

Your app can attach properties to a document with setDocumentProperties. The type property sets the document's kind. Otis stores the other properties, and you can ask about them in chat.

Documents and artifacts

Otis uses two identifiers that are easy to confuse.

A document is the place where work happens. It is named by the document ID.
An artifact is one thing the user produces, such as a draft, an export or a generated page. Your app reports each stage in its life, such as created, shared or discarded, with sendArtifactEvent(). It is named by an artifact ID.

The two IDs are separate. Stages and funnels follow the artifact ID, and Otis hashes an artifact ID where it stores a document ID as sent. Otis connects an artifact to a document only when a span carries both IDs, so set the document ID on the telemetry around your artifact events if you want the two linked.

Documents in Otis

Otis uses documents in two places:

Session narratives. When Otis writes up a session, it can refer to the documents the user worked on by name and kind.
Chat. You can ask Otis about documents, such as which kinds of document users create most or what a given document is for.

Intent covers how Otis writes a document's purpose, alongside the intent of tasks and users.
Funnels and artifacts covers artifact stages and the funnels built from them.
Identity covers setDocumentProperties and how a document's type and name are set.