#Graphify for k0smos

Mini guida per usare Graphify con k0smos.

Graphify crea un knowledge graph del repository e lo salva in graphify-out/. Per k0smos l'installazione consigliata e tramite uv; Docker serve solo quando vuoi esporre un graph.json gia generato come server HTTP/MCP.

Riferimenti ufficiali:

• Sito: https://graphify.net/
• CLI: https://graphify.net/graphify-cli-commands.html
• PyPI: https://pypi.org/project/graphifyy/
• Repository: https://github.com/safishamsi/graphify

#Installazione consigliata tramite uv

Prerequisiti:

• Python 3.10+
• uv

Installa il pacchetto ufficiale. Il nome PyPI e graphifyy, con doppia y; il comando CLI resta graphify.

#uv tool install graphifyy
uv tool install "graphifyy[ollama]"
graphify --version

Se il tool era gia installato e vuoi aggiornarlo:

uv tool upgrade graphifyy

Per usare l'estrazione semantica locale con Ollama, installa Graphify con l'extra dedicato:

uv tool install "graphifyy[ollama]"

Registra Graphify nel progetto corrente dalla root del repository:

graphify install --project

Genera il grafo di k0smos dalla root del repository:

graphify .

Output atteso:

graphify-out/
  graph.html
  GRAPH_REPORT.md
  graph.json
  cache/

Note operative:

• graphify-out/graph.json e il file da montare nel container Docker se vuoi esporre il grafo via HTTP/MCP.
• Il compose locale monta solo quel file come ../../var/custom/graphify/graph.json:/data/graph.json:ro; crea quindi var/custom/graphify/ e copia li il graph.json generato.
• Non versionare graphify-out/ se contiene snapshot locali del repo.
• In PowerShell non usare /graphify .: usa graphify ..

#Uso LLM locale con Ollama

Graphify puo usare Ollama per l'estrazione headless senza inviare codice o documenti a provider esterni. Il comando ufficiale e:

graphify extract . --backend ollama

Il wrapper PowerShell locale imposta OLLAMA_BASE_URL e lancia Graphify con backend ollama.

Avvia Ollama e assicurati che il modello sia disponibile:

ollama pull qwen2.5-coder:7b

Poi lancia l'estrazione dalla root del repository:

.\docker\graphify\run-example.ps1

Se la policy locale blocca gli script PowerShell:

pwsh -ExecutionPolicy Bypass -File .\docker\graphify\run-example.ps1

#Alternativa tramite Python venv

Usa questa opzione solo se uv non e disponibile.

python -m venv .venv-graphify

Attiva il virtual environment nella tua shell, poi installa Graphify:

python -m pip install --upgrade pip
python -m pip install graphifyy
python -m graphify --version

Poi registra la skill e genera il grafo:

python -m graphify install --project
python -m graphify .

Se il comando graphify non viene trovato dopo pip install graphifyy, il problema di solito e il PATH della directory script Python. In quel caso usa python -m graphify oppure passa a uv tool install graphifyy.

#Server Docker opzionale

Il repository Graphify espone un Dockerfile, quindi qui non si usa un'immagine preconfezionata: si clona il sorgente upstream sotto docker/graphify/src/, cartella locale ignorata da Git, e si builda l'immagine usata dal compose.

Da docker/graphify/:

git clone --depth 1 --single-branch --branch v8 https://github.com/safishamsi/graphify.git src
docker build -t graphify:latest src

Se src/ contiene gia un checkout Graphify, aggiornalo dentro quella cartella oppure ricreala localmente. Non committare il contenuto di src/.

Prima di avviare il container, genera il grafo k0smos con graphify . dalla root del repo. Poi copia il file generato nella directory usata dal compose.

PowerShell:

New-Item -ItemType Directory -Force var/custom/graphify
Copy-Item graphify-out/graph.json var/custom/graphify/graph.json -Force

Shell POSIX:

mkdir -p var/custom/graphify
cp graphify-out/graph.json var/custom/graphify/graph.json

Configura la API key locale in docker/graphify/.env:

GRAPHIFY_API_KEY=change-me-local-only

Avvia il server con Docker Compose da docker/graphify/:

docker compose up -d

Apri il servizio su:

http://localhost:8282

Per modificare la porta esposta sul browser, cambia solo il lato sinistro del mapping ports in docker-compose.yml.

Esempio con docker run, se non vuoi usare Compose:

docker run --rm --name k0smos-graphify -p 18080:8080 -v "<repo-root>/var/custom/graphify/graph.json:/data/graph.json:ro" graphify:latest /data/graph.json --transport http --host 0.0.0.0 --port 8080 --api-key "<secret-locale>"

In questo caso il servizio risponde su http://localhost:18080.

#Configurazione minima consigliata

Sequenza minima per k0smos:

1. Installa Graphify con uv tool install graphifyy.
2. Verifica il CLI con graphify --version.
3. Dalla root del repo, registra la skill con graphify install --project.
4. Dalla root del repo, genera il grafo con graphify ..
5. Apri graphify-out/GRAPH_REPORT.md e verifica che descriva il progetto.
6. Apri graphify-out/graph.html in un browser per controllare la visuale.
7. Se serve un server HTTP/MCP, clona Graphify in docker/graphify/src/.
8. Builda l'immagine locale con docker build -t graphify:latest src.
9. Copia graphify-out/graph.json in var/custom/graphify/.
10. Imposta GRAPHIFY_API_KEY in docker/graphify/.env.
11. Avvia il server con docker compose up -d.

#Configurazione per assistenti AI

Graphify puo essere usato direttamente da terminale o come skill in un assistente AI.

Comandi consigliati per k0smos:

graphify install --project
graphify .

Dopo la generazione, gli assistenti devono leggere:

graphify-out/GRAPH_REPORT.md

prima di fare analisi architetturali o ricerche ampie nel codice.

#Comandi utili

graphify . --update
graphify . --force
graphify . --no-viz
graphify export callflow-html
docker compose logs -f
docker compose restart
docker logs -f k0smos-graphify
docker rm -f k0smos-graphify

#Note operative

• Il grafo e un artefatto locale: rigeneralo quando il codice cambia molto.
• Il Dockerfile serve il grafo gia generato; non sostituisce il passaggio graphify . sul repository.
• docker/graphify/src/, var/custom/graphify/, docker/graphify/.env e graphify-out/ sono artefatti locali e non devono entrare nel commit.
• Non versionare API key, cache o output locali.