feat: add CLI entrypoint and doctor command

This commit is contained in:
Ilgiz Kamelyev 2026-05-28 13:40:43 +05:00
parent 788e7d26b6
commit 4f2013de90
13 changed files with 336 additions and 25 deletions

13
.gitignore vendored
View File

@ -11,4 +11,15 @@ dist/
*.log
.env
.DS_Store
data/*
!data/.gitkeep
input/calls/*
!input/calls/.gitkeep
models/*
!models/.gitkeep
output/*
!output/.gitkeep
spool/*
!spool/.gitkeep
logs/*
!logs/.gitkeep

View File

@ -8,7 +8,18 @@ Repository skeleton for the local call-processing pipeline.
- SQLite state tracking
- Validation, spool, transcription, classification, export
## Development environment
Use the project virtual environment for development and runtime:
```bash
python -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/b24calls doctor
```
The configuration example uses absolute filesystem paths. If you create a custom config, keep path values absolute as well.
## Current status
Only the project skeleton is initialized. Implementation starts in later steps of `IMPLEMENTATION_PLAN.md`.

View File

@ -2,13 +2,13 @@
level = "INFO"
console = true
structured = true
file = "./logs/b24calls.log"
file = "/home/ilgiz/projects/b24calls/logs/b24calls.log"
[paths]
spool_dir = "./spool"
output_dir = "./output"
log_dir = "./logs"
database_path = "./data/b24calls.sqlite3"
spool_dir = "/home/ilgiz/projects/b24calls/spool"
output_dir = "/home/ilgiz/projects/b24calls/output"
log_dir = "/home/ilgiz/projects/b24calls/logs"
database_path = "/home/ilgiz/projects/b24calls/data/b24calls.sqlite3"
[runtime]
device = "auto"
@ -16,12 +16,12 @@ allow_cuda = true
compute_type = "default"
[models]
directory = "./models"
directory = "/home/ilgiz/projects/b24calls/models"
whisper_model = "large-v3"
download_missing = true
[local_source]
directory = "./input/calls"
directory = "/home/ilgiz/projects/b24calls/input/calls"
extensions = [".wav", ".mp3", ".m4a", ".flac", ".ogg", ".webm"]
recursive = true

1
data/.gitkeep Normal file
View File

@ -0,0 +1 @@
# Placeholder to keep the data directory in git.

1
input/calls/.gitkeep Normal file
View File

@ -0,0 +1 @@
# Placeholder to keep the input/calls directory in git.

1
logs/.gitkeep Normal file
View File

@ -0,0 +1 @@
# Placeholder to keep the logs directory in git.

1
models/.gitkeep Normal file
View File

@ -0,0 +1 @@
# Placeholder to keep the models directory in git.

1
output/.gitkeep Normal file
View File

@ -0,0 +1 @@
# Placeholder to keep the output directory in git.

View File

@ -13,9 +13,11 @@ authors = [
]
license = { text = "Proprietary" }
[project.scripts]
b24calls = "b24calls.cli:main"
[tool.setuptools]
package-dir = {"" = "src"}
[tool.setuptools.packages.find]
where = ["src"]

1
spool/.gitkeep Normal file
View File

@ -0,0 +1 @@
# Placeholder to keep the spool directory in git.

51
src/b24calls/cli.py Normal file
View File

@ -0,0 +1,51 @@
from __future__ import annotations
import argparse
from pathlib import Path
from typing import Sequence
from .doctor import run_doctor
def _build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(prog="b24calls", description="B24 Call Pipeline")
parser.add_argument(
"--config",
type=Path,
default=None,
help="Path to TOML config file",
)
parser.add_argument(
"--env",
type=Path,
default=None,
help="Path to .env file",
)
subparsers = parser.add_subparsers(dest="command", required=True)
subparsers.add_parser("doctor", help="Validate runtime environment")
subparsers.add_parser("discover", help="Discover source files (placeholder)")
subparsers.add_parser("process", help="Process files end-to-end (placeholder)")
subparsers.add_parser("run-once", help="Run a single pipeline pass (placeholder)")
subparsers.add_parser("export", help="Export artifacts (placeholder)")
return parser
def _placeholder(command: str) -> int:
print(f"{command} is not implemented yet")
return 2
def main(argv: Sequence[str] | None = None) -> int:
parser = _build_parser()
args = parser.parse_args(argv)
if args.command == "doctor":
return run_doctor(config_path=args.config, env_path=args.env)
if args.command in {"discover", "process", "run-once", "export"}:
return _placeholder(args.command)
parser.error(f"unknown command: {args.command}")
return 2

View File

@ -151,6 +151,15 @@ def _resolve_path(value: Any, base_dir: Path) -> Path | None:
return path.resolve()
def _resolve_absolute_path(value: Any, label: str) -> Path | None:
if value is None or value == "":
return None
path = Path(str(value)).expanduser()
if not path.is_absolute():
raise ConfigError(f"{label} must be an absolute path: {value}")
return path.resolve()
def _resolve_required_path(value: Any, base_dir: Path, default: Path) -> Path:
resolved = _resolve_path(value, base_dir)
if resolved is None:
@ -208,9 +217,9 @@ def load_settings(
logging_config = LoggingConfig(
level=str(os.environ.get("B24CALLS_LOG_LEVEL", logging_section.get("level", "INFO"))).upper(),
console=_parse_bool(os.environ.get("B24CALLS_LOG_CONSOLE"), bool(logging_section.get("console", True))),
file=_resolve_path(
file=_resolve_absolute_path(
os.environ.get("B24CALLS_LOG_FILE", logging_section.get("file")),
project_root,
"logging.file",
),
structured=_parse_bool(
os.environ.get("B24CALLS_LOG_STRUCTURED"),
@ -220,24 +229,36 @@ def load_settings(
paths_config = PathsConfig(
spool_dir=_resolve_required_path(
os.environ.get("B24CALLS_SPOOL_DIR", paths_section.get("spool_dir")),
_resolve_absolute_path(
os.environ.get("B24CALLS_SPOOL_DIR", paths_section.get("spool_dir")),
"paths.spool_dir",
),
project_root,
PathsConfig.spool_dir,
(project_root / PathsConfig.spool_dir).resolve(),
),
output_dir=_resolve_required_path(
os.environ.get("B24CALLS_OUTPUT_DIR", paths_section.get("output_dir")),
_resolve_absolute_path(
os.environ.get("B24CALLS_OUTPUT_DIR", paths_section.get("output_dir")),
"paths.output_dir",
),
project_root,
PathsConfig.output_dir,
(project_root / PathsConfig.output_dir).resolve(),
),
log_dir=_resolve_required_path(
os.environ.get("B24CALLS_LOG_DIR", paths_section.get("log_dir")),
_resolve_absolute_path(
os.environ.get("B24CALLS_LOG_DIR", paths_section.get("log_dir")),
"paths.log_dir",
),
project_root,
PathsConfig.log_dir,
(project_root / PathsConfig.log_dir).resolve(),
),
database_path=_resolve_required_path(
os.environ.get("B24CALLS_DB_PATH", paths_section.get("database_path")),
_resolve_absolute_path(
os.environ.get("B24CALLS_DB_PATH", paths_section.get("database_path")),
"paths.database_path",
),
project_root,
PathsConfig.database_path,
(project_root / PathsConfig.database_path).resolve(),
),
)
@ -252,9 +273,12 @@ def load_settings(
models_config = ModelConfig(
directory=_resolve_required_path(
os.environ.get("B24CALLS_MODELS_DIR", models_section.get("directory")),
_resolve_absolute_path(
os.environ.get("B24CALLS_MODELS_DIR", models_section.get("directory")),
"models.directory",
),
project_root,
ModelConfig.directory,
(project_root / ModelConfig.directory).resolve(),
),
whisper_model=str(os.environ.get("B24CALLS_WHISPER_MODEL", models_section.get("whisper_model", "large-v3"))),
download_missing=_parse_bool(
@ -265,9 +289,12 @@ def load_settings(
local_source_config = LocalSourceConfig(
directory=_resolve_required_path(
os.environ.get("B24CALLS_LOCAL_SOURCE_DIR", source_section.get("directory")),
_resolve_absolute_path(
os.environ.get("B24CALLS_LOCAL_SOURCE_DIR", source_section.get("directory")),
"local_source.directory",
),
project_root,
LocalSourceConfig.directory,
(project_root / LocalSourceConfig.directory).resolve(),
),
extensions=_parse_extensions(
os.environ.get("B24CALLS_LOCAL_SOURCE_EXTENSIONS", source_section.get("extensions")),
@ -306,4 +333,3 @@ def load_settings(
local_source=local_source_config,
bitrix24=bitrix24_config,
)

204
src/b24calls/doctor.py Normal file
View File

@ -0,0 +1,204 @@
from __future__ import annotations
from dataclasses import dataclass, field
from pathlib import Path
import importlib.util
import logging
import os
import platform
import shutil
import subprocess
import sys
from .config import Settings, load_settings
from .logging_setup import configure_logging
logger = logging.getLogger(__name__)
@dataclass(frozen=True)
class CheckResult:
name: str
status: str
message: str
details: dict[str, str] = field(default_factory=dict)
@property
def is_error(self) -> bool:
return self.status == "error"
@dataclass(frozen=True)
class DoctorReport:
settings: Settings
checks: tuple[CheckResult, ...]
@property
def has_errors(self) -> bool:
return any(check.is_error for check in self.checks)
def _format_path(path: Path | None) -> str:
return str(path) if path is not None else "-"
def _run_version_command(command: str) -> tuple[bool, str]:
executable = shutil.which(command)
if executable is None:
return False, f"{command} not found on PATH"
try:
completed = subprocess.run(
[executable, "-version"],
capture_output=True,
text=True,
check=True,
)
except (OSError, subprocess.CalledProcessError) as exc:
return False, f"{command} exists but failed to run: {exc}"
first_line = completed.stdout.splitlines()[0] if completed.stdout else f"{command} found"
return True, first_line.strip()
def _detect_cuda_available() -> bool:
torch_spec = importlib.util.find_spec("torch")
if torch_spec is not None:
try:
import torch # type: ignore
except Exception:
pass
else:
if hasattr(torch, "cuda"):
try:
return bool(torch.cuda.is_available())
except Exception:
return False
return shutil.which("nvidia-smi") is not None
def _check_python() -> CheckResult:
version = platform.python_version()
supported = sys.version_info >= (3, 11)
status = "ok" if supported else "error"
message = f"Python {version}"
if not supported:
message += " is below the required minimum 3.11"
return CheckResult("python", status, message, {"executable": sys.executable})
def _check_virtualenv() -> CheckResult:
in_venv = sys.prefix != getattr(sys, "base_prefix", sys.prefix) or bool(os.environ.get("VIRTUAL_ENV"))
status = "ok" if in_venv else "warn"
message = "running inside virtualenv" if in_venv else "not running inside virtualenv"
details = {"prefix": sys.prefix, "base_prefix": getattr(sys, "base_prefix", sys.prefix)}
if "VIRTUAL_ENV" in os.environ:
details["virtual_env"] = os.environ["VIRTUAL_ENV"]
return CheckResult("virtualenv", status, message, details)
def _check_command(command: str) -> CheckResult:
executable = shutil.which(command)
ok, message = _run_version_command(command)
return CheckResult(
command,
"ok" if ok else "error",
message,
{"path": _format_path(Path(executable) if executable else None)},
)
def _check_directory(path: Path, name: str, required: bool = False) -> CheckResult:
if path.exists():
if path.is_dir():
status = "ok"
message = f"{name} exists"
else:
status = "error"
message = f"{name} exists but is not a directory"
else:
status = "warn" if not required else "error"
message = f"{name} does not exist"
details = {"path": str(path)}
return CheckResult(name, status, message, details)
def _check_file_parent(path: Path, name: str) -> CheckResult:
parent = path.parent
if parent.exists() and parent.is_dir():
return CheckResult(name, "ok", f"parent directory exists for {name}", {"path": str(path), "parent": str(parent)})
return CheckResult(name, "warn", f"parent directory does not exist for {name}", {"path": str(path), "parent": str(parent)})
def _detect_runtime(settings: Settings) -> CheckResult:
cuda_available = _detect_cuda_available()
selected = "cuda" if settings.runtime.allow_cuda and cuda_available else "cpu"
status = "ok"
message = f"selected runtime: {selected}"
if settings.runtime.allow_cuda and not cuda_available:
status = "warn"
message = "cuda not available, CPU fallback will be used"
details = {
"requested_device": settings.runtime.device,
"allow_cuda": str(settings.runtime.allow_cuda).lower(),
"cuda_available": str(cuda_available).lower(),
"selected": selected,
}
return CheckResult("runtime", status, message, details)
def _build_report(settings: Settings) -> DoctorReport:
checks = (
_check_python(),
_check_virtualenv(),
_check_command("ffmpeg"),
_check_command("ffprobe"),
_check_directory(settings.local_source.directory, "local_source.directory"),
_check_directory(settings.models.directory, "models.directory"),
_check_directory(settings.paths.spool_dir, "paths.spool_dir"),
_check_directory(settings.paths.output_dir, "paths.output_dir"),
_check_directory(settings.paths.log_dir, "paths.log_dir"),
_check_file_parent(settings.paths.database_path, "paths.database_path"),
_detect_runtime(settings),
)
return DoctorReport(settings=settings, checks=checks)
def _print_report(report: DoctorReport) -> None:
settings = report.settings
print("B24 Call Pipeline doctor")
print(f"config: {settings.config_path}")
print(f"project_root: {settings.project_root}")
print(f"virtualenv: {_format_path(Path(os.environ['VIRTUAL_ENV'])) if 'VIRTUAL_ENV' in os.environ else sys.prefix}")
print(f"python: {platform.python_version()} ({sys.executable})")
print(f"models_dir: {settings.models.directory}")
print(f"source_dir: {settings.local_source.directory}")
print("")
print("Checks:")
for check in report.checks:
prefix = {
"ok": "[OK]",
"warn": "[WARN]",
"error": "[ERROR]",
}.get(check.status, "[INFO]")
print(f"{prefix} {check.name}: {check.message}")
for key, value in sorted(check.details.items()):
print(f" {key}: {value}")
def run_doctor(config_path: str | Path | None = None, env_path: str | Path | None = None) -> int:
settings = load_settings(config_path=config_path, env_path=env_path)
configure_logging(settings.logging)
logger.info("loaded settings", extra={"config_path": str(settings.config_path)})
report = _build_report(settings)
_print_report(report)
if report.has_errors:
logger.error("doctor detected fatal issues")
return 1
logger.info("doctor completed successfully")
return 0