F26 · COMP 523

Specification

Requirements, personas, user stories, workflows, and error-handling behavior. A living document.

Requirements Out of Scope Personas User Stories Workflows Error Handling Technical Approach Platform Selection

Functional Requirements

FR-1
Resource discovery by location
A user enters a ZIP code or town and receives the library system and outlets serving that area, with their available digital and physical resources, ranked by proximity. Ideally should allow the user to have the ability to specify the desired maximum distance of target libraries from their ZIP code, with a stretch goal of allowing users to hand-select their libraries.
Must have
FR-2
Natural-language question answering
Questions are answered from the curated dataset of roughly 467 records covering 100 counties, 90 library systems, and 413 outlets, with about 40 attributes each including resource name, URL, access model, format, NC LIVE membership, and usability notes.
Must have
FR-3
Step-by-step guided navigation
Modeled on the NC DMV AI agent. The assistant walks the user through card signup, login, app installation, and database access one step at a time, confirming before advancing.
Must have
FR-4
Source citation
Every substantive answer names and links to the source.
Must have
FR-5
Confidence-based guardrails
High-confidence answers are served directly. Medium and low confidence answers are visibly flagged, cited, and offered with a path to a human librarian.
Must have
FR-6
Librarian admin panel
Authenticated librarians can add, edit, remove, and override dataset entries, and can flag broken links. Every change is recorded in an audit log.
Must have
FR-7
Responsive interface
The interface works on desktop, tablet, and mobile.
Must have
FR-8
Local activity and event information
Community programs, health events, and links to local resources.
Should have
FR-9
Gap reporting
Questions the assistant cannot answer are logged to a review queue that librarians can see.
Should have
FR-10
Conversation memory within a session
A user can ask a follow-up question without repeating their ZIP code.
Should have

Non-Functional Requirements

NFR-1
Plain language
Output targets roughly a sixth to eighth grade reading level. No library jargon without explanation. Words like database, catalog, and consortium mean nothing to most patrons.
NFR-2
Accessibility
WCAG 2.1 AA. Keyboard navigable, screen-reader usable, adequate contrast, resizable text. One of our primary personas is 72 years old.
NFR-3
Performance
First response in under about five seconds, usable on slow rural connections, with no heavy client-side payloads.
NFR-4
Privacy
No account required for patrons. ZIP code only, never a street address. No personally identifying information stored. Health-topic queries are especially sensitive and are never retained against an identity.
NFR-5
Bounded cost
API spend is estimated and capped. A cost estimate with justification goes to the client before any paid service is switched on.
NFR-6
Maintainability
The dataset is swappable without a code change, so the client can replace it as it is finalized and extended.

Out of Scope this Semester

  • Real time crawling of live library websites. Discussed and deliberately deferred. See decision D-1 on the timeline.
  • The fully autonomous agent that keeps the database current on its own. That is the long-term vision, not this semester's deliverable.
  • Native iOS and Android applications. The web interface is responsive instead.
  • Languages other than English. A stretch goal at best.
  • Patron accounts, saved history, or authentication for anyone who is not a librarian.

User Personas

Four personas guide design and evaluation. Every feature is checked against at least one of them.

Persona one
Ruth, 72. Managing hypertension and type 2 diabetes.
Lives outside a small town in eastern North Carolina. Her doctor is forty minutes away and she goes twice a year. She has a library card from a decade ago and a tablet her daughter set up.
  • Needs: trustworthy, readable health information, help getting past a login screen, large text, and no jargon.
  • Frustrations: does not know the library offers anything online at all, abandons any site that asks her to authenticate, and is afraid of clicking the wrong thing.
  • Success: she reaches a reputable health database and reads an article about her condition without calling her daughter.
Persona two
Danielle, 38. Homeschooling parent of three.
Rural county in the northwest. Comfortable with technology and chronically short on time.
  • Needs: pediatric health information she can trust, reading and curriculum material by grade level, e-books and audiobooks for the kids, and the county library's programs.
  • Frustrations: cannot tell what is free through the library versus what she is about to pay for twice, and resources are scattered across a dozen sites.
  • Success: one list of what her library already pays for, by subject and age, with the access steps attached.
