adachsoft / repo-knowledge
CLI library for indexing and semantic search over repository documentation using vector embeddings
Requires
- php: ^8.3
- adachsoft/collection: ^3.0
- adachsoft/embedding-contracts: ^0.1
- adachsoft/embedding-openai: ^0.1
- adachsoft/vector-store-contracts: ^0.2.0
- adachsoft/vector-store-json-file: ^0.2.0
- vlucas/phpdotenv: ^5.6
Requires (Dev)
- adachsoft/cli-process-tester: ^0.1
- adachsoft/php-code-style: ^0.5.0
- friendsofphp/php-cs-fixer: ^3.95
- phpstan/phpstan: ^2.2
- phpunit/phpunit: ^13.2
- rector/rector: ^2.5
- symplify/phpstan-rules: ^14
README
PHP library for indexing and searching knowledge stored in a Git repository using vector embeddings.
Installation
Install via Composer:
composer require adachsoft/repo-knowledge
This package requires PHP 8.3 or higher.
Features
- Indexes files from your repository into a vector store
- Uses embedding providers that implement
adachsoft/embedding-contracts - Stores vectors using implementations of
adachsoft/vector-store-contracts(e.g. JSON file backend) - Simple CLI interface for indexing, searching and checking status
Basic usage
After installing the package, you can use the CLI entry point (for example via bin/repo-knowledge) to:
- index your repository content into the configured vector store,
- search for relevant snippets using semantic similarity,
- inspect the indexing status.
Example (your actual entry point or configuration may differ depending on your project setup):
php bin/repo-knowledge index --config=repo-knowledge.json
php bin/repo-knowledge search "How do I configure X?" --config=repo-knowledge.json
php bin/repo-knowledge status --config=repo-knowledge.json
Configuration
Configuration is usually provided in a JSON file (for example repo-knowledge.json).
All keys are optional; when a key is missing, a sensible default is taken from the internal DefaultConfig.
Top-level keys
| Key | Type | Description |
|---|---|---|
vector_store_path | string | Path to the file used by the underlying vector store backend (for example a JSON file). |
include | array of strings | List of files or directories that should be included in indexing. |
exclude | array of strings | List of files or directories that should be excluded from indexing. |
extensions | array of strings | List of file extensions that will be processed (for example ['php', 'md']). |
chunk_max_chars | integer | Maximum number of characters in a single text chunk (must be a positive integer if specified). |
embedding | object | Embedding model configuration (see below). |
distance_metric | string | Distance metric used in similarity search, mapped to an internal DistanceMetricEnum (for example cosine or euclidean). |
min_score | float (optional) | Minimal similarity score for search results; hits below this threshold are filtered out. |
embedding object
The embedding object configures how text is turned into vectors. It is mapped to the internal ConfigDto and then used by the embedding provider (for example adachsoft/embedding-openai).
| Key | Type | Description |
|---|---|---|
model | string | Name or identifier of the embedding model used by your embedding provider. |
dimensions | integer | Number of dimensions of the produced embedding vectors (must be a positive integer). |
A minimal example configuration might look like this:
{
"vector_store_path": "var/repo-knowledge/vector-store.json",
"include": ["src", "README.md"],
"exclude": ["vendor"],
"extensions": ["php", "md"],
"chunk_max_chars": 2000,
"embedding": {
"model": "text-embedding-3-large",
"dimensions": 3072
},
"distance_metric": "cosine",
"min_score": 0.5
}
Note: Exact defaults and supported values for
distance_metricdepend on the internal enums and the vector store implementation you use (adachsoft/vector-store-contractsbackends).
Testing
Run the test suite with:
vendor/bin/phpunit
Static analysis and code style tools:
vendor/bin/phpstan analyse src tests
vendor/bin/rector process src tests
vendor/bin/php-cs-fixer fix src tests
License
This library is open-sourced software licensed under the MIT license.