Metadata-Version: 2.4
Name: cist-kernel
Version: 0.0.1
Summary: CLI for cist kernel telemetry and compilation
Author-email: tooig research lab <oyebamijo@tooig.com>
License: tooig software license
Requires-Python: >=3.9
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.9.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: build>=0.10.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# CIST Monorepo

Polyglot monorepo for the Contract Instruction Set (`.cis`) language.

This repository ships three user-facing pieces together:

- `cist` Python CLI for workspace bootstrapping, local syntax validation, and cloud compilation.
- A VS Code extension that adds `.cis` language registration, indentation rules, and syntax highlighting.
- A build orchestrator that packages the Python wheel and VSIX from one command.

## What You Install

If you only want to write and validate `.cis` files locally, install the Python CLI.

If you want editor syntax highlighting for `.cis`, install the VS Code extension.

If you want to send contracts to the remote compiler, you need the CLI plus a `CIST_CLOUD_API_KEY`.

## Language Snapshot

```cis
use math
use compute
use risk

market_data := from data (source: "binance", symbols: ["BTC-USD"], resolution: "1m")

sma_20 := math.sma(market_data.close, 20)
signal := compute.crossover(market_data.price, sma_20)

if signal and position.size == 0:
	execute(market_buy(size: risk.calculate_size(portfolio_value: 10000)))
elif position.pnl < -100:
	execute(close_position())
```

## Repository Layout

```text
cist/
├── pyproject.toml
├── README.md
├── .env.example
├── scripts/
│   └── build.py
├── cist_cli/
│   ├── __init__.py
│   ├── main.py
│   ├── parser.py
│   ├── network.py
│   └── assets/
│       └── .gitkeep
├── tests/
│   └── test_parser.py
└── vscode-extension/
	├── README.md
	├── package.json
	├── language-configuration.json
	└── syntaxes/
		└── cis.tmLanguage.json
```

## Installation

### Install From Source

Use this when you are developing CIST itself or want the latest local version.

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
cp .env.example .env
```

Windows PowerShell:

```powershell
python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
Copy-Item .env.example .env
```

### Install The Built CLI Wheel

If a wheel has already been built, install it directly:

```bash
python -m pip install dist/cist-<version>-py3-none-any.whl
```

### Install The VS Code Extension

Build the repo once, then install the generated VSIX from VS Code.

```bash
python scripts/build.py
```

That produces:

- `dist/cist-<version>-py3-none-any.whl`
- `cist_cli/assets/cist-<version>.vsix`

In VS Code, open Extensions, choose `...`, then `Install from VSIX...` and select the file in `cist_cli/assets/`.

If you have the `code` shell command available, you can also run:

```bash
code --install-extension cist_cli/assets/cist-<version>.vsix
```

## Quick Start

After installation, create a workspace and compile a sample contract:

```bash
cist init --path /tmp/test
cist validate /tmp/test/contracts/example.cis

CIST_CLOUD_API_KEY=sk_live_your_api_key_here cist compile /tmp/test/contracts/example.cis --verbose
```

The `validate` command is local-only. The `compile` command contacts the configured cloud endpoint.

## How To Use CIST

Typical workflow:

1. Initialize a folder with `cist init --path <dir>`.
2. Edit the generated `.cis` file or add your own contracts under `contracts/`.
3. Run `cist validate path/to/file.cis` to catch local syntax issues before upload.
4. Run `cist compile path/to/file.cis` to stream compile output from the cloud service.
5. Add `--deploy` when you want the cloud request to mark the compile as deployable/live.

Example contract:

```cis
use math
use compute
use risk

market_data := from data (source: "binance", symbols: ["BTC-USD"], resolution: "1m")

sma_20 := math.sma(market_data.close, 20)
signal := compute.crossover(market_data.price, sma_20)

if signal and position.size == 0:
	execute(market_buy(size: risk.calculate_size(portfolio_value: 10000)))
elif position.pnl < -100:
	execute(close_position())
```

## CLI Commands

`cist init --path <dir>`

- Creates a `contracts/` directory.
- Writes an `example.cis` starter contract if one does not already exist.

`cist validate <file.cis>`

- Checks UTF-8 decoding.
- Checks bracket and quote matching.
- Collects `use` imports and `from data (...)` occurrences.
- Reports mixed tabs/spaces as warnings.

`cist compile <file.cis> [--verbose] [--deploy]`

- Runs the same local validation first.
- Sends the contract to the configured cloud endpoint.
- Streams logs, artifacts, and errors back to the terminal.

## Configuration

The CLI reads environment variables directly and also loads them from `.env` if present.

Required for cloud compilation:

```bash
CIST_CLOUD_API_KEY=sk_live_your_api_key_here
```

Optional override:

```bash
CIST_CLOUD_ENDPOINT=https://api.cist.io/v1
```

## Build Artifacts

Build both deliverables with:

```bash
python scripts/build.py
```

Expected outputs:

- `dist/cist-*.whl`
- `cist_cli/assets/cist-*.vsix`

## Notes

- Local validation is lightweight and non-executing. It checks UTF-8 decoding, bracket matching, quote closure, `use` statements, `from data (...)` expressions, and mixed tab/space indentation.
- Cloud compilation requires `CIST_CLOUD_API_KEY`. The CLI also reads `.env` automatically if present.
- The VS Code grammar uses Python-style scope categories while adding CIST-specific handling for `use` and `from data`.