Persona three
Marcus, 16. Rural teenager seeking mental health support.
Southeastern North Carolina. Phone only. There is one counselor for his entire school.
  • Needs: confidential, after-hours, mobile-first access to mental health information and local services.
  • Frustrations: few local options, will not ask a librarian in person, and does not want a record of what he searched.
  • Success: he finds real local and statewide support, and if he is in crisis he is handed the crisis line immediately rather than a chatbot's opinion.
Persona four
Sandra, 45. Branch librarian and system administrator.
Manages a branch in the foothills. Eleven years in the job and she still finds subscriptions she did not know about.
  • Needs: to correct wrong entries for her branch, fix broken links, add local events, and override an answer the assistant keeps getting wrong.
  • Frustrations: the catalog of resources is larger than any one person can hold, and nobody owns keeping the list current.
  • Success: she fixes a bad entry in under two minutes and sees the assistant's answer change.

User Stories

Ruth, older adult with a chronic condition

As Ruth, I want to type my ZIP code and be told which library serves me, so that I know where to start.
Accepted when: a valid North Carolina ZIP returns the serving system and nearest outlets with address and hours, nearest first.
As Ruth, I want to ask about managing my diabetes in my own words and be shown resources my library already pays for.
Accepted when: results are filtered to what her system actually carries, and each result names its source and links to it.
As Ruth, I want to be walked through logging in one step at a time, so that I do not get lost.
Accepted when: one instruction per step, the assistant waits for confirmation before continuing, and the user can go back.
As Ruth, I want to be told plainly when the assistant is not sure, so that I do not act on something wrong.
Accepted when: below the confidence threshold the answer is visibly marked as unverified and the librarian contact is offered.

Danielle, homeschooling parent

As Danielle, I want to see everything my library offers for children by subject and age, so that I stop paying for things I already have.
Accepted when: results can be filtered by audience and format, and the access model is stated for each.
As Danielle, I want to know how to get my kids onto Libby and Hoopla, so that I can set it up once.
Accepted when: a guided walkthrough covers card number, app install, and library selection.
As Danielle, I want to see upcoming programs at my county library, so that I can plan around them.
Accepted when: local events are listed with date, location, and a source link.

Marcus, rural teenager

As Marcus, I want to use this on my phone without making an account, so that nothing is tied to my name.
Accepted when: full functionality on a small screen with no login, and no personally identifying information collected.
As Marcus, I want to find mental health resources near me and statewide, so that I have somewhere to go.
Accepted when: results include library-provided resources and vetted local and statewide services.
As Marcus, if I say something that sounds like a crisis, I want real help immediately rather than a chatbot answer.
Accepted when: crisis language triggers an immediate, unmissable handoff to the 988 Suicide and Crisis Lifeline and local services, and the assistant does not attempt triage.

Sandra, librarian administrator

As Sandra, I want to sign in to an admin panel, so that only staff can change the data.
Accepted when: authenticated access only, and unauthenticated requests to admin routes are rejected.
As Sandra, I want to add, edit, and remove resource entries for my system, so that the data reflects reality.
Accepted when: full create, edit, and remove on entries scoped to her system, reflected in answers immediately.
As Sandra, I want to override an answer the assistant keeps getting wrong, so that patrons stop being misled.
Accepted when: a librarian-authored override takes precedence over generated content and is labeled as staff verified.
As Sandra, I want to see questions the assistant could not answer, so that I know what to add.
Accepted when: a review queue of unanswered and low-confidence questions, with frequency counts.
As Sandra, I want broken links flagged, so that I am not the one who has to find them.
Accepted when: links recorded as broken, or reported by users, appear in the queue and are suppressed from answers.

Core Workflows

W1
Resource discovery
  1. The user opens the assistant and is asked for a ZIP code, or the name of their town.
  2. The system resolves that to a county, a library system, and the outlets serving it.
  3. The user asks a question in plain language.
  4. The system retrieves matching records, scoped to that system's holdings.
  5. Results are ranked by relevance and proximity and returned with access model, format, and source link.
  6. The user selects one and is offered the guided walkthrough.
W2
Guided access walkthrough
  1. The system states what the user needs before starting, such as a library card number.
  2. The system gives one step and waits.
  3. The user confirms, asks for clarification, or says it did not work.
  4. If it did not work, the system offers the known alternative path for that resource.
  5. Steps repeat until access is confirmed or the user is handed to a librarian.
  6. The system closes with a short summary of what was done, so it can be repeated later.
