Passa al contenuto principale

Contribuire

Grazie per il tuo interesse nel contribuire a Kore Memory. Questa guida copre la configurazione dell'ambiente di sviluppo, l'esecuzione dei test, lo stile del codice e il processo di pull request.

Primi passi​

Prerequisiti​

  • Python 3.11+ (3.12 consigliato)
  • Git
  • pip o uv (consigliato per una risoluzione delle dipendenze più rapida)

Clonare e installare​

git clone https://github.com/auriti-web-design/kore-memory.git
cd kore-memory

# Installa con tutti gli extra incluse le dipendenze di sviluppo
pip install -e ".[semantic,mcp,dev]"

Oppure con uv (più veloce):

uv pip install -e ".[semantic,mcp,dev]"

Verificare la configurazione​

# Esegui la suite di test
pytest

# Avvia il server in locale
kore

# Verifica lo stato
curl http://localhost:8765/health

Struttura del progetto​

kore-memory/
├── src/
│   └── kore_memory/
│       ├── __init__.py         # Export del pacchetto
│       ├── server.py           # Applicazione FastAPI
│       ├── models.py           # Modelli Pydantic
│       ├── database.py         # Operazioni SQLite
│       ├── decay.py            # Motore di decay di Ebbinghaus
│       ├── embeddings.py       # Wrapper sentence-transformer
│       ├── importance.py       # Valutatore di importanza automatico
│       ├── compression.py      # Compressione della memoria
│       ├── security.py         # Auth, rate limiting, header
│       ├── mcp_server.py       # Server protocollo MCP
│       ├── client.py           # SDK Python sincrono
│       └── async_client.py     # SDK Python asincrono
├── tests/
│   ├── test_server.py          # Test degli endpoint API
│   ├── test_decay.py           # Test del motore di decay
│   ├── test_embeddings.py      # Test degli embedding
│   ├── test_importance.py      # Test del valutatore di importanza
│   ├── test_compression.py     # Test della compressione
│   ├── test_security.py        # Test di sicurezza
│   └── test_client.py          # Test dell'SDK
├── pyproject.toml              # Configurazione del pacchetto
├── README.md                   # README del progetto
└── LICENSE                     # Licenza MIT

Esecuzione dei test​

Suite di test completa​

pytest

Con report di copertura​

pytest --cov=kore_memory --cov-report=html
open htmlcov/index.html

File di test specifico​

pytest tests/test_decay.py

Test specifico​

pytest tests/test_decay.py::test_ebbinghaus_formula -v

Eseguire i test in parallelo​

pytest -n auto
suggerimento

I test usano un database SQLite in memoria per impostazione predefinita. Non è necessaria alcuna pulizia tra le esecuzioni.

Stile del codice​

Linting​

Kore Memory utilizza ruff per il linting e la formattazione:

# Verifica eventuali problemi
ruff check .

# Correggi automaticamente
ruff check --fix .

# Formatta il codice
ruff format .

Controllo dei tipi​

mypy src/kore_memory

Linee guida di stile​

  • Type hint ovunque -- Tutte le firme delle funzioni devono avere annotazioni di tipo complete
  • Docstring -- Tutte le funzioni e classi pubbliche devono avere docstring (stile Google)
  • Niente tipi Any -- Usa tipi specifici. Se serve flessibilità, usa generics o union
  • Modelli Pydantic -- Tutto l'input/output dell'API usa modelli Pydantic v2
  • Messaggi di errore -- I messaggi di errore rivolti all'utente devono essere chiari e utilizzabili

Esempio​

def calculate_decay(
    elapsed_days: float,
    half_life_days: float,
) -> float:
    """Calculate memory decay using the Ebbinghaus forgetting curve.

    Args:
        elapsed_days: Time since last access in days.
        half_life_days: Half-life of the memory in days.

    Returns:
        Decay score between 0.0 and 1.0.

    Raises:
        ValueError: If half_life_days is not positive.
    """
    if half_life_days <= 0:
        raise ValueError(f"half_life_days must be positive, got {half_life_days}")
    return math.exp(-elapsed_days * math.log(2) / half_life_days)

Scrivere i test​

Struttura dei test​

I test seguono il pattern Arrange-Act-Assert:

