xists
Find what exists. Decide what's next.
xists is a local semantic search engine for selected lists of GitHub repositories. Find existing projects you can use, deploy, adapt, or learn from—then decide what to do next.
English · 简体中文
Why xists?
Global GitHub search is often noisy, and traditional keyword matching lacks semantic understanding. xists solves this by narrowing the search space: you provide a curated repository list, and xists builds a local index for semantic search.
- Before you decide: check if a similar project or existing solution already exists.
- Tech decisions: compare candidates from a curated set using semantic search.
- Fast lookups: quickly find what you need without manually opening dozens of READMEs.
How it works
flowchart LR
A[Repo List] --> B[Ingest Metadata]
B --> C[Generate LLM Summaries]
C --> D[Build Local Index]
D --> E[Search]
D -. optional .-> F[Evaluate Ranking]
F -.-> G[Inspect Misses]
- Ingest: Provide a list of GitHub repos.
xistsfetches their metadata and READMEs. - Profile: It uses an LLM to generate compact, search-optimized summaries for better matching.
- Index: It builds a local JSON embedding index.
- Search: You query the index using semantic search.
Local-first index, explicit model endpoints
xists keeps everything transparent and local:
records.json: Raw metadata, structure signals, and LLM-generated profiles.index.json: The embedding index.eval-report.json: Search quality test results.
You need a GitHub token for the initial data fetch, plus model endpoints for summaries and embeddings. The records, index, ranking, and evaluation report stay on your machine. An embedding endpoint calculates vectors; xists stores them in local JSON and compares them locally.
Install and first search
Requires Python 3.11+. Install the published package:
python -m pip install xists
For development from a checked-out source tree, install the editable package with test dependencies:
python -m pip install -e ".[dev]"
Then initialize the default local workspace, add repositories you control to
~/.xists/repos.txt, and configure its .env file:
xists init
# Edit ~/.xists/.env and add owner/repo lines to ~/.xists/repos.txt.
xists ingest github
xists index build
xists search "open source firebase alternative"
See the demo walkthrough for endpoint checks, concurrency,
evaluation, and troubleshooting. No current-schema demo records/index download
is published yet; the first Release asset will be created only after it passes
records validate and index verify.
Quickstart
Requires Python 3.11+.
# Install
python -m pip install -e ".[dev]"
# Set up the default workspace configuration
xists init
# Edit ~/.xists/.env with your GitHub token, LLM model, and embedding model
Run the pipeline:
# 1. Fetch data & generate summaries
xists ingest github \
--repos repos.txt \
--output demo-records.json \
--report demo-report.json \
--github-api graphql
# 2. Build the local index
xists index build \
--records demo-records.json \
--output demo-index.json
# 3. Search!
xists search "open source firebase alternative" --index demo-index.json
xists search "open source firebase alternative" --index demo-index.json --format json
The commands above generate local files and may call the endpoints configured
in .env; use records.json / index.json instead if you do not want files
named as demo artifacts.
Python API
Use the stable API when another Python program needs the same search behavior
as the CLI. Configuration is always explicit; importing xists.api does not
read .env or send network requests.
from xists.api import load_index, search
from xists.search.embed import EmbeddingConfig
index = load_index("index.json")
config = EmbeddingConfig(
api_key="your-key",
base_url="https://your-embedding-endpoint/v1",
model="your-embedding-model",
)
result = search("open source firebase alternative", index, embedding_config=config, top_k=5)
search() may call the endpoint in config to embed the query. It raises
actionable Python exceptions for invalid indexes, incompatible embedding models,
and endpoint failures instead of printing or terminating the process.
Data, security, and privacy
.envand token files are read only from your local machine; xists does not commit, print, telemetry-report, or upload their secret values.ingest githubsends your GitHub token only to GitHub.profile refreshand ingest-time profile generation send repository text to the configured LLM endpoint.index buildsends embeddable repository text to the configured embedding endpoint;searchandeval runsend query text to that endpoint.- A local endpoint keeps those requests on your machine or network. A remote endpoint receives the corresponding text under that provider's terms; choose it only when you are permitted to send the material. xists does not host the endpoint, upload your index, or perform vector search remotely.
- If you share records or indexes, you are responsible for checking repository licenses, source content, generated profiles, and any personal or sensitive information before distribution.
Search Result Example
When you run a search, xists returns a compact text view by default for terminal review. Add --format json for scripts and agent integrations. v0.2.0 keeps ranking simple: exact repo/name/alias matches are pinned first, then semantic similarity is adjusted by a few explainable metadata signals.
Default text output looks like this:
query: hermes ai agent
intent: functional
abstained: False
results: 1
1. repo: NousResearch/hermes-agent
url: https://github.com/NousResearch/hermes-agent
confidence: high_confidence
score: 0.680000
summary: An agent-oriented project for Hermes models.
why: matched metadata terms: agent
The JSON output keeps the same ranking evidence in a machine-readable shape:
{
"query": "hermes ai agent",
"results": [
{
"repo_id": "NousResearch/hermes-agent",
"url": "https://github.com/NousResearch/hermes-agent",
"score": 0.68,
"semantic_score": 0.63,
"metadata_score": 0.05,
"confidence": "high_confidence",
"why": ["matched metadata terms: agent"]
}
]
}
score is the final ranking score; higher means a stronger match. Use --format json when another program or agent needs the structured payload.
Optional Evaluation
If you update the repository list, regenerate summaries, or change the search setup, xists lets you run fixed test cases to sanity-check whether results changed in a meaningful way.
pytest
xists eval run \
--cases examples/eval-cases.json \
--index demo-index.json \
--output demo-eval-report.json
xists eval inspect --report demo-eval-report.json --status serious_mismatch
The report groups results into pragmatic categories:
- Exact match: The specific target repo was #1.
- Acceptable alternative: Not the exact target, but a valid substitute (e.g., returning Vue when you asked for a React-like framework).
- Serious mismatch: The top result missed the core intent.
- Insufficient evidence: The indexed data was too thin to judge.
Commands
xists doctor: Check config and file status; add--check-endpointsor--strictto probe the embedding service.xists ingest github: Fetch repo metadata and generate summaries.xists index build: Build or incrementally update the local index.xists search "query": Query the local index with readable terminal output by default; add--format jsonfor scripts and agents.xists eval cases/xists eval run/xists eval inspect: Validate the dataset and run/review ranking tests.xists records validate/xists records stats/xists records inspect: Check record quality without printing huge payloads to your terminal.xists index stats/xists index verify: Summarize an index and confirm it is in sync with records.
Metadata
Release files for xists 0.7.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| xists-0.7.2.tar.gz | 153.9 kB | Without provenance | Details for xists-0.7.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| xists-0.7.2-py3-none-any.whl | Python 3 | none | any | Details for xists-0.7.2-py3-none-any.whl |
Total release size: 343.2 kB
Release files / xists-0.7.2.tar.gz
| Download URL | xists-0.7.2.tar.gz |
|---|---|
| Size | 153.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
492ddc2823c13f15b90917210df369b83271deecfb92958e3d391394cedcf8d7
|
|
BLAKE2b-256 checksum How to use checksums |
0391b4730aeb716b2ccb7ae87daada8635ef0b8c4f8149f581b9ccf374d914dc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.5
|
Release files / xists-0.7.2-py3-none-any.whl
| Download URL | xists-0.7.2-py3-none-any.whl |
|---|---|
| Size | 189.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
13721fa102111ca62eeb4491f66da69f8a6d38a991d4b4f28d09bfb1dcac18c7
|
|
BLAKE2b-256 checksum How to use checksums |
9258b5549224e62473e3af4573e95786f98b6238219162cbd04385ddc6a0dfd8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.5
|
Security for xists 0.7.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.