Software Requirements Specification - DrAlzahrani2025Projects/team1f25 GitHub Wiki

Project: CSUSB Scholarly AI Assistant

Version: 1.0

Date: 2025-11-04

Authors: Team1f25

Status: Baseline

1. Introduction

1.1 Purpose

This Software Requirements Specification (SRS) defines the goals, scope, functional requirements, and nonfunctional requirements for the CSUSB Scholarly AI Assistant. It is intended for stakeholders, product owners, analysts, designers, developers, testers, librarians, and maintainers to establish a shared understanding before implementation begins.

1.2 Document conventions

  • Standard IEEE SRS structure and terminology.
  • Plain language; minimal technical implementation details.

1.3 Intended audience and reading suggestions

  • Product owners and stakeholders: Review Sections 1–2 for scope and user context.
  • Analysts and designers: Review Sections 2–5 for system behavior and constraints.
  • Testers: Review Sections 3–5 for acceptance criteria and quality attributes.
  • Maintainers: Review Sections 5–6 for quality, compliance, and constraints.

1.4 Product scope

CSUSB Scholarly AI Assistant is a web-based conversational assistant that helps students, faculty, and staff discover and refine scholarly resources from institutional collections and reputable academic sources. Through a chat-driven experience, the assistant interprets user intent, performs scholarly searches, applies useful filters (e.g., date range, resource type), and presents clear, citable results with links. Outcomes include faster discovery, improved search strategies, and transparent access to authoritative resources.

1.5 References

  • IEEE/ISO/IEC 29148: Systems and software engineering β€” Life cycle processes β€” Requirements engineering.
  • CSU/CSUSB institutional policies on privacy, acceptable use, and accessibility.
  • Library link resolver and discovery service policies.
  • Terms of use for scholarly content providers and the LLM provider.

2. Overall description

2.1 Product perspective

  • Context: Standalone web application that integrates with institutional search/discovery services and an LLM provider.
  • Interactions: End users (via chat UI), library discovery APIs, institutional link resolver/proxy for full-text access, and an LLM provider for language understanding and suggestion generation.
  • High-level workflow: User query β†’ Intent/constraint analysis β†’ Scholarly search β†’ Filtering and ranking β†’ Result formatting β†’ Display with links β†’ Guided suggestions β†’ Iteration.

2.2 Product functions (high-level)

  • F1. Allow users to submit research queries conversationally (free-text chat).
  • F2. Analyze the query to infer topic, intent, date constraints, and resource type.
  • F3. Perform scholarly search and present results with summaries and basic refinement controls (e.g., sort/filter).
  • F4. Provide guided suggestions and follow-ups to improve search outcomes.
  • F5. Optionally support saving or exporting selected references (e.g., links/citations) when applicable.

2.3 User classes and characteristics

  • Primary users: Students (undergraduate and graduate) with basic to moderate technical proficiency.
  • Secondary users: Faculty/Researchers with moderate proficiency; Librarians/Support staff with high domain expertise.
  • Accessibility needs: Inclusive design with clear language, keyboard navigation, screen-reader compatibility, and sufficient contrast.

2.4 Operating environment

  • Client: Modern web browsers (e.g., Chrome, Edge, Safari) on desktop and mobile.
  • Server: University-managed or cloud-hosted environment; scalable hosting expected.
  • Data: Institutional discovery/catalog APIs and reputable scholarly data sources; minimal transient session storage.

2.5 Design and implementation constraints

  • Compliance: Adhere to institutional privacy policies and accessibility guidelines.
  • Legal/licensing: Respect third-party content licenses and API terms of use.
  • Resource constraints: Semester timeline; small student team; limited budget.
  • Technology constraints: Must integrate with institutional discovery APIs and a supported LLM provider; observe API rate limits.

2.6 User documentation

  • Quick start guide with example queries.
  • User help/FAQ (how to refine searches, interpret results, and access full text).
  • Release notes and change log.

2.7 Assumptions and dependencies

  • Assumptions: Stable access to institutional search services; typical student network conditions; users can access full text via institutional credentials when required.
  • Dependencies: Library discovery API, institutional link resolver/proxy, LLM provider service, and web browser capabilities.

3. External interface requirements

3.1 User interfaces

  • General: Clean, responsive chat interface prioritizing accessibility and clarity.
  • Conversation area: Displays user prompts and assistant responses in a readable timeline.
  • Input: Single message box with submit; support for basic editing and resubmission.
  • Results panel: Cards or list view with title, brief context, source, and link; visible filters (e.g., date, type) when available.
  • Feedback: Clear loading indicators, human-readable error messages, and confirmations; provide β€œno results” guidance.

3.2 Hardware interfaces

Not applicable for typical web deployments. No special peripherals are required.

3.3 Software interfaces

  • External scholarly search/discovery API: Retrieve bibliographic records and availability.
  • Link resolver/proxy: Provide institution-authorized links to full text.
  • LLM provider API: Natural-language understanding and suggestion generation.
  • Authentication/Authorization: May rely on institutional SSO for accessing licensed content; the assistant itself can function without user accounts if session-only.
  • Data storage: Ephemeral session context; optional lightweight storage for saved lists if enabled.

3.4 Communications interfaces

  • Protocols: HTTPS for all network communication; optional streaming responses.
  • Network requirements: Typical broadband; no offline mode.

4. System features

Each feature is described at a user-facing level with minimal technical detail. Acceptance criteria are stated behaviorally, not in code.

