> ## Documentation Index
> Fetch the complete documentation index at: https://lunr-f6858e75.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# API introduction

> Use HelixCommit programmatically in your Python applications

<Note>
  The Python API gives you full control over the release note generation process, allowing custom workflows and integration with other tools.
</Note>

## When to use the Python API

<CardGroup cols={2}>
  <Card title="Custom automation" icon="robot" color="#0A6ACB">
    Build custom release workflows tailored to your team's needs
  </Card>

  <Card title="Integration" icon="plug" color="#F26419">
    Integrate release notes into existing Python applications
  </Card>

  <Card title="Advanced customization" icon="sliders" color="#F6A02D">
    Customize formatting, filtering, and processing beyond CLI options
  </Card>

  <Card title="Programmatic control" icon="code" color="#0A6ACB">
    Generate notes from within your application or script
  </Card>
</CardGroup>

***

## Quick example

Here's a minimal example to get you started:

```python theme={}
from datetime import datetime
from pathlib import Path
from helixcommit.changelog import ChangelogBuilder
from helixcommit.formatters.markdown import render_markdown
from helixcommit.git_client import CommitRange, GitRepository

# Initialize repository
repo = GitRepository(Path("."))

# Define commit range
commit_range = CommitRange(since="v1.0.0", until="v2.0.0")

# Get commits
commits = list(repo.iter_commits(commit_range))

# Build changelog
builder = ChangelogBuilder(include_scopes=True)
changelog = builder.build(
    version="v2.0.0",
    release_date=datetime.now(),
    commits=commits,
    commit_prs={},
    pr_index={}
)

# Render to markdown
markdown = render_markdown(changelog)
print(markdown)
```

<Check>
  This example generates release notes for commits between two tags without any external dependencies.
</Check>

***

## Core modules

<CardGroup cols={2}>
  <Card title="git_client" icon="code-branch" href="/api-reference/git-client" color="#0A6ACB">
    Interface with Git repositories and commit history
  </Card>

  <Card title="changelog" icon="list" href="/api-reference/changelog" color="#F26419">
    Build and structure changelog data
  </Card>

  <Card title="formatters" icon="file-export" href="/api-reference/formatters" color="#F6A02D">
    Render changelogs in different formats
  </Card>

  <Card title="Python API" icon="python" href="/api-reference/python-api" color="#0A6ACB">
    Complete API reference and examples
  </Card>
</CardGroup>

***

## Installation

Install HelixCommit via pip:

```bash theme={}
pip install helixcommit
```

Import the modules you need:

```python theme={}
# Core modules
from helixcommit.git_client import GitRepository, CommitRange
from helixcommit.changelog import ChangelogBuilder
from helixcommit.formatters import markdown, html, text

# Advanced features
from helixcommit.github_client import GitHubClient, GitHubSettings
from helixcommit.summarizer import PromptEngineeredSummarizer
from helixcommit.models import Changelog, CommitInfo
```

***

## Basic workflow

<Steps>
  <Step title="Initialize Git repository" icon="folder-open">
    ```python theme={}
    from pathlib import Path
    from helixcommit.git_client import GitRepository

    repo = GitRepository(Path("."))  # Current directory
    # or
    repo = GitRepository(Path("/path/to/repo"))
    ```
  </Step>

  <Step title="Define commit range" icon="code-branch">
    ```python theme={}
    from helixcommit.git_client import CommitRange

    # Between tags
    commit_range = CommitRange(since="v1.0.0", until="v2.0.0")

    # Unreleased changes
    commit_range = CommitRange(since="v1.0.0", until="HEAD")

    # With filtering
    commit_range = CommitRange(
        since="v1.0.0",
        until="HEAD",
        include_merges=False,
        max_count=100
    )
    ```
  </Step>

  <Step title="Fetch commits" icon="download">
    ```python theme={}
    commits = list(repo.iter_commits(commit_range))
    print(f"Found {len(commits)} commits")
    ```
  </Step>

  <Step title="Build changelog" icon="hammer">
    ```python theme={}
    from datetime import datetime
    from helixcommit.changelog import ChangelogBuilder

    builder = ChangelogBuilder(include_scopes=True)
    changelog = builder.build(
        version="v2.0.0",
        release_date=datetime.now(),
        commits=commits,
        commit_prs={},
        pr_index={}
    )
    ```
  </Step>

  <Step title="Render output" icon="file-export">
    ```python theme={}
    from helixcommit.formatters.markdown import render_markdown

    # Generate markdown
    output = render_markdown(changelog)
    print(output)

    # Save to file
    Path("RELEASE_NOTES.md").write_text(output)
    ```
  </Step>
