Xyzen

AI Laboratory Server

Getting Started

Xyzen supports two development approaches:

1. Containerized Development (Recommended) - Full-stack development with Docker
2. Local Development - Backend/frontend development with local tools

Prerequisites

• For Containerized Development:

  • Docker and Docker Compose
  • uv for pre-commit hooks

• For Local Development:

  • Python 3.13+
  • uv for Python package management
  • Node.js with Yarn (via Corepack) for frontend development

Containerized Development (Recommended)

The easiest way to get started with Xyzen is using the containerized development environment. This automatically sets up all services (PostgreSQL, Mosquitto, Casdoor) and development tools.

Quick Start

1. Clone the repository:

   git clone https://github.com/ScienceOL/Xyzen.git
   cd Xyzen

2. Start the development environment:

   On Unix/Linux/macOS:

   ./launch/dev.sh

   On Windows (PowerShell):

   .\launch\dev.ps1

   Or use the Makefile:

   make dev              # Start in foreground (shows logs)
   make dev ARGS="-d"    # Start in background (daemon mode)
   make dev ARGS="-s"    # Stop containers (without removal)
   make dev ARGS="-e"    # Stop and remove containers

The script will automatically:

• Check Docker and validate .env.dev file
• Set up global Sciol virtual environment at ~/.sciol/venv
• Install and configure pre-commit hooks
• Create VS Code workspace configuration
• Start infrastructure services (PostgreSQL, Mosquitto, Casdoor)
• Launch development containers with hot reloading

Container Development Options

Start in foreground (see logs):

./launch/dev.sh

Start in background:

./launch/dev.sh -d

Stop containers:

./launch/dev.sh -s

Stop and remove containers:

./launch/dev.sh -e

Show help:

./launch/dev.sh -h

AI Agent Configuration

Xyzen uses a standardized instruction file for AI coding assistants to ensuring consistency across different tools.

The master file is located at AGENTS.md.

To configure your preferred AI tool, create a symbolic link (or copy) AGENTS.md to the filename expected by your tool. These specific filenames are ignored by git to keep the repository clean.

GitHub Copilot:

mkdir -p .github
ln -s ../AGENTS.md .github/copilot-instructions.md

Claude / Cursor / Windsurf / Cline:

ln -s AGENTS.md CLAUDE.md       # For Claude
ln -s AGENTS.md .cursorrules    # For Cursor
ln -s AGENTS.md .windsurfrules  # For Windsurf
ln -s AGENTS.md .clinerules     # For Cline
ln -s AGENTS.md .rules          # Generic

Contributing

Contributions are the core of open source! We welcome improvements and features.

Running Tests

Xyzen has a comprehensive unit test suite. All PRs must introduce or update tests as appropriate and pass the full suite.

Run all tests:

cd service
uv run pytest

Run tests with coverage:

cd service
uv run pytest --cov=src --cov=examples --cov-report=html

Run specific tests:

cd service
uv run pytest tests/test_models/        # Run all model tests
uv run pytest -k "test_name"           # Run tests matching pattern
uv run pytest -m "unit"                # Run only unit tests

Code Quality Checks

Xyzen uses pre-commit for code formatting, linting, and type-checking. All PRs must pass these checks (they run automatically in CI).

Install pre-commit hooks (done automatically by make dev or dev.sh):

cd service
uv run pre-commit install

Run checks manually:

cd service
uv run pre-commit run --all-files      # Run all hooks on all files
uv run pre-commit run                  # Run on staged files only

The pre-commit hooks include:

• Python Backend: Ruff (formatting & linting), Pyright (type checking)
• Frontend: Prettier, ESLint, TypeScript checking
• General: Trailing whitespace, end-of-file fixes, YAML validation

Pull Request Process

1. Fork the repository on GitHub
2. Create a feature branch from main
3. Make your changes, including tests and documentation updates
4. Ensure all tests pass: uv run pytest
5. Ensure code quality checks pass: uv run pre-commit run --all-files
6. Commit your changes and push to your fork
7. Open a pull request against the main branch of ScienceOL/Xyzen

Please open an issue or discussion for questions or suggestions before starting significant work!