W3
Local activities and events
  1. The user asks what is happening nearby, or accepts a prompt offering it.
  2. The system returns programs and health events for the resolved system, with date, place, and source.
  3. Entries past their date are not shown.
W4
Librarian administration
  1. The librarian authenticates into the admin panel.
  2. The panel lists entries scoped to their system, plus the review queue of unanswered, low-confidence, and broken-link items.
  3. The librarian creates, edits, overrides, or retires an entry.
  4. The change is validated, written, and recorded in the audit log with author and timestamp.
  5. Subsequent answers reflect the change.
W5
Low-confidence escalation
  1. The system scores its retrieval and answer confidence.
  2. High confidence: the answer is served directly with its citation.
  3. Medium confidence: the answer is served, visibly marked as unverified, with the source link foregrounded and a suggestion to confirm with a librarian.
  4. Low confidence: no answer is asserted. The system says it does not know, offers the closest verified resource and the librarian contact, and logs the question to the review queue.

Error Handling

What the assistant does when something goes wrong, is missing, or falls outside what it should answer.

Invalid or malformed ZIP code
Reject it without penalty, explain the expected format, and offer to search by town or county name instead. Never guess a location.
ZIP code outside North Carolina
Say plainly that coverage is North Carolina only, and point to the national library locator and NC LIVE as alternatives.
ZIP resolves but no outlet nearby
Return the serving system's digital resources anyway, since those do not require a trip, and name the nearest physical outlet with its distance.
No resource matches the topic
Say so directly rather than substituting something loosely related. Offer the nearest adjacent category, offer the librarian contact, and log the gap to the review queue.
Low retrieval confidence
Do not assert an answer at all. Say what is not known, offer the closest verified resource and the librarian contact, and log the question.
Medium confidence
Serve the answer with a visible marker that it is unverified and a prominent source link, and suggest confirming with a librarian.
Link known to be broken
Suppress the link, show the resource with a note that access is currently unavailable, offer the library's contact, and surface it in the librarian queue.
Model or API failure or timeout
Fail visibly, not silently. Show a plain message, retry once, and fall back to a static directory of the resolved system's resources so the user is not left with nothing.
Rate limit or budget ceiling reached
Degrade to keyword search over the dataset and notify administrators. The site stays usable.
Request for medical, legal, or financial advice
Decline to advise. Redirect to the relevant vetted resources and, where appropriate, to a professional. The assistant finds information. It does not diagnose or counsel.
Crisis or self-harm language
Interrupt the normal flow immediately and present the 988 Suicide and Crisis Lifeline and local crisis services prominently. Do not triage, assess, or counsel, and do not make the user keep typing to reach help.
Prompt injection or off-topic manipulation
Stay in scope. Content retrieved from the dataset or the web is treated as data, never as instructions.
Unauthenticated access to an admin route
Reject with a generic failure, reveal nothing about what exists, and record the attempt.
Invalid librarian edit
Reject the write, keep the previous value intact, and explain exactly which field failed and why.
Dataset unavailable at startup
Refuse to serve generated answers at all rather than answer without grounding. Show a maintenance notice.

Technical Approach

  • Backend data. The curated dataset assembled by the client's research students: roughly 467 rows, all 100 counties, 90 library systems, 413 outlets, and about 40 columns per row. Still being finalized and delivered via OneDrive.
  • Retrieval. Retrieval over that dataset, filtered by the resolved library system, feeding a generation step that is required to cite what it used.
  • Guardrails. Confidence scoring on both retrieval and generation, thresholded into the behavior described in workflow W5.
  • Administration. Authenticated create, edit, and remove over the dataset, with an audit log and a review queue.
  • Deferred. Live fetching and real time retrieval. The client is open to funding API costs, and we owe a cost estimate with justification before anything paid is enabled. The client also has a high-end laptop with a local LLM already configured that we may use.
  • First working version is estimated at two to five weeks from the kickoff meeting.

Platform

Our platform choices, the alternatives we weighed against them, the pros and cons of each, and the constraints our client placed on us are documented in full on the Platform Selection page.