4.1 Feature A: Conversational query intake

  • Description: Users enter research queries through a chat input to begin a session.
  • Priority: High
  • Stimulus/Response:
    • When a user submits a prompt, the system acknowledges receipt and begins analysis.
    • If input is empty or unintelligible, the system provides guidance and examples.
  • Functional requirements:
    • FR-A1: The system shall accept free-text input up to a reasonable length for research queries.
    • FR-A2: The system shall validate that input is non-empty and provide human-readable errors.
    • FR-A3: The system shall display example prompts to help first-time users.

4.2 Feature B: Scholarly search and filtering

  • Description: The system performs scholarly search and allows refinement by criteria such as date and resource type.
  • Priority: High
  • Stimulus/Response:
    • When the user provides a prompt, the system interprets intent and initiates a search.
    • If no results are found, the system proposes alternative strategies or broadened terms.
  • Functional requirements:
    • FR-B1: The system shall query institutional discovery services using the inferred topic and constraints.
    • FR-B2: The system shall offer refinement by date range and resource type (e.g., journal, article) where supported by the data source.
    • FR-B3: The system shall communicate empty, partial, or error states clearly and propose next steps.

4.3 Feature C: Results presentation with links and context

  • Description: The system presents results with clear metadata and direct links to access.
  • Priority: High
  • Functional requirements:
    • FR-C1: The system shall display title, brief summary/context, source, and publication date when available.
    • FR-C2: The system shall provide direct links through the institutional link resolver/proxy to authorized content when applicable.
    • FR-C3: The system shall avoid presenting non-scholarly sources as authoritative.

4.4 Feature D: Guidance and follow-up suggestions

  • Description: The system suggests refinements and follow-up questions to improve results.
  • Priority: Medium
  • Functional requirements:
    • FR-D1: The system shall present context-aware suggestions (e.g., add a date filter, focus on peer-reviewed journals).
    • FR-D2: Suggestions shall be non-intrusive, clearly optional, and easily dismissible.

4.5 Feature E: Save or export (optional)

  • Description: Users can optionally save or export selected references for later use.
  • Priority: Low/Medium
  • Functional requirements:
    • FR-E1: The system may enable users to save selected items to a temporary session list.
    • FR-E2: The system may allow exporting or sharing links to selected items; citation export is optional.

5. Other nonfunctional requirements

5.1 Performance

  • Typical response time: ≀ 5 seconds for common queries under normal load; complex searches may take up to 10 seconds depending on external services.
  • Throughput: Support for typical course-scale usage; targets refined with stakeholder input.
  • Startup: Initial view ready within 3 seconds on modern devices and networks.

5.2 Reliability and availability

  • Availability target: β‰₯ 99.0% during typical usage windows; refined after pilot.
  • Error handling: User-friendly messages; no sensitive details disclosed.
  • Recovery: Operations can be retried; transient errors and timeouts handled gracefully.

5.3 Security and privacy

  • Data protection: Use industry-standard transport security; store only what is necessary for a session.
  • Access control: Enforce least privilege; respect license restrictions for full-text access.
  • Compliance: Align with institutional policies and relevant regulations (e.g., FERPA); avoid storing sensitive personal data.

5.4 Usability and accessibility

  • Accessibility: Aim to conform to WCAG 2.1 AA.
  • Learnability: First-time use should be effective without training; provide examples and inline tips.
  • Internationalization: English for initial release; additional languages considered based on need.

5.5 Maintainability and extensibility

  • Modularity: Components organized for ease of change.
  • Documentation: User and admin documentation kept current with releases.
  • Configurability: Environment- and org-specific settings (e.g., API endpoints, keys) configurable without code changes.

5.6 Portability and compatibility

  • Supported platforms: Current versions of major browsers on Windows and macOS; mobile browsers where feasible.
  • Interoperability: Clear high-level contracts for institutional systems (discovery API, link resolver) and LLM provider.

5.7 Business rules

  • Present authoritative scholarly sources preferentially.
  • Provide clear source attribution and links; avoid misrepresenting availability.
  • When filters are applied (e.g., date, resource type), reflect them accurately in the results.
  • Avoid fabricating citations or links; be transparent about limitations and data sources.

6. Legal, regulatory, and compliance

  • Licensing: Ensure compatibility of open-source components and third-party licenses.
  • Data handling: Adhere to institutional policies for privacy and data retention.
  • Accessibility: Meet applicable accessibility standards or provide reasonable accommodations.

Appendix A: Glossary

  • Scholarly source: Peer-reviewed or academically recognized publication (e.g., journals, conference proceedings).
  • Link resolver: Institutional service that routes users to licensed full-text content when available.
  • Discovery service: System that indexes and exposes library holdings and metadata for search.
  • LLM (Large Language Model): Language model used to analyze queries and suggest refinements.

Appendix B: Analysis models (optional)

  • High-level context diagram or user flow (to be added in design phase).
  • Wireframes or UI sketches (non-binding, conceptual).

Appendix C: To-be-determined (TBD) list

  • TBD-1: Finalize discovery API endpoints and access model.
  • TBD-2: Confirm link resolver/proxy configuration and usage patterns for off-campus access.
  • TBD-3: Set concrete performance targets after initial prototype testing.
  • TBD-4: Decide on optional saved lists and export formats.
  • TBD-5: Determine scope of initial subject areas or collections to prioritize.

Change log

  • 1.0 (Baseline): Finalized pre-implementation SRS; reconciled versioning and feature labels.
  • 0.2 (Tailored Draft): Updated with CSUSB scholarly assistant scope, features, interfaces, and quality attributes.
  • 0.1 (Draft): Initial pre-implementation SRS created.