v1.1.0 - Architecture Alignment

Release Highlights

Version v1.1.0 consolidates the current Archssistant architecture and aligns the implementation with the documented component flow. This release reinforces the separation of responsibilities between deterministic decision-making and LLM-based elicitation and explanation.

Architectural Updates

• The architecture is now consistently centered on five core components: Orchestrator, Elicitation Machine, Explicit Decision Model, Decision Maker, and Recommendation Explainer.
• The former Symbolic Knowledge Base naming has been fully replaced by Explicit Decision Model to match the current architectural model.
• The interaction flow described in the documentation has been aligned with the current component diagram and implementation boundaries.

Implementation Changes

• The backend has been refactored to better reflect the separation between orchestration, deterministic recommendation, and explanation.
• The Explicit Decision Model has been reorganized as a dedicated package containing both the architecture catalog and the decision-table instantiation logic.
• The API layer has been improved through dependency injection and centralized error handling.
• Local execution has been streamlined through docker compose, with frontend and backend running as separate services.

Documentation Updates

• README.md has been revised to reflect the current architecture and terminology.
• The documentation now uses Explicit Decision Model consistently across the repository.
• The setup instructions have been simplified and consolidated into a single section.
• The architectural description has been aligned with the current component diagram used for the paper.

Notes

• This release advances the project from v1.0.0 to v1.1.0.
• The version increment reflects architectural and implementation-level improvements without indicating a major compatibility break.

v1.0.0 - First Release

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.