# Lisa
Lisa is a persona-driven, LLM-backed Matrix bot for a small, private chat
room on a self-hosted Continuwuity server. The room is unencrypted and its
members are trusted.
## Goals
- Let room members invite Lisa into an existing conversation by mentioning
her and continue the conversation by replying to her.
- Give Lisa enough recent conversation context to respond naturally.
- Give Lisa a consistent, operator-defined persona.
- Let Lisa search the web and read web pages when outside information would
improve her response.
- Keep Lisa simple to operate on a self-hosted system.
## Non-goals
- Supporting encrypted Matrix rooms.
- Responding to messages that neither mention Lisa nor reply to her.
- Moderating rooms or enforcing room policy.
- Acting on behalf of users outside the room.
- Supporting arbitrary code execution or filesystem access as LLM tools.
- Providing a general-purpose interface for installing tools at runtime.
## User journey
A typical interaction looks like this:
```text
Human A: bla bla
Human B: bla bla bla
Human C: @Lisa What do you think?
Lisa: I looked up information about blabla. It turns out that blablabla.
Human A, replying to Lisa: Does that also apply to foobar?
Lisa: It does, but only when quux is enabled.
```
Lisa receives relevant recent messages as context, recognizes that Human C
mentioned her, decides whether web research is useful, and replies in the
room using her configured persona.
## Functional requirements
### Matrix interaction
- Lisa must connect to a configured Continuwuity server as a dedicated
Matrix user.
- Lisa must operate only in configured rooms.
- Lisa must respond to new text messages that explicitly mention her.
- Lisa must also respond to new text messages that reply to one of her
messages, even when the reply does not explicitly mention her.
- Lisa must ignore her own messages.
- Lisa must not treat reactions, redactions, membership events, or other
non-message events as invocations.
- Lisa must not respond to old messages encountered while starting or
reconnecting.
- Lisa must not treat a message edit as a new invocation.
- Lisa must not produce duplicate responses for the same invocation.
- Lisa's response must be sent as a reply to the invoking message.
- Lisa should indicate that she is typing while preparing a response.
- Lisa must preserve ordinary Matrix text formatting in received context when
it affects meaning.
- Lisa's outgoing messages must render correctly in Matrix clients and may
contain paragraphs, lists, code blocks, and links.
### Conversation context
- Lisa must receive recent conversation from the room before the invocation,
not just the invoking message.
- Context must identify the author of each message.
- Context must preserve reply relationships when they are relevant to
understanding the conversation.
- Context must include Lisa's recent messages when they are part of the
conversation.
- The amount of context supplied to the LLM must be bounded and configurable.
- Conversations from different rooms must never be mixed.
- Concurrent invocations must not cause one invocation's messages or tool
results to appear in another invocation's context.
- Long-term memory across unrelated conversations is out of scope.
### Persona
- Lisa must use an operator-provided persona definition.
- The persona definition must be configurable without changing program code.
- Lisa must apply the persona consistently to normal responses, researched
responses, clarification requests, and user-visible errors.
- The persona must not grant Lisa capabilities that are not provided by the
bot.
- Lisa must not claim to have used a tool when she did not successfully use
it.
### LLM
- Lisa must use the operator's existing self-hosted LLM service.
- The LLM service endpoint, model identifier, credentials, and generation
limits must be configurable.
- Lisa must support multi-turn exchanges between the LLM and tools within one
invocation.
- The number of LLM and tool iterations for one invocation must be bounded and
configurable.
- Lisa must place an upper bound on response length.
- Failure or unavailability of the LLM service must not terminate the bot.
### Tools
- The LLM must be able to decide whether a tool is needed and which available
tool to use.
- Lisa must provide a web search tool.
- Lisa must provide a tool for downloading a web page over HTTP or HTTPS.
- Lisa must provide a tool for converting downloaded HTML into Markdown using
Pandoc.
- Tool inputs must be validated before execution.
- Tool execution time and returned content size must be bounded.
- Tool failures must be reported to the LLM so it can recover, choose another
approach, or answer without the failed tool.
- The result of one tool call may be used by a later tool call during the same
invocation.
- Web content must be treated as untrusted information, not as instructions
that can change Lisa's persona, permissions, or tool policy.
- When a response relies materially on web research, Lisa must include links
to the relevant sources.
- Lisa must not fabricate source links.
### Web access safety
- Web tools must accept only HTTP and HTTPS URLs.
- Downloads must have configurable limits for size, redirects, and duration.
- Downloaded content must not gain access to local files or credentials.
### Errors and recovery
- A failed invocation must produce a brief, in-character error response when
Lisa can still send messages to the room.
- User-visible errors must not contain credentials, internal prompts, stack
traces, or other sensitive implementation details.
- Lisa must continue processing later invocations after an LLM, tool, or
Matrix request fails.
- Lisa must reconnect automatically after a temporary loss of connection to
the Matrix or LLM service.
- Restarting or reconnecting the bot must not cause an already handled
invocation to be answered again.
## Configuration requirements
The operator must be able to configure:
- The Continuwuity server and Lisa's Matrix account credentials.
- The rooms in which Lisa is allowed to operate.
- Lisa's identity for mention detection.
- The LLM service endpoint, credentials, and model identifier.
- Lisa's persona.
- Conversation-context limits.
- LLM response and iteration limits.
- Tool time, redirect, download-size, and output-size limits.
- Web search service details, if the search tool requires them.
- Logging verbosity.
Credentials must not be committed to source control.
## Privacy and logging
- Room messages must be disclosed only to services required to fulfill an
invocation.
- Logs must not contain access tokens, API credentials, or other secrets.
- Routine logs should identify invocations and failures without recording full
room conversations or complete downloaded pages.
- Tool and LLM failures must be diagnosable from operator-visible logs.
## Implementation constraints
- Lisa must be implemented in Rust.
- Dependencies should be kept to those that materially reduce implementation,
security, or maintenance risk.
- Pandoc is an external runtime requirement.
- Lisa must run without requiring changes to the existing LLM server.
## Acceptance criteria
Lisa is ready for initial use when all of the following are true:
- Mentioning Lisa in an allowed room produces exactly one reply.
- Replying to Lisa without mentioning her produces exactly one reply.
- An ordinary message that neither mentions nor replies to Lisa produces no
reply.
- A mention in a room that is not allowed produces no reply.
- Lisa's reply reflects relevant recent messages and attributes them to the
correct participants.
- Lisa responds according to the configured persona.
- Lisa can answer a question by searching the web, reading a result, and
citing the source.
- A failed web request does not prevent Lisa from replying or handling later
invocations.
- A failed LLM request does not terminate Lisa.
- Restarting Lisa does not replay responses to previously handled messages.
- Responses and logs do not expose configured credentials.