add comprehensive documentation and improve logging in DocGPT

[ajs2583]

This pull request introduces an interaction logging system to DocGPT that automatically records every user interaction (question, retrieved context, answer, and source metadata) to CSV and JSONL files. It also refactors the assistant prompt interface to return richer results, enabling downstream consumers (API, CLI, Discord bot) to access and log context and source information. Minor improvements and bugfixes are included for consistency and robustness.

Interaction Logging System:

• Added a new InteractionLogger utility (src/core/interaction_logger.py) that logs each RAG interaction to timestamped CSV and JSONL files for crash-resilient persistence. The logger is initialized at startup and used in the API, CLI, and Discord bot to record every prompt and response, including retrieved context and source metadata.
• Updated .gitignore to exclude the new logs/ directory where interaction logs are stored.

Assistant Prompt Refactor:

• Changed the assistant prompt interface to return a new PromptResult dataclass, which includes the answer, retrieved context, and source metadata, instead of just a string answer. This affects the assistant adapter, domain, and port definitions. [1] [2] [3] [4] [5]
• Updated API endpoint, CLI, and Discord bot to use the new PromptResult structure, enabling them to log detailed interaction data and display richer responses. [1] [2] [3] [4] [5]

Integration and Initialization:

• The logger is initialized in main.py for API runs, with log file locations configurable via the INTERACTION_LOG_DIR environment variable. Logging is now robust to errors, with failures reported to the application log. [1] [2]

Consistency and Minor Improvements:

• Standardized metadata extraction and error handling in document ingestion for better clarity and maintainability. [1] [2]
• Extended the API response model to include the retrieved context and source count, making the API more informative. [1] [2]

These changes collectively improve traceability, debugging, and analysis of user interactions with DocGPT, while preparing the codebase for future enhancements around context and provenance.

[github-actions]

PR Change Log

Changed Files Summary

Overall: 10 files changed, 1642 insertions(+), 42 deletions(-)

Files Changed

Status	File	Lines Added	Lines Removed
Added	DOCUMENTATION.md	+1354	-0
Modified	systems/docgpt/.gitignore	+4	-1
Modified	systems/docgpt/main.py	+64	-28
Modified	systems/docgpt/src/adapters/assistant.py	+18	-3
Modified	systems/docgpt/src/app/api/v1/endpoints/assistant.py	+24	-2
Modified	systems/docgpt/src/app/discord.py	+23	-6
Added	systems/docgpt/src/core/interaction_logger.py	+141	-0
Modified	systems/docgpt/src/domain/assistant.py	+10	-0
Modified	systems/docgpt/src/domain/responses/assistant.py	+2	-0
Modified	systems/docgpt/src/port/assistant.py	+2	-2

Changes by Directory

• systems/docgpt/: 2 file(s)
• ./: 2 file(s)
• systems/docgpt/src/port/: 1 file(s)
• systems/docgpt/src/domain/responses/: 1 file(s)
• systems/docgpt/src/domain/: 1 file(s)
• systems/docgpt/src/core/: 1 file(s)
• systems/docgpt/src/app/: 1 file(s)
• systems/docgpt/src/adapters/: 1 file(s)
• .../docgpt/src/app/api/v1/endpoints/: 1 file(s)

Warnings

Large changes detected in:

• DOCUMENTATION.md (1354+ / 0-)

---

Updated: 2026-02-11T18:57:11.776Z