# Repository API Module

## Overview

The `kohakuhub.api.repo` module is responsible for all repository-related operations in KohakuHub. It provides a comprehensive set of endpoints for creating, deleting, moving, and inspecting repositories, as well as browsing their file trees. This module is a cornerstone of the Hugging Face API compatibility layer.

## Key Features

- **Repository Lifecycle Management**: Endpoints for creating, deleting, and moving/renaming repositories.
- **Repository Inspection**: Retrieve detailed information about a repository, including its files, commit history, and storage usage.
- **File Tree Browsing**: List the contents of a repository at a specific revision, with support for recursive listing.
- **Garbage Collection**: Utilities for cleaning up unreferenced LFS objects and other repository-related storage.
- **Hugging Face Compatibility**: A utility sub-module (`hf.py`) provides helper functions for generating Hugging Face-compatible error responses and data formats.

## Module Structure

- **`routers/`**: Contains the FastAPI routers that define the API endpoints.
  - **`crud.py`**: Handles repository creation, deletion, and moving (`/repos/create`, `/repos/delete`, `/repos/move`).
  - **`info.py`**: Provides endpoints for listing repositories and retrieving detailed information about a specific repository.
  - **`tree.py`**: Implements file tree browsing and path information endpoints.
- **`utils/`**: Contains utility functions supporting the repository operations.
  - **`gc.py`**: Implements the logic for garbage collecting old LFS objects and cleaning up storage when a repository is deleted or moved.
  - **`hf.py`**: A crucial component for Hugging Face compatibility, providing functions to generate error responses with the specific headers and error codes that `huggingface_hub` client expects.

## How It Works

### Repository Creation
When a new repository is created, a corresponding repository is also created in LakeFS. The metadata, such as the owner and privacy status, is stored in the local database.

### Repository Deletion
Deleting a repository is an irreversible operation that involves:
1.  Cleaning up all associated S3 storage, including LFS objects (with checks to avoid deleting objects still used by other repositories).
2.  Deleting the repository from LakeFS.
3.  Deleting the repository's metadata from the local database.

### File Tree Browsing
The file tree is generated by listing objects in the corresponding LakeFS repository at a given revision. The module enriches this information with metadata from the local database, such as LFS details.

## API Endpoints

### CRUD
- `POST /repos/create`: Create a new repository.
- `DELETE /repos/delete`: Delete a repository.
- `POST /repos/move`: Move or rename a repository.
- `POST /repos/squash`: Squash a repository's history.

### Info
- `GET /models/{namespace}/{repo_name}`: Get information about a model repository.
- `GET /datasets/{namespace}/{repo_name}`: Get information about a dataset repository.
- `GET /spaces/{namespace}/{repo_name}`: Get information about a space repository.
- `GET /models`, `/datasets`, `/spaces`: List repositories of a specific type.
- `GET /users/{username}/repos`: List all repositories for a user or organization.

### Tree
- `GET /{repo_type}s/{namespace}/{repo_name}/tree/{revision}`: List the file tree of a repository at a specific revision.
- `POST /{repo_type}s/{namespace}/{repo_name}/paths-info/{revision}`: Get information about specific paths in a repository.