Alys CLI

Alys is the terminal-native runtime for autonomous AI data preparation.

npm install -g alys-akusa
alys prepare ./company-docs

Or run without installing:

npx alys-akusa prepare ./company-docs
npx alys-akusa audit ./knowledge-base
npx alys-akusa media-debug ./call-recordings
npx alys-akusa debug-artifact ~/Alys/prepared/run_id
npx alys-akusa media-transcribe-plan ./call-recordings --gcs-input gs://bucket/in --gcs-output gs://bucket/out
npx alys-akusa simulate-rag ./knowledge-base
npx alys-akusa improve ./knowledge-base
npx alys-akusa benchmark ./knowledge-base
npx alys-akusa ingest ./knowledge-base
npx alys-akusa finetune-ready ./support-tickets

Alys turns messy local knowledge into OpenAI fine-tuning JSONL, Anthropic instruction records, RAG chunks, QA datasets, eval datasets, embeddings-ready corpora, media manifests, SHA-256 fingerprints, timestamped and redacted segment rows, dataset cards, redaction reviews, and debug reports for transcript-backed audio/video assets, Google Speech-to-Text V2 transcription plans, GCS upload manifests, BatchRecognize request JSON, VTT/SRT import maps, source lists, AI readiness reports, and artifact debug reports for already-prepared runs.

What It Does

messy knowledge
  -> ingestion
  -> parsing
  -> chunking
  -> deduplication
  -> semantic grouping
  -> grounding
  -> evaluation
  -> AI-ready exports

Local preparation writes artifacts under ~/Alys/prepared/{run_id} and does not require users to bring model API keys. Retrieval simulation writes retrieval-simulation.json and retrieval-simulation.md with hit rate, overlap failures, weak boundaries, unsupported-answer risk, and hallucination risk. Improve writes a safe optimized copy under ~/Alys/improved/{run_id} with improved-rag-chunks.jsonl, cleaned-corpus.md, and an improvement report. It does not mutate original source files. Benchmark writes knowledge-benchmark.json and knowledge-benchmark.md under ~/Alys/benchmarks/{run_id} to compare original vs improved retrieval behavior, answer support, grounding, hallucination risk, and regressions. Artifact debug reads an existing prepared output folder or report JSON and writes artifact-debug-report.json plus artifact-debug-report.md under ~/Alys/artifact-debug/{run_id}. Use it when you want Alys to inspect local media/debug artifacts instead of running hosted source-gated topic generation.

Local Development

Do not publish to npm for normal testing. Use the repo CLI directly first:

pnpm install
pnpm alys -- audit ./knowledge-base --yes
pnpm alys -- media-debug ./call-recordings --yes
pnpm alys -- debug-artifact ~/Alys/prepared/run_id --yes
pnpm alys -- media-transcribe-plan ./call-recordings --google-project my-gcp-project --gcs-input gs://bucket/alys-media-input --gcs-output gs://bucket/alys-media-output --yes
pnpm alys -- simulate-rag ./knowledge-base --queries 12 --top-k 5 --yes
pnpm alys -- improve ./knowledge-base --yes
pnpm alys -- benchmark ./knowledge-base --queries 16 --top-k 5 --yes
pnpm alys -- prepare ./docs --profile all --yes
pnpm alys -- ingest ./knowledge-base --profile rag,embeddings,eval --yes
pnpm alys -- finetune-ready ./tickets --profile openai,anthropic,qa --yes

Recommended pre-publish loop:

pnpm cli:test
pnpm cli:smoke:local
pnpm cli:pack

pnpm cli:smoke:local does not call the hosted generation API. It audits the repo docs folder and writes disposable artifacts to ./.alys-test.

Use the API smoke only when you explicitly want to test the live hosted generation path with a tiny run:

pnpm cli:smoke:api

Only after those pass should you publish:

cd apps/cli
npm publish --access public