use std::path::PathBuf;
use clap::Args;
use serde::Serialize;
use super::apply::{self, ApplyOptions, ApplyReport};
use super::error::AiError;
use super::model::{ModelId, DEFAULT_MODEL};
use super::plan::{Completer, Plan};
use super::view::DocumentView;
pub const ABOUT: &str = "Local AI that drives blackline: a prompt becomes native OOXML edits";
pub const AFTER_HELP: &str = "The model never writes OOXML. It emits a small op list; blackline applies it.\n\
DOCX ops become Word tracked changes (pass --author). XLSX and PPTX are silent edits.\n\n\
Default model is quantized Phi-3 mini 4k (Kalosm). Override with --model.\n\
First run downloads the GGUF into the Kalosm cache. On Apple Silicon\n\
(`--features metal`) inference is llama.cpp Metal (all layers on the\n\
GPU). Elsewhere Kalosm owns the tensors and drops them after the plan.\n\
`bl ai --clear-cache` deletes the GGUFs.\n\n\
You do not pass paragraph indexes. Phrases in the instruction select\n\
the view (`change thirty days to sixty days` looks up that text;\n\
`change title to …` is the first paragraph). `every paragraph` /\n\
`throughout the document` walks the file in chunks. `--from` / `--to`\n\
is an optional override, same index space as `bl docx view`.\n\n\
Apply is best-effort by default: leftover model ops are reported and\n\
the rest still writes. `--strict` aborts on the first miss (same as\n\
`bl docx edit`). Default stderr is a few status lines; `--verbose`\n\
prints fetch, unload, and every apply op. `--json` is the full report.\n\n\
Examples:\n \
bl ai contract.docx \"change thirty days to sixty days\" -o out.docx --author \"Jane Doe\"\n \
bl ai model.xlsx \"set B2 to 42\" --in-place --model llama3.2-1b\n \
bl ai deck.pptx \"set the title to Q3\" -o out.pptx --model ./phi.gguf\n \
bl ai contract.docx \"flag the indemnity clause\" --dry-run --json --author Jane\n \
bl ai --clear-cache";
#[derive(Args, Debug)]
pub struct AiArgs {
#[arg(required_unless_present = "clear_cache")]
pub file: Option<PathBuf>,
#[arg(required_unless_present = "clear_cache")]
pub instruction: Option<String>,
#[arg(short, long)]
pub output: Option<PathBuf>,
#[arg(long)]
pub in_place: bool,
#[arg(long)]
pub author: Option<String>,
#[arg(long, default_value = DEFAULT_MODEL)]
pub model: String,
#[arg(long)]
pub dry_run: bool,
#[arg(long)]
pub json: bool,
#[arg(long)]
pub no_track: bool,
#[arg(long)]
pub strict: bool,
#[arg(long, hide = true)]
pub lenient: bool,
#[arg(long, default_value = "word")]
pub granularity: String,
#[arg(long)]
pub from: Option<usize>,
#[arg(long)]
pub to: Option<usize>,
#[arg(long)]
pub sheet: Option<String>,
#[arg(long, short)]
pub verbose: bool,
#[arg(long)]
pub clear_cache: bool,
}
#[derive(Debug, Serialize)]
pub struct AiReport {
pub format: super::format::Format,
pub model: String,
pub plan: Plan,
pub apply: ApplyReport,
#[serde(skip_serializing_if = "Option::is_none")]
pub output: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub cache: Option<super::cache::ClearCacheReport>,
}
pub fn run_args(args: AiArgs) -> Result<(), AiError> {
tokio::runtime::Builder::new_multi_thread()
.enable_all()
.build()
.expect("tokio")
.block_on(run_cli(args))
}
async fn run_cli(cli: AiArgs) -> Result<(), AiError> {
match (&cli.file, &cli.instruction, cli.clear_cache) {
(None, None, true) => return print_clear(cli.json),
(Some(_), Some(_), _) => {}
_ => {
return Err(AiError::usage(
"pass FILE INSTRUCTION, or --clear-cache with no file".to_string(),
));
}
}
let file = cli.file.as_deref().expect("file present");
let instruction = read_instruction(cli.instruction.as_deref().expect("instruction present"))?;
if instruction.trim().is_empty() {
return Err(AiError::usage("instruction is empty".to_string()));
}
let output = apply::resolve_output(file, cli.output.as_deref(), cli.in_place, cli.dry_run)?;
let granularity = parse_granularity(&cli.granularity)?;
let author = resolve_author(cli.author.as_deref())?;
let model_id = ModelId::parse(&cli.model)?;
let views = DocumentView::windows(
file,
cli.from,
cli.to,
cli.sheet.as_deref(),
Some(instruction.as_str()),
)?;
let view_lines: usize = views.iter().map(|v| v.lines.len()).sum();
if cli.verbose {
let prompt_chars: usize = views.iter().map(DocumentView::prompt_chars).sum();
eprintln!(
"view {} line(s) in {} chunk(s) {} prompt chars",
view_lines,
views.len(),
prompt_chars
);
} else if views.len() > 1 {
eprintln!("view {} line(s) in {} chunk(s)", view_lines, views.len());
} else {
eprintln!("view {view_lines} line(s)");
}
let format = views
.first()
.expect("windows always returns at least one view")
.format;
if format == super::format::Format::Docx && !cli.no_track && author.is_none() {
return Err(AiError::usage(
"author required: tracked changes and comments must carry an explicit author \
(pass --author or set BLACKLINE_AUTHOR)"
.to_string(),
));
}
let plan = complete_with_model(&model_id, &views, &instruction, cli.verbose).await?;
let opts = ApplyOptions {
author,
granularity,
no_track: cli.no_track,
lenient: !cli.strict,
dry_run: cli.dry_run,
};
let _ = cli.lenient;
let apply_report = apply::apply(file, output.as_deref(), &plan, &opts)?;
let cache = if cli.clear_cache {
Some(super::cache::clear_cache()?)
} else {
None
};
let report = AiReport {
format,
model: model_id.as_str(),
plan,
apply: apply_report,
output: output.map(|p| p.display().to_string()),
cache,
};
if cli.json {
println!(
"{}",
serde_json::to_string_pretty(&report).map_err(|e| AiError::Io(e.to_string()))?
);
} else {
print_human(&report, cli.verbose);
if let Some(cache) = &report.cache {
eprintln!("{}", super::cache::format_clear_report(cache));
}
}
Ok(())
}
fn print_clear(json: bool) -> Result<(), AiError> {
let report = super::cache::clear_cache()?;
if json {
println!(
"{}",
serde_json::to_string_pretty(&report).map_err(|e| AiError::Io(e.to_string()))?
);
} else {
eprintln!("{}", super::cache::format_clear_report(&report));
}
Ok(())
}
async fn complete_with_model(
id: &ModelId,
views: &[DocumentView],
instruction: &str,
verbose: bool,
) -> Result<Plan, AiError> {
#[cfg(feature = "kalosm")]
{
let completer = super::model::load(id, verbose).await?;
let plan = completer.complete_views(views, instruction).await?;
drop(completer);
if verbose {
eprintln!("unloaded model");
}
Ok(plan)
}
#[cfg(not(feature = "kalosm"))]
{
let _ = (id, views, instruction, verbose);
Err(AiError::usage(
"this binary was built without Kalosm. Rebuild with --features kalosm:\n \
cargo install blackline --features kalosm\n \
cargo install blackline --features kalosm,metal # Apple Silicon\n \
cargo install blackline --features kalosm,cuda # NVIDIA"
.to_string(),
))
}
}
fn read_instruction(raw: &str) -> Result<String, AiError> {
if raw == "-" {
use std::io::Read;
let mut buf = String::new();
std::io::stdin()
.read_to_string(&mut buf)
.map_err(|e| AiError::Io(format!("failed to read stdin: {e}")))?;
return Ok(buf);
}
if let Some(path) = raw.strip_prefix('@') {
return std::fs::read_to_string(path)
.map_err(|e| AiError::Io(format!("failed to read {path}: {e}")));
}
Ok(raw.to_string())
}
fn parse_granularity(raw: &str) -> Result<blackline_docx::Granularity, AiError> {
match raw {
"char" => Ok(blackline_docx::Granularity::Char),
"word" => Ok(blackline_docx::Granularity::Word),
"sentence" => Ok(blackline_docx::Granularity::Sentence),
other => Err(AiError::usage(format!(
"unknown --granularity {other:?} (char | word | sentence)"
))),
}
}
fn resolve_author(flag: Option<&str>) -> Result<Option<String>, AiError> {
if let Some(a) = flag {
if !a.trim().is_empty() {
return Ok(Some(a.to_string()));
}
}
if let Ok(a) = std::env::var("BLACKLINE_AUTHOR") {
if !a.trim().is_empty() {
return Ok(Some(a));
}
}
Ok(None)
}
fn print_human(report: &AiReport, verbose: bool) {
if verbose {
eprintln!(
"{} model={} planned={} applied={} failed={} {}",
report.format,
report.model,
report.plan.ops.len(),
report.apply.applied,
report.apply.failed,
report.apply.mode
);
for op in &report.apply.ops {
eprintln!(" [{}] {} {} — {}", op.index, op.status, op.op, op.detail);
}
} else {
eprintln!(
"{} model={} applied={} failed={} {}",
report.format,
report.model,
report.apply.applied,
report.apply.failed,
report.apply.mode
);
}
if !verbose && report.apply.failed > 0 {
let preview: Vec<&str> = report
.apply
.ops
.iter()
.filter(|op| op.status == "failed")
.take(3)
.map(|op| op.detail.as_str())
.collect();
if !preview.is_empty() {
eprintln!(" {} failed: {}", report.apply.failed, preview.join("; "));
if report.apply.failed > preview.len() {
eprintln!(" pass --verbose for every op");
}
}
}
if let Some(path) = &report.output {
eprintln!("wrote {path}");
}
}
pub async fn run_with_completer<C: Completer>(
file: &std::path::Path,
instruction: &str,
output: Option<&std::path::Path>,
opts: ApplyOptions,
completer: &C,
) -> Result<AiReport, AiError> {
let view = DocumentView::open(file, None, None, None, Some(instruction))?;
let plan = completer.complete(&view, instruction).await?;
let apply_report = apply::apply(file, output, &plan, &opts)?;
Ok(AiReport {
format: view.format,
model: "static".into(),
plan,
apply: apply_report,
output: output.map(|p| p.display().to_string()),
cache: None,
})
}