Metadata-Version: 2.4
Name: senselab-cli
Version: 0.1.1
Summary: SenseLab CLI for managing AI agents
Author: SenseLab
Project-URL: Homepage, https://github.com/raia-live/backend-api
Project-URL: Repository, https://github.com/raia-live/backend-api
Keywords: senselab,cli,devops,sre,orchestrator
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.31.0
Requires-Dist: PyYAML>=6.0

# Raia Backend Server 

## Prerequisites

The official development environment is configured for Ubuntu 22.04 LTS.
In order to work on the project, the following components must be installed (in brackets confirmed working version were placed):

- docker (20.10.14)
- docker compose plugin (version v2.3.3)

## Development setup

### For local env (backend server and postgres containers deployed locally using docker compose)

1. `cp .env.example .env`

2. Fill missing values in .env template file

3. `docker compose build`

4. `docker compose up`

5. Application server should be exposed on APP_PORT defined in .env file

6. Gunicorn inside backend container will reload automatically upon code change in src/ directory

7. Also, you can connect to Postgres DB from your workstation using localhost as a host and 15432 as a port

#### (Optional) Running backend directly from command line from workstation

1. Create python virtualenv with python 3.11 and activate it

2. `pip install -r requirements.txt`

3. In your .env file change POSTGRES_HOST=localhost and POSTGRES_PORT=15432

4. Comment out raia-backend service in docker-compose.yml file

5. docker compose up (Only postgres container will be spawned)

6. `cd src/`

7. Run in console: `ENVIRONMENT=local gunicorn --config gunicorn_config.py 'app:create_app()'` or `ENVIRONMENT=local python app.py`

#### (Optional) Connecting to dev env AWS resources (at this moment it means only RDS)

##### Running backend from command line:

Be aware that below command will utilise your AWS credentials stored in ~/.aws/ directory

`ENVIRONMENT=dev AWS_REGION=eu-west-1 python app.py`

OR

`ENVIRONMENT=dev AWS_REGION=eu-west-1 gunicorn --config gunicorn_config.py 'app:create_app()'`

##### Running backend inside container:

1. In raia-backend service comment out env_file section (Almost all needed configuration will be
   fetched from AWS SecretManager and ParameterStore)

2. Set ENVIRONMENT=dev under raia-backend service environment section

3. Turn on Raia AWS VPN (to enable access to RDS instance)

4. Comment out raia-database service section in docker-compose.yml

5. docker compose up


#### (Optional) Running examples

1. Create python virtualenv with python 3.11 and activate it

2. `pip install -r requirements.txt`
 
3. `cd examples/`

4. `export PYTHONPATH="${PYTHONPATH}:<repo_root_path>/src/"`

5. `cp .env.example .env`

6. Fill missing values in .env template file

7. Run desired python script


## How to perform changes on DB schema

1. Make desired changes in src/repository/models.py file

2. In src/ directory perform: `flask db migrate -m "Migration description"`

3. New file under src/migrations/versions/ directory should appear

4. Check it content and apply adjustments if needed

5. `flask db upgrade` will apply migration(s) to DB to which you are actually connected to.
   (Use with caution when connecting to RDS instances. For RDS instances it should be done via CI server)

6. After migration was applied to any of RDS instances, the migration should not be altered, 
   unless upgrade command failed. If something requires further changes. Please crate a follow-up migration.

7. Single migration should be as small as possible.

## How to create an empty migration

1. In src/ directory perform: `flask db revision -m "Migration description"`

2. Continue creating the operations as needed.

## Sense CLI (specialist chat)

This repository now includes a new CLI package under `cli/` for specialist chat and function execution.

- Run CLI locally from repo root: `python3 -m cli.main --help`
- Default API URL: `https://api.raia.live`
- Login options:
  - Token mode: `python3 -m cli.main login --token <CI_CD_TOKEN>`
  - Browser flow: `python3 -m cli.main login --connect-url <frontend-cli-connect-url>`

### New backend telemetry migration

The CLI telemetry endpoint persists events in a `cli_telemetry` table.

Apply DB migration in `src/`:

`flask db upgrade`

Latest migration revision introduced for this feature:

`9b4f31ad7c2e_add_cli_telemetry_table.py`

## Sense CLI build and distribution

After this branch is merged, you can build and distribute the CLI package from this repo.

### Build locally

1. Create and activate a Python 3.11+ virtualenv.
2. Install build tooling:
   - `python3 -m pip install --upgrade build twine pipx`
3. Build package artifacts:
   - `python3 -m build`
4. Validate artifacts:
   - `python3 -m twine check dist/*`

Generated artifacts:
- `dist/senselab_cli-<version>-py3-none-any.whl`
- `dist/senselab_cli-<version>.tar.gz`

### Install locally for smoke tests

- `pipx install dist/senselab_cli-<version>-py3-none-any.whl`
- `sense-cli --help`
- `sense-cli version`

### Publish package

For PyPI:
- `python3 -m twine upload dist/*`

For private package indexes, use your index URL and credentials with `twine upload`.

### Homebrew distribution (SenseLab branding)

Recommended naming:
- Tap: `senselab/tap`
- Formula: `sense-cli`

Example user install flow:
- `brew tap senselab/tap`
- `brew install sense-cli`
