speclink 0.1.0

Keep documentation and code in sync using LLMs

Speclink 🔗

Speclink keeps your documentation and code in perfect harmony using LLMs. It automatically maps documentation sections to relevant code and synchronizes them when changes occur.

Key Features

• Auto-Mapping: Analyzes your repository to link documentation paragraphs with the exact code symbols they describe.
• Incremental Sync: Only updates the parts of your documentation affected by recent code changes.
• GitHub Action Integration: Automates the synchronization process in your CI/CD pipeline.
• AI-Powered: Leverages LLMs (OpenAI, Anthropic) and Rerankers (Cohere) for high-precision context retrieval.

Installation

pip install speclink

Quick Start

1. Initialize Speclink

Run the wizard to select which documentation files you want to track.

speclink scope

This will:

• Create a .speclink/ configuration directory.
• Generate a .github/workflows/speclink-sync.yml for automated syncs.

2. Configure Environment

Create a .env file or set environment variables. Speclink uses LiteLLM, which means it supports over 100+ providers (OpenAI, Anthropic, Mistral, Ollama, etc.).

LLM_API_KEY=your_key
LLM_MODEL=gpt-4o  # or anthropic/claude-3-5-sonnet, mistral/mistral-large, etc.
RERANK_API_KEY=your_key
RERANK_MODEL=cohere/rerank-v3.5

Check the LiteLLM Supported Providers for the full list of model strings.

3. Initial Analysis & Commit

Generate the initial mapping and push it to your repository to enable automation.

speclink analyze
git add .speclink/ .github/
git commit -m "chore: initialize speclink"
git push

4. Continuous Sync (Automation)

Once committed, you don't need to run manual commands. The GitHub Action will:

1. Trigger on every Pull Request.
2. Re-analyze the repository to update the doc-map (incremental).
3. Synchronize your documentation with any detected code changes.
4. Commit both updated docs and the doc-map back to your branch.

How it works

1. Scope: You define which .md files are the "Source of Truth".
2. Analyze: Speclink parses your code (using tree-sitter) and uses a Reranker to find which files/functions relate to each documentation paragraph.
3. Sync: When code changes, Speclink identifies the affected doc sections, feeds the new code context to an LLM, and rewrites the documentation to match the new reality.

Development

Requires Python 3.12+.

git clone https://github.com/lacatu5/speclink.git
cd speclink
pip install -e .

License

MIT