Metadata-Version: 2.4
Name: speclink
Version: 0.1.1
Summary: Keep documentation and code in sync using LLMs
Project-URL: Homepage, https://github.com/lacatu5/speclink
Project-URL: Issues, https://github.com/lacatu5/speclink/issues
Author: lacatu5
License: MIT
License-File: LICENSE
Keywords: ai,development-tools,documentation,llm,sync
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.12
Requires-Dist: beaupy
Requires-Dist: instructor
Requires-Dist: litellm
Requires-Dist: markdown-it-py
Requires-Dist: pathspec
Requires-Dist: pydantic-settings
Requires-Dist: pydantic>=2
Requires-Dist: pyyaml
Requires-Dist: structlog
Requires-Dist: tiktoken
Requires-Dist: tree-sitter
Requires-Dist: tree-sitter-python
Requires-Dist: tree-sitter-typescript
Requires-Dist: typer
Description-Content-Type: text/markdown

# Speclink

[![Coverage](https://codecov.io/gh/lacatu5/speclink/branch/main/graph/badge.svg)](https://codecov.io/gh/lacatu5/speclink)

**Speclink** mantiene la documentación y el código sincronizados mediante LLMs. Mapea automáticamente las secciones de documentación con el código relevante y las reescribe cuando detecta cambios.

## Características principales
- **Mapeo automático**: Analiza el repositorio para vincular secciones de documentación con los símbolos de código que describen.
- **Sincronización incremental**: Solo actualiza las secciones de documentación afectadas por cambios recientes en el código.
- **Integración con GitHub Actions**: Automatiza la sincronización en el pipeline CI/CD.
- **Basado en IA**: Utiliza LLMs (OpenAI, Anthropic, etc.) y rerankers para recuperación de contexto de alta precisión.

## Instalación

```bash
pip install speclink
```

## Inicio rápido

### 1. Inicializar Speclink
Ejecutar el asistente para seleccionar los archivos de documentación a monitorizar.
```bash
speclink scope
```
Esto crea:
- Un directorio de configuración `.speclink/`.
- Un workflow `.github/workflows/speclink-sync.yml` para la sincronización automática.

### 2. Configurar entorno
Crear un archivo `.env` o definir variables de entorno. Speclink utiliza **LiteLLM**, compatible con más de 100 proveedores (OpenAI, Anthropic, Mistral, Ollama, etc.).

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

Consultar [proveedores soportados por LiteLLM](https://docs.litellm.ai/docs/providers) para la lista completa de identificadores de modelo.

### 3. Análisis inicial y commit
Generar el mapeo inicial y subirlo al repositorio para habilitar la automatización.
```bash
speclink analyze
git add .speclink/ .github/
git commit -m "chore: inicializar speclink"
git push
```

### 4. Sincronización continua (automatización)
Una vez configurado, la GitHub Action se ejecuta automáticamente en cada Pull Request:
1. **Detecta** cambios en el código.
2. **Re-analiza** el repositorio para actualizar el mapa de trazabilidad (incremental).
3. **Sincroniza** las secciones de documentación afectadas.
4. **Commitea** los cambios directamente en la rama.

## Funcionamiento
1. **Scope**: Se definen qué archivos `.md` son la fuente de verdad.
2. **Analyze**: Speclink parsea el código con `tree-sitter` y utiliza un reranker para identificar qué archivos/funciones están relacionados con cada sección de documentación.
3. **Sync**: Cuando el código cambia, Speclink identifica las secciones afectadas, proporciona el nuevo contexto al LLM y reescribe la documentación.

## Desarrollo

Requiere Python 3.12+.

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

## Licencia
MIT
