Metadata-Version: 2.4
Name: cist-kernel
Version: 0.0.34
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-kernel` Python package — the CLI, the syntax validator, and the cloud compiler client.
- A VS Code extension bundled inside the package — `cist init` installs it into your local VS Code extensions folder.
- A build orchestrator (`scripts/build.py`) for cutting releases.

## 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

└── extensions/
	├── README.md
	├── package.json
	├── language-configuration.json
	└── syntaxes/
		└── cis.tmLanguage.json
```

## Getting Started

```bash
python -m pip install --upgrade cist-kernel
cist init
```

If `cist` is not on your PATH yet, use the fallback:

```bash
python -m cist_cli
```

Works on Windows, macOS, and Linux immediately after install — no extra tools. Running `python -m cist_cli` with no arguments automatically runs `init`.

If you installed an older release already, the `--upgrade` matters. Plain `pip install cist-kernel` will keep the old version and will not add the newer `python -m cist_cli` entrypoint.

After `init` runs, if `cist` isn't yet on your PATH it will print the exact one-liner to fix it permanently. Once you've done that (and reopened your terminal), you can use the short form for everything:

```bash
cist compile contracts/my_strategy.cis
```

`init` creates a workspace, writes a `.env` config file, removes the broken legacy CIST extension if present, and installs the bundled VS Code syntax extension. If you want to re-run only the extension step later, use `python -m cist_cli sync-vscode-extension`, or `cist sync-vscode-extension` after PATH is configured.

Add `--deploy` to mark a build as live:

```bash
cist compile contracts/my_strategy.cis --deploy
```

## How To Use CIST

1. `python -m pip install --upgrade cist-kernel` — install the latest release.
2. `cist init` — preferred first run. If `cist` is not on PATH yet, use `python -m cist_cli` instead. No args = auto-runs `init`.
3. Add your `CIST_CLOUD_API_KEY` to the generated `.env`.
4. Write `.cis` files in `contracts/`.
5. `cist compile <file.cis>` — validates syntax locally, then streams compilation output from the cloud.

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 Reference

**`cist init [--path <dir>]`**
- Creates `contracts/` and `example.cis`.
- Writes a `.env` stub with `CIST_CLOUD_API_KEY` placeholder.
- Removes the broken legacy `tooig research lab.cist` extension if it exists.
- Installs the bundled `.cis` VS Code extension into your local extensions folder.

**`cist sync-vscode-extension`**
- Re-installs or updates the bundled `.cis` VS Code extension.
- Uses the latest bundled VSIX from `cist_cli/assets/`.
- Fails with a clear message if the bundled VSIX is missing or the extensions folder cannot be written.

**`cist compile <file.cis> [--deploy] [--verbose]`**
- Validates syntax locally first (bracket matching, `use` imports, `from data` expressions, encoding).
- Streams compilation logs, artifacts, and errors from the cloud compiler.
- `--deploy` flags the build as ready for live execution.
- `--verbose` prints detected modules and data stream count.

## 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_kernel-*.whl`

During the build, a `.vsix` is created temporarily so it can be bundled into the wheel. The local build script removes that generated `.vsix` afterward, so it does not stay in the repo.

## 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`.
