Skip to content

README.md

Latest commit

 

History

History
208 lines (169 loc) · 8.73 KB

README.md

File metadata and controls

208 lines (169 loc) · 8.73 KB

TransferAI

TransferAI helps California students understand how their community college courses transfer to UC campuses, using AI to interpret complex articulation rules and provide clear, accurate guidance.

Version 1.6 - Modular Architecture Release

This version represents a significant architectural refactoring to enhance maintainability, testability, and extensibility. Key improvements include:

  • Implemented modular architecture with clear separation of concerns
  • Added specialized query handlers for different query types
  • Created a unified ArticulationFacade for all articulation operations
  • Enhanced test coverage and organization
  • Fixed contradictory logic in course validation
  • Standardized honors course notation
  • Improved query classification and processing
  • Added full support for local embeddings (no OpenAI API dependency)

System Architecture

TransferAI is built using established design patterns for robust and maintainable code:

Design Patterns

  • Strategy Pattern: Specialized query handlers for different query types
  • Repository Pattern: Document access and data caching
  • Facade Pattern: Simplified interfaces to complex subsystems
  • Dependency Injection: Loose coupling and enhanced testability

System Flow

  1. Query Intake: User queries enter the system through the TransferAIEngine
  2. Query Processing:
    • QueryService parses the query and extracts relevant filters
    • QueryService determines the query type (course validation, lookup, honors, etc.)
  3. Query Routing:
    • The engine routes the query to the appropriate specialized handler via the handler registry
    • Each handler is optimized for specific query types (validation, equivalency, group, honors, etc.)
  4. Document Retrieval:
    • Handlers access relevant articulation documents through the DocumentRepository
    • Documents are filtered based on extracted course codes, groups, or sections
  5. Articulation Logic:
    • The ArticulationFacade provides a unified interface to all articulation functionality
    • Core validation, formatting, and rendering logic is delegated to specialized modules
  6. Response Generation:
    • Handlers use the PromptService to build appropriate prompts
    • Responses are formatted according to query type and articulation rules
  7. Response Delivery: Formatted responses are returned to the user

Project Structure

The project follows a modular architecture:

TransferAI/
├── llm/                          # Core TransferAI package
│   ├── engine/                   # Core engine components
│   │   ├── transfer_engine.py    # Main engine - entry point for queries
│   │   ├── config.py             # Configuration management
│   │   └── utils.py              # Shared utilities
│   ├── handlers/                 # Query handlers
│   │   ├── base.py               # Handler base class and registry
│   │   ├── validation_handler.py # Course validation handler
│   │   ├── course_handler.py     # Course equivalency handler
│   │   ├── course_lookup_handler.py # Course lookup handler
│   │   ├── group_handler.py      # Group requirement handler
│   │   ├── honors_handler.py     # Honors queries handler
│   │   └── fallback_handler.py   # Default/fallback handler
│   ├── repositories/             # Data access layer
│   │   ├── document_repository.py # Document access and caching
│   │   ├── course_repository.py  # Course information access
│   │   └── template_repository.py # Template storage
│   ├── services/                 # Core services
│   │   ├── document_service.py   # Document loading & processing
│   │   ├── query_service.py      # Query parsing & classification
│   │   ├── prompt_service.py     # Prompt building & management
│   │   ├── matching_service.py   # Document matching & filtering
│   │   └── articulation_facade.py # Unified interface to articulation
│   ├── models/                   # Data models
│   │   ├── document.py           # Document wrapper models
│   │   ├── query.py              # Query models and types
│   │   ├── response.py           # Response models
│   │   └── config.py             # Configuration models
│   ├── templates/                # Prompt templates
│   │   ├── course_templates.py   # Course-related templates
│   │   ├── group_templates.py    # Group-related templates
│   │   └── helpers.py            # Template helper functions
│   ├── articulation/             # Core articulation logic
│   │   ├── validators.py         # Validates course requirements
│   │   ├── renderers.py          # Renders articulation data
│   │   ├── formatters.py         # Formats articulation responses
│   │   ├── analyzers.py          # Analyzes articulation data
│   │   ├── detectors.py          # Detects patterns in articulation
│   │   └── models.py             # Articulation data models
│   ├── data/                     # Data files for the system
│   ├── docs/                     # Documentation
│   ├── tests/                    # Unit and integration tests
│   │   ├── engine/               # Tests for engine components
│   │   ├── handlers/             # Tests for query handlers
│   │   ├── services/             # Tests for services
│   │   └── articulation/         # Tests for articulation logic
│   └── main.py                   # Application entry point
├── data/                         # Additional data files
├── regression tests/             # End-to-end test files
└── webpage/                      # Web interface components

Getting Started

Prerequisites

  • Python 3.9+
  • Sentence Transformers (for local embeddings)

Installation

  1. Clone the repository:

    git clone https://github.com/yourusername/TransferAI.git
cd TransferAI

  2. Install dependencies:

    pip install -r requirements.txt

  3. Run tests to verify installation:

    python3 llm/run_unit_tests.py

Usage

from llm.engine.transfer_engine import TransferAIEngine

# Initialize the engine
engine = TransferAIEngine()
engine.configure()
engine.load()

# Process a query
response = engine.handle_query("Which De Anza courses satisfy CSE 8A at UCSD?")
print(response)

Development

Running Tests

Unit tests:

python3 llm/run_unit_tests.py

Specific test module:

python3 llm/run_unit_tests.py services.test_articulation_facade

Regression tests:

python3 llm/regression_tests/test_runner.py

Key Components

Engine

The core TransferAIEngine manages the query processing pipeline, coordinating between services and handlers.

Handlers

Specialized query handlers process different types of queries:

  • ValidationQueryHandler: Validates if courses satisfy requirements
  • CourseEquivalencyHandler: Identifies equivalent courses
  • CourseLookupHandler: Provides information about courses that satisfy a specific UC course
  • GroupQueryHandler: Processes group requirement queries
  • HonorsQueryHandler: Handles honors course requirements
  • FallbackQueryHandler: Processes queries that don't match other handlers

Services

  • DocumentService: Loads and manages articulation documents
  • QueryService: Parses and classifies user queries
  • PromptService: Builds prompts for different query types
  • MatchingService: Matches queries to relevant documents
  • ArticulationFacade: Provides a unified interface to articulation logic

Models

The models package contains data structures that represent core system entities:

  • document.py: Document models for articulation data representation
  • query.py: Query models including QueryType enumeration for classification
  • response.py: Response models for structured handler output
  • config.py: Configuration models for system settings and parameters

Articulation Package

The core articulation modules handle the complex logic of course articulation:

  • validators.py: Validates course combinations against requirements
  • renderers.py: Renders articulation data in human-readable format
  • formatters.py: Formats articulation responses consistently
  • analyzers.py: Analyzes articulation data for patterns
  • detectors.py: Detects specific patterns in articulation rules

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.