sscorp/ecosystem-intel

Should I Build This? — Ecosystem Intelligence for Open Source

Before you start an open-source project, this tells you what's alive, what's a graveyard (and exactly why each project died), and where the genuinely unfilled gap is — questions a search box cannot answer.

Built on self-hosted [Cognee](https://www.cognee.ai) for the WeMakeDevs × Cognee "Where's My Context?" hackathon — Track 1: Best Use of Cognee Open Source.

Live demo: https://sscorp-ecosystem-intel.hf.space

[image]

[image]

One analysis, three answers: what's alive, what's dead and why (every graveyard carries the maintainer's own deprecation notice as a clickable receipt), and the gap — demand no maintained project serves.

 

The theme, taken literally

The hackathon asks *"Where's my context?" — an AI that woke up with no memory of last night. Open source wakes up like that every morning.* In any niche, dozens of projects have already lived and died, and the context — what was tried, why it failed, what users still ask for — is scattered across closed issues, archived READMEs, and deprecation notices nobody reads. The ecosystem has amnesia.

This project is the morning-after reconstruction, built on Cognee's memory lifecycle: it remembers the ecosystem (add + cognify), recalls why each dead project died with the source as the receipt, improves what it knows when reality changes (memify), and forgets projects that no longer belong. Ask it "should I build this?" and it answers with the context everyone else lost.

Table of contents

1. 1.The theme
2. 2.The problem
3. 3.Why a knowledge graph
4. 4.How it uses Cognee
5. 5.Architecture
6. 6.Getting started
7. 7.Configuration reference
8. 8.API reference
9. 9.Project structure
10. 10.Development
11. 11.Deployment
12. 12.Status

The problem

Asking "does something like this already exist?" is a similarity search — solved, commodity, and useless over a sea of abandoned repos. The questions that actually decide whether you should build are relational and live in scattered prose, not in repo descriptions:

• —Which similar projects were abandoned, and why? (the reason is buried in a closing issue or a README deprecation notice)
• —Where is the unmet gap — a capability people keep requesting that no maintained project supplies?

Vector search cannot answer either. Both require a graph.

Why a knowledge graph

How it uses Cognee's memory lifecycle

Architecture

GitHub API ──▶ documents ──▶ Cognee (cognify) ──▶ graph + vector store (Kuzu + LanceDB)
                                                          │
              Web UI ◀── FastAPI /analyze ◀── recall (multi-hop) ◀┘

Ingestion runs offline to pre-build the store; the deployed service only reads it. This keeps deployment light and free.

Getting started

Mock mode (2 minutes, no keys, no Cognee)

cd backend
python -m venv .venv && source .venv/bin/activate
pip install fastapi "uvicorn[standard]" python-dotenv requests pydantic
cp .env.example .env                      # then set USE_MOCK=1
uvicorn app.main:app --reload
# open http://127.0.0.1:8000

Real mode

Windows users: the real stack (cognee + kuzu + fastembed) runs under WSL Ubuntu. Create the venv inside WSL and run all commands below from there.

# 1) Environment (uv recommended; plain pip works too)
uv venv ~/eco-venv --python 3.11
uv pip install --python ~/eco-venv/bin/python -r backend/requirements.txt

# 2) Configure
cp backend/.env.example backend/.env      # fill LLM_* and GITHUB_TOKEN, set USE_MOCK=0

# 3) GATE: prove LLM + embeddings + graph round-trip before anything else
#    WARNING: the gate starts with a store reset — always BEFORE step 4, never after.
cd backend && ~/eco-venv/bin/python smoke_test.py
# PASS = the printed answer names RepoB as abandoned (burnout / superseded)

# 4) Pre-ingest demo domains (offline)
~/eco-venv/bin/python -m app.ingest "llm eval framework" --max 15

# 5) Serve
~/eco-venv/bin/uvicorn app.main:app --reload

Configuration reference

All configuration is via backend/.env (see backend/.env.example). Never commit `.env` — it is gitignored; every secret lives there and nowhere else.

Do not set DATA_ROOT_DIRECTORY in .env: cognee validates it at import time and rejects relative paths. The store location (backend/data/) is set in code by cognee_engine.configure().

API reference

Fail-soft contract: if the real pipeline errors, every endpoint returns the error in the body (e.g. "mode": "mock-fallback", "forgotten": false) — nothing 500s during a demo.

The API layer is class-based: controllers in app/api/routes.py own their routers, and every router carries the get_current_user dependency from app/api/deps.py — the single seam where authentication can be added later without touching any route.

Project structure

backend/
  app/
    api/
      routes.py        # class-based controllers (Health, Analysis, Lifecycle)
      schemas.py       # Pydantic request models
      deps.py          # shared dependencies — the auth seam
    cognee_engine.py   # THE ONLY file with version-sensitive Cognee calls (pinned 1.2.2)
    github_client.py   # GitHub REST wrapper: repo search, tiered provenance, demand signals
    provenance.py      # cognee-free ledger: project -> exact source URL
    schema.py          # graph ontology models + document builders
    ingest.py          # offline ingestion, one dataset per project
    queries.py         # product logic: mock / cognee / fail-soft, ADR-0010 JSON contract
    main.py            # app factory: wires controllers + mounts the frontend
  tests/               # pytest suite (contracts, provenance tiers, fail-soft)
  smoke_test.py        # six-leg gate: remember, cognify, recall, forget, memify
  Dockerfile           # HF Spaces deployment (port 7860)
  requirements.txt
frontend/
  index.html           # markup only
  css/app.css          # styles
  js/app.js            # API calls + rendering
pyproject.toml         # ruff + pylint + pytest config

The one rule: every version-sensitive Cognee call lives in backend/app/cognee_engine.py, annotated with the verified 1.2.2 signature. If a Cognee upgrade breaks something, the fix is in that one file.

Development

Run locally for feedback (mock mode — instant, no keys)

# from backend/ (in WSL if on Windows):
USE_MOCK=1 uvicorn app.main:app --host 0.0.0.0 --port 8000
# then open http://localhost:8000  (UI)  and  http://localhost:8000/docs  (Swagger)

USE_MOCK=1 on the command line overrides .env, so the full UI + API run with canned data and zero dependencies on Cognee/Euri/GitHub. Drop the override to serve real graph answers from the pre-ingested store.

Quality gates

# Lint + format (both must be clean; pylint is held at 10.00/10)
ruff format backend && ruff check backend
cd backend && pylint app smoke_test.py tests

# Unit/contract tests (fast, no network)
cd backend && pytest

# The real-Cognee integration gate (needs .env keys; ~4 min)
cd backend && python smoke_test.py

• —The smoke test is the gate: no feature work lands while smoke_test.py fails.
• —Multi-file changes are test-first (see backend/tests/).

Test suite & coverage

86 tests, all green, in ~10s with no network and no Cognee installed — the suite proves the API contracts, the fail-soft behavior, the provenance tiers, the status heuristic, and the LLM failover chain entirely in mock mode. Coverage of backend/app is 72%, and the gap is deliberate:

pytest --cov=backend/app --cov-report=term-missing   # reproduce the numbers

Continuous integration

Every push runs `.github/workflows/ci.yml`: ruff format --check + ruff check, pylint --fail-under=10, and the full pytest suite with coverage — on a machine with cognee deliberately not installed, which continuously proves the mock/fail-soft boot path (ADR-0008).

The real-Cognee integration is not CI-able (it needs live LLM keys and resets the store), so it is gated locally instead:

The six-leg real-Cognee gate

backend/smoke_test.py runs against real Cognee 1.2.2 + Euri + local fastembed and must print six PASS lines:

Run order for a deployable store: smoke → bulk ingest → deploy.

Deployment

• —Backend → Hugging Face Spaces (Docker). Commit backend/data/ (the prebuilt store) at ingest time, set USE_MOCK=0 + the LLM vars as Space Variables. Serves on port 7860.
• —Frontend → Vercel (static). Point API_BASE in frontend/index.html at the Space URL.

Status

• —[x] Environment validated: cognee 1.2.2 + Euri LLM + local fastembed
• —[x] Six-leg smoke gate passing (remember, cognify, recall, forget, memify)
• —[x] pytest suite green (API contracts, fail-soft, provenance tiers, status heuristic)
• —[x] Provenance-tiered GitHub ingestion (README notices → maintainer issues → archived default → none)
• —[x] /forget + /memify HTTP endpoints and UI controls
• —[x] Class-based API layer with an auth seam (app/api/)
• —[x] Lint clean: ruff all-pass, pylint 10.00/10
• —[x] CI on every push: ruff + pylint + pytest with coverage (mock-mode, cognee-free)
• —[x] MIT licensed
• —[x] Pre-ingested demo domains (96 datasets, 1157 nodes / 1608 edges) + deployed live on HF Spaces with an hourly keep-alive