def test_save_memory_with_auto_importance(client):
    """Save a memory and verify auto-importance scoring."""
    # Arrange
    payload = {
        "content": "Always use parameterized SQL queries to prevent injection",
        "category": "decision",
    }

    # Act
    response = client.post("/save", json=payload)

    # Assert
    assert response.status_code == 201
    data = response.json()
    assert data["importance"] >= 3  # Should be scored high due to "always" + security context
    assert data["decay_score"] == 1.0

Fixture dei test​

Le fixture comuni sono definite in conftest.py:

import pytest
from fastapi.testclient import TestClient
from kore_memory.server import app

@pytest.fixture
def client():
    """Create a test client with a fresh in-memory database."""
    with TestClient(app) as client:
        yield client

@pytest.fixture
def saved_memory(client):
    """Save a test memory and return its data."""
    response = client.post("/save", json={
        "content": "Test memory for fixtures",
        "category": "general",
    })
    return response.json()

Cosa testare​

  • Percorso felice -- Le operazioni normali funzionano come previsto
  • Casi limite -- Lunghezza minima/massima del contenuto, tag vuoti, zero risultati
  • Casi di errore -- Input non valido, campi mancanti, ID inesistenti
  • Sicurezza -- Tentativi di SQL injection, payload XSS, bypass dell'autenticazione
  • Calcoli di decay -- Verifica l'output della formula a istanti temporali noti

Processo di pull request​

1. Crea un branch​

git checkout -b feature/your-feature-name

Convenzioni per i nomi dei branch:

  • feature/description -- Nuove funzionalità
  • fix/description -- Correzione di bug
  • docs/description -- Modifiche alla documentazione
  • refactor/description -- Refactoring del codice
  • test/description -- Aggiunta o modifica di test

2. Implementa le modifiche​

  • Scrivi codice seguendo le linee guida di stile sopra indicate
  • Aggiungi o aggiorna i test per le tue modifiche
  • Esegui la suite di test completa e assicurati che passi
  • Esegui il linting e il controllo dei tipi

3. Commit​

Scrivi messaggi di commit chiari e descrittivi:

# Buono
git commit -m "Add TTL support for auto-expiring memories"
git commit -m "Fix decay calculation when half-life is extended by retrieval"

# Cattivo
git commit -m "Update code"
git commit -m "Fix bug"

4. Push e creazione della PR​

git push origin feature/your-feature-name

Poi crea una pull request su GitHub. La descrizione della PR dovrebbe includere:

  • Cosa -- Una breve descrizione della modifica
  • Perché -- La motivazione o il problema risolto
  • Come -- Dettagli chiave dell'implementazione
  • Testing -- Come la modifica è stata testata

5. Processo di review​

  • Tutte le PR richiedono almeno una review prima del merge
  • La CI deve passare (test, linting, controllo dei tipi)
  • Mantieni le PR focalizzate -- una funzionalità o correzione per PR
  • Rispondi prontamente ai feedback della review
informazioni

Per funzionalità di grandi dimensioni, considera l'apertura di una PR in bozza per ricevere feedback anticipato sul tuo approccio prima di investire tempo significativo.

Segnalazione di problemi​

Apri un issue su GitHub con:

  • Descrizione -- Cosa è successo rispetto a cosa ti aspettavi
  • Passi per riprodurre -- Passaggi minimi per riprodurre il problema
  • Ambiente -- Versione di Python, sistema operativo, versione di Kore Memory (kore --version)
  • Log -- Messaggi di errore o stack trace rilevanti

Suggerimenti per lo sviluppo​

Ciclo di iterazione rapido​

# Terminale 1: Avvia il server con auto-reload
KORE_LOG_LEVEL=debug kore

# Terminale 2: Esegui test specifici al salvataggio
pytest tests/test_server.py -v --tb=short -x

Test con database pulito​

rm -f data/memory.db
kore

Ispezione del database​

sqlite3 data/memory.db ".tables"
sqlite3 data/memory.db "SELECT id, content, importance, decay_score FROM memories LIMIT 10;"

Profiling​

python -m cProfile -o profile.out -m kore_memory.server &
# Esegui il tuo workload, poi:
python -c "import pstats; p = pstats.Stats('profile.out'); p.sort_stats('cumulative'); p.print_stats(20)"

Licenza​

Contribuendo a Kore Memory, accetti che i tuoi contributi saranno rilasciati sotto la Licenza MIT.