Metadata-Version: 2.4
Name: skeletonpy
Version: 1.0.0
Project-URL: Homepage, https://github.com/Premik/skeletonpy
Project-URL: Repository, https://github.com/Premik/skeletonpy
Project-URL: Issues, https://github.com/Premik/skeletonpy/issues
Description-Content-Type: text/markdown
Requires-Dist: jedi
Requires-Dist: pathspec
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"

# SkeletonPy

SkeletonPy is a Python utility for code analysis and summarization. It parses Python source code to generate a compact overview, which is particularly useful for reducing the context size when working with Large Language Models (LLMs). By providing a summarized version of the code, it helps improve the performance of AI-assisted coding and reduces token usage.

## Motivation

SkeletonPy is designed as a fast, pure code-driven alternative to complex local indexers (like those used in Continue or Cursor) for developers who want a lightweight, zero-overhead solution. It serves as an companion for Agentic Frameworks (by providing them with a highly accurate map of your Python repository.

Why use SkeletonPy over full-context stuffing or maintaining local indexes?

* **Zero Overhead Code Mapping:** Code changes frequently during development. Instead of maintaining complex embeddings, local vector databases, or dealing with expensive re-indexing processes, SkeletonPy runs instantly and entirely locally without LLMs.
* **Focused Context:** Pumping entire repositories into the prompt window often leads to the "lost in the middle" phenomenon, where models overlook pieces of the context. A concise skeleton limits irrelevant information, which helps smaller local models and large models alike focus on what actually matters.
* **Cost and Speed:** Passing a compact skeleton instead of full source files means significantly fewer input tokens. This directly translates to lower API costs and faster responses.
* **Perfect for Agentic Workflows:** The generated summary contains original file names and precise line numbers down to class-level resolution.

![side_by_side_example](doc/example-sbs.png)

## Quick Start

From your project's root directory, run `skeletonpy` with the path to your source code (`src`):

```bash
uvx skeletonpy src
```

This will scan all Python files in the `src` directory and create a `skeleton.txt` file inside it. You can then append the content of this file to your LLM prompt.

## Installation

You can install `skeletonpy` from PyPI using your favorite package manager like `pip` or `uv`.

```bash
pip install skeletonpy

uv pip install skeletonpy
```

Alternatively, you can run it directly without a permanent installation:

```bash
pipx run skeletonpy -- --help

uvx skeletonpy --help
```

Once installed, you can invoke the script:
```bash
skeletonpy --help
```

## Usage

Run `skeletonpy` with the path to your source directory/directories. You can use include and exclude patterns to filter the files. The patterns are regular expressions.

For example, to process the `src` directory, including all Python files but excluding test files, and save the output to `skeleton.txt`:

```bash
skeletonpy src --exclude "_test\.py" -o main_src.txt
```

This will generate a `main_src.txt` file. If you provide an absolute or relative path as output, it will be respected.
See the [examples folder](examples/README.md) for more.
