Metadata-Version: 2.1
Name: lucihub-cli
Version: 0.1.1
Summary: Command-line interface for LuciHub system
Author-Email: Anabrid <info@anabrid.com>
Requires-Python: <4.0,>=3.11
Requires-Dist: click<9.0.0,>=8.1.7
Requires-Dist: httpx<1.0.0,>=0.25.0
Requires-Dist: lucihub-common
Requires-Dist: numpy>=2.4
Requires-Dist: pydantic<3.0.0,>=2.0.0
Requires-Dist: rich<14.0.0,>=13.0.0
Requires-Dist: sympy>=1.14.0
Description-Content-Type: text/markdown

# LuciHub CLI

Command-line interface for the LuciHub analog computing system.

## Overview

The LuciHub CLI provides a convenient command-line interface to interact with LuciHub's analog computing devices through the REST API. You can submit tasks, monitor their progress, and retrieve results directly from your terminal.

## Installation

1. Navigate to the CLI directory:
   ```bash
   cd components/cli
   ```

2. Install using Poetry:
   ```bash
   poetry install
   ```

3. The CLI tool will be available as `lucihub` command after installation.

## Usage

### Basic Commands

The CLI connects to a LuciHub API server. By default, it connects to `localhost:8000`, but you can specify different host and port:

```bash
# Connect to default server
lucihub status

# Connect to different server
lucihub -h 192.168.1.100 -p 8080 status
```

### Available Commands

#### 1. System Status
Get system information and connected devices:
```bash
lucihub status
```

#### 2. Run Tasks
Execute a configuration on physical LUCIDAC device:
```bash
# Basic run
lucihub run config.json

# With custom parameters
lucihub run config.json --sample-rate 20000 --op-time 0.5 --device device1
```

Options:
- `--sample-rate`: Number of samples per second (default: 10000)
- `--op-time`: Integration time in seconds (default: 0.1)
- `--device`: Specific device ID (auto-detected if not specified)
- `--no-confirm`: Skip confirmation prompt

#### 3. Simulate Tasks
Execute a configuration on the built-in simulator:
```bash
# Basic simulation
lucihub simulate config.json

# With simulator options
lucihub simulate config.json --k0 1000 --with-limits --op-time 1.0
```

Options:
- `--sample-rate`: Number of samples per second (default: 10000)
- `--op-time`: Integration time in seconds (default: 0.1)
- `--k0`: Acceleration factor (choices: 1, 10, 100, 1000, 10000; default: 10000)
- `--with-limits`: Enable integrator capacity limits
- `--device`: Device context (auto-detected if not specified)
- `--no-confirm`: Skip confirmation prompt

#### 4. Compile Tasks
Compile an ODE specification to device configuration:
```bash
# Basic compilation
lucihub compiler ode.json
```

Options:
- `--no-confirm`: Skip confirmation prompt

### File Formats

#### Configuration Files (for run/simulate)
JSON files containing analog circuit configurations:
```json
{
  "integrators": {
    "int0": {"initial_value": 1.0}
  },
  "constants": {
    "k1": 2.5
  },
  "connections": []
}
```

#### ODE Files (for compiler)
JSON files containing ODE specifications:
```json
{
  "variables": ["x", "y"],
  "equations": {
    "x": "-y",
    "y": "x"
  },
  "initial_conditions": {
    "x": 1.0,
    "y": 0.0
  }
}
```

### Example Workflow

1. Check system status:
   ```bash
   lucihub status
   ```

2. Compile an ODE to configuration:
   ```bash
   lucihub compiler my_ode.json
   # Save the output to compiled_config.json when prompted
   ```

3. Run the compiled configuration:
   ```bash
   lucihub run compiled_config.json --sample-rate 25000 --op-time 0.2
   ```

4. Or simulate instead:
   ```bash
   lucihub simulate compiled_config.json --k0 1000 --with-limits
   ```

## Development

### Running Tests
```bash
poetry run pytest
```

### Code Formatting
```bash
poetry run black .
```

## Dependencies

- **click**: Command-line interface framework
- **httpx**: HTTP client for API communication
- **pydantic**: Data validation using the shared models
- **rich**: Rich text and beautiful formatting in the terminal
- **lucihub-common**: Shared models and utilities

## Error Handling

The CLI provides user-friendly error messages for common issues:
- Connection errors to the API server
- Invalid JSON files
- Missing files
- API errors with detailed messages

Progress indicators show task status during execution, and results are displayed in a formatted, readable way.