</Steps>

***

## Advanced features

### GitHub integration

Enrich changelogs with pull request data:

```python theme={}
from helixcommit.github_client import GitHubClient, GitHubSettings

# Initialize GitHub client
settings = GitHubSettings(
    owner="username",
    repo="repository",
    token="ghp_..."  # Optional, improves rate limits
)
client = GitHubClient(settings)

# Fetch PR data
pr_index = {}
commit_prs = {}

for commit in commits:
    if commit.pr_number:
        pr = client.get_pull_request(commit.pr_number)
        if pr:
            pr_index[commit.pr_number] = pr

# Use enriched data in changelog
changelog = builder.build(
    version="v2.0.0",
    release_date=datetime.now(),
    commits=commits,
    commit_prs=commit_prs,
    pr_index=pr_index
)
```

### AI summarization

Add AI-powered summaries:

```python theme={}
from helixcommit.summarizer import PromptEngineeredSummarizer

# Initialize AI summarizer
summarizer = PromptEngineeredSummarizer(
    api_key="sk-...",
    model="gpt-4o-mini",
    cache_path=Path(".cache/summaries.json"),
    domain_scope="software release notes",
    expert_roles=["Product Manager", "Tech Lead"],
    rag_backend="simple"
)

# Use with changelog builder
builder = ChangelogBuilder(
    summarizer=summarizer,
    include_scopes=True
)

# AI summaries are automatically generated
changelog = builder.build(
    version="v2.0.0",
    release_date=datetime.now(),
    commits=commits,
    commit_prs={},
    pr_index={}
)
```

### Custom formatting

Create custom output formatters:

```python theme={}
from helixcommit.models import Changelog

def custom_formatter(changelog: Changelog) -> str:
    """Generate custom release notes format."""
    lines = [
        f"# Release {changelog.version}",
        f"Released: {changelog.release_date.strftime('%Y-%m-%d')}",
        ""
    ]
    
    for section in changelog.sections:
        lines.append(f"## {section.title}")
        for item in section.items:
            lines.append(f"- {item.description} ({item.commit_sha[:7]})")
        lines.append("")
    
    return "\n".join(lines)

# Use custom formatter
output = custom_formatter(changelog)
```

***

## Type hints and IDE support

HelixCommit is fully typed with type hints for excellent IDE support:

```python theme={}
from helixcommit.git_client import GitRepository, CommitRange
from helixcommit.models import CommitInfo, Changelog
from typing import List

def generate_notes(repo_path: str, since: str, until: str) -> str:
    """Generate release notes with full type safety."""
    repo: GitRepository = GitRepository(Path(repo_path))
    commit_range: CommitRange = CommitRange(since=since, until=until)
    commits: List[CommitInfo] = list(repo.iter_commits(commit_range))
    
    # IDE provides autocomplete and type checking
    builder = ChangelogBuilder()
    changelog: Changelog = builder.build(
        version=until,
        release_date=datetime.now(),
        commits=commits
    )
    
    return render_markdown(changelog)
```

***

## Error handling

Handle errors gracefully:

```python theme={}
from helixcommit.git_client import GitRepository
from helixcommit.github_client import GitHubApiError, GitHubRateLimitError

try:
    # Initialize repository
    repo = GitRepository(Path("/path/to/repo"))
    commits = list(repo.iter_commits(commit_range))
    
    # GitHub operations
    client = GitHubClient(settings)
    pr = client.get_pull_request(123)
    
except FileNotFoundError:
    print("Error: Git repository not found")
except GitHubRateLimitError as e:
    print(f"Rate limit exceeded. Resets at: {e.reset_time}")
except GitHubApiError as e:
    print(f"GitHub API error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")
```

***

## Next steps

<CardGroup cols={2}>
  <Card title="Python API reference" icon="book" href="/api-reference/python-api" color="#0A6ACB">
    Complete API documentation
  </Card>

  <Card title="Git client" icon="code-branch" href="/api-reference/git-client" color="#F26419">
    Working with Git repositories
  </Card>

  <Card title="Changelog builder" icon="list" href="/api-reference/changelog" color="#F6A02D">
    Building and structuring changelogs
  </Card>

  <Card title="Formatters" icon="file-export" href="/api-reference/formatters" color="#0A6ACB">
    Rendering output in different formats
  </Card>
</CardGroup>