# Semantic Models Lab

Semantic Models Lab is a DSS plugin for editing semantic models and powering semantic-model-aware agent tools.

It includes:

- a Flask backend under `python-lib/semantic_models`
- a Vue 3 frontend under `resource/frontend`
- DSS plugin assets and webapp entrypoints
- agent tools for semantic model query and dataset SQL query

## What This Repo Contains

- `python-lib/semantic_models`: backend application, services, routes, agent runtime, and shared schemas
- `python-lib/tests`: backend tests
- `resource/frontend`: Vue 3 + Vite frontend for the semantic model editor
- `python-agent-tools`: DSS agent tool entrypoints
- `webapps/semantic-model-editor`: DSS webapp integration assets
- `docs`: high-level exploration and architecture notes

Start with `docs/semantic-model-tools-overview.md` for the high-level difference between `Semantic Model Query` and `Dataset SQL Query`.

## Local Development

### Prerequisites

- Python 3.12 for the project virtualenv
- Node.js 22+
- Yarn 1.22+

### Initial Setup

```bash
make setup
```

This will:

- create `.env`
- create `.venv`
- install backend dependencies
- install frontend dependencies
- install repository git hooks

### DSS resources setup

Update the generated `.env` file with values from your DSS instance, especially the entries in the `DSS Configuration` section.

### Run The App

Backend:

```bash
make backend-dev
```

Frontend:

```bash
make frontend-dev
```

The backend runs through `wsgi.py`. In local development, it enables CORS and serves the Flask API for the Vite frontend.

## Backend API Docs

The backend OpenAPI spec is generated from Flask route decorators with `flask-pydantic-spec`.

Available endpoints:

- Swagger UI: `/api/docs`
- Swagger UI direct path: `/api/docs/swagger`
- Generated spec: `/api/docs/openapi.json`
- Compatibility alias: `/api/openapi.json`

Route-local OpenAPI request and response models live next to the controllers in `python-lib/semantic_models/routes/*_models.py`.

## Frontend API Generation

The frontend client is generated with Orval from a checked-in OpenAPI spec.

Relevant files:

- exported spec: `resource/frontend/openapi/openapi.json`
- Orval config: `resource/frontend/orval.config.ts`
- generated client: `resource/frontend/src/api/generated/client.ts`

To regenerate the spec and frontend client together:

```bash
make frontend-api-sync
```

That command:

1. exports the backend OpenAPI spec to `resource/frontend/openapi/openapi.json`
2. runs Orval to regenerate the frontend client

You can still run the steps separately:

```bash
make backend-openapi-export
make frontend-api-generate
```

## Common Commands

Setup and local dev:

- `make setup`
- `make backend-dev`
- `make frontend-dev`

Backend checks:

- `make backend-unit-tests`
- `make backend-lint-check`
- `make backend-build-check`

Frontend checks:

- `make frontend-lint-check`
- `make frontend-format-check`
- `make frontend-test`
- `make frontend-build`

API generation:

- `make backend-openapi-export`
- `make frontend-api-generate`
- `make frontend-api-sync`

## Development Notes

- Prefer top-level package imports for public project code, such as `from semantic_models.agent import ...`
- Treat package-level modules as the stable API across subpackages
- Keep backend route contract models close to the route files that use them
- The frontend currently keeps a stable `src/api/index.ts` facade on top of the generated Orval client so the rest of the app can migrate incrementally

## Plugin Metadata

- Plugin ID: `semantic-models-lab`
- Version: `1.0.0`
- Category: `Generative AI`
