Skip to content

v1.0.0 - First Release

Choose a tag to compare

View all tags
@JessusTM JessusTM released this 21 Jan 03:52
· 11 commits to main since this release
v1.0.0
dc81227

Overview

Archssistant is a research prototype of an Explainable Conversational Recommender System (CRS). This release establishes the core architecture that enforces separation of responsibilities: a deterministic decision component produces the final recommendation, while the LLM is constrained to elicitation and natural-language explanations.

Note

Focus: traceability and auditability of the recommendation process through explicit responsibility boundaries.

Key Features

  • Core: Multi-turn orchestration with state machine–driven flow control
  • Deterministic: Decision maker based on decision tables, scoring, and ranking
  • Knowledge: Symbolic knowledge base with an explicit, editable architecture catalog
  • LLM · Elicitation: Mapping user answers to predefined criteria with ambiguity detection
  • LLM · Clarification: Next-question generation when user input is ambiguous
  • LLM · Explanation: Natural-language justifications grounded on deterministic decision outputs
  • Traceability: Versioned prompt templates as auditable behavioral artifacts
  • Observability: Structured logging with rotation and separated log levels

Architecture

Six-component architecture:

  • UI (Chat Interface)
  • Orchestrator
  • Elicitation Machine (LLM)
  • Symbolic Knowledge Base
  • Decision Maker (Deterministic)
  • Recommendation Explainer (LLM)

Tech Stack

  • Python, FastAPI
  • Dependency management: uv
  • Frontend: HTML / CSS / JavaScript
  • LLM provider: DeepSeek

Installation & Setup

  1. Clone the repository
  2. Copy .env.example to .env and set DEEPSEEK_API_KEY
  3. Install dependencies:
    • cd archssistant-backend
    • uv sync
  4. Run:
    • uv run app/main.py
      The frontend is served at the root path.

Configuration

Environment variables:

  • LOG_LEVEL (e.g., DEBUG)
  • HOST (e.g., 0.0.0.0)
  • PORT (e.g., 5000)
  • DEEPSEEK_API_KEY

Logging

  • Rotating file handlers (10 MB max per file, 5 backups)
  • Separate log files: info.log, error.log, debug.log
  • debug.log is only created when LOG_LEVEL=DEBUG

Caution

Research prototype. The LLM must remain non-decisional. Any prompt or integration change that lets the LLM influence ranking undermines auditability.

Known Limitations

  • Token/context optimization (currently re-sends full conversation history)
  • Evaluation metrics for explanation quality and auditability
  • Long-term conversation memory with traceable persistence

Changelog

Initial release implementing the core architecture and functionality described in the paper.

Assets 2
Loading