Skip to content

python-api.md

Latest commit

 

History

History
96 lines (67 loc) · 2.78 KB

python-api.md

File metadata and controls

96 lines (67 loc) · 2.78 KB

Python API

code2skill can be used as a Python package as well as a CLI.

The Python API follows the same workflow-oriented product model as the CLI: build configuration around a repository root, run one of the repository workflows, then optionally adapt generated Skill artifacts into downstream tool formats.

Supported High-Level API

The supported high-level API is available from code2skill.api and re-exported from the package root:

from code2skill import adapt_repository, create_scan_config, estimate, run_ci, scan

These helpers are intended for application code and automation scripts. They are the recommended product-facing API.

Shortcut Functions

scan(...)

Run the full repository workflow and write the normal artifact bundle.

estimate(...)

Run the report-only preview path. This writes report.json but does not write Skills or state.

run_ci(...)

Run the automation-oriented path that can choose between full and incremental execution.

adapt_repository(...)

Adapt generated Skills into one or more target instruction-file formats under the target repository root.

Config Builder

Use create_scan_config(...) when you need direct control over ScanConfig before calling lower-level functions such as:

from code2skill import create_scan_config, run_ci_repository

config = create_scan_config(
    repo_path="/path/to/repo",
    command="ci",
    mode="auto",
    output_dir=".code2skill",
    base_ref="origin/main",
)
result = run_ci_repository(config)

Path Semantics

create_scan_config(...) treats repo_path as the repository root.

  • Relative output_dir values are resolved from repo_path
  • Relative report_path, diff_file, and pricing_file values are resolved from repo_path
  • Relative source_dir values passed to adapt_repository(...) are resolved from repo_path
  • If report_path is omitted, it defaults to output_dir/report.json

Returned Results

The pipeline functions return ScanExecution, which includes:

  • repo_path
  • output_dir
  • output_files
  • candidate_count
  • selected_count
  • total_chars
  • run_mode
  • changed_files
  • affected_files
  • affected_skills
  • generated_skills
  • report_path
  • report

The lower-level config and report dataclasses are also exported from the package root. The package root also exports the new artifact and summary contracts used by the workflow-oriented surface:

from code2skill import (
    ArtifactLayout,
    CommandRunSummary,
    PricingConfig,
    RunOptions,
    ScanConfig,
    ScanExecution,
    ScanLimits,
)

Incremental-State Safety

Incremental state is reused only when the saved snapshot belongs to the same resolved repository root. Invalid or damaged state files are treated as missing state and fall back safely.