lemdb/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

This repository currently contains the technical architecture report and its bundled Mermaid asset:

• tech-architecture/tech-architecture.html: self-contained architecture and technology-selection report.
• tech-architecture/_shared/js/mermaid.min.js: local Mermaid renderer; keep vendored assets beside the HTML report.
• Root-level images and screenshots are reference material, not application source.

The report defines the planned Python implementation. When implementation begins, use a src layout under src/lmpm/, with subpackages such as domain/, data/, doe/, and later ml/ and api/. CLI entry points belong in src/lmpm/scripts/, tests in tests/, and generated SQLite or CSV artifacts in data/. Do not commit local database files or experiment data.

Build, Test, and Development Commands

For the current static report:

• python -m http.server 47319 --directory tech-architecture: serve the report locally; open http://localhost:47319/tech-architecture.html.

For the planned Python package:

• uv sync: install dependencies declared in pyproject.toml.
• uv run pytest: run the test suite.
• uv run ruff check .: lint Python sources.
• uv run ruff format .: apply the repository formatter.

Coding Style & Naming Conventions

Use Python 3.10+ and 4-space indentation. Keep modules, classes, functions, and tests in snake_case/PascalCase as standard Python requires. Prefer descriptive domain names: MaterialProperty, ExperimentRecord, and ParameterSpace mirror the documented domain model. Keep one primary concern per module, place data models under domain/, and isolate hardware, persistence, and ML concerns behind small, testable APIs. Run Ruff before committing.

Testing Guidelines

Use pytest. Cover domain validation, SQLite/CSV data import-export behavior, DOE generation, and model or API behavior as those layers are added. Name tests after the unit under test, for example tests/test_material.py or tests/test_store.py. Prefer small, deterministic tests and use temporary files or in-memory SQLite for persistence tests.

Deployment Environment

Production deployment and model training target the Ubuntu server. Prefer Docker as the deployment and training runtime so the scientific Python stack, CUDA-free CPU dependencies, and filesystem paths remain reproducible across machines. Use uv.lock as the dependency source of truth and avoid compiling native binaries unless a required dependency has no compatible wheel. Direct Ubuntu deployment with uv sync is acceptable only when a lightweight host environment is explicitly required.

Commit & Pull Request Guidelines

No Git history exists yet, so use concise, imperative Conventional Commits such as feat: add material schema or docs: update architecture report. Pull requests should describe the change and motivation, link related issues or project tasks, include verification commands and results, and add screenshots for visible report changes.

Agent-Specific Instructions

Treat the architecture report as the source of truth for planned structure and dependencies. Keep documentation, diagrams, and implementation decisions aligned; call out intentional deviations in commit messages or pull requests.