Skip to content

[docs] Add OpenAPI spec for miner HTTP endpoints #46

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
zjwjing wants to merge 6 commits into
base: main
Choose a base branch
from
+1,178 −0
Open

[docs] Add OpenAPI spec for miner HTTP endpoints #46

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
136ef01
test commit
zjwjing Jun 17, 2026
d3a7653
delete test
zjwjing Jun 17, 2026
62dda41
Add OpenAPI spec for miner HTTP endpoints - Closes #23
zjwjing Jun 17, 2026
2cf7538
Add Redoc documentation page for API spec
zjwjing Jun 17, 2026
78e3263
Add retrieval benchmark suite for Engram vs Pinecone, Weaviate, pgvector
zjwjing Jun 18, 2026
80bd952
Add benchmark report template for retrieval comparisons
zjwjing Jun 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 57 additions & 0 deletions docs/benchmarks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
# Engram Retrieval Benchmark Report

## Summary

| System | Recall@1 | Recall@5 | Recall@10 | p50 Latency | p95 Latency |
|--------|----------|----------|-----------|-------------|-------------|
| Engram | - | - | - | - | - |
| Pinecone | - | - | - | - | - |
| Weaviate | - | - | - | - | - |
| pgvector | - | - | - | - | - |

## Methodology

### Datasets
- **MSMARCO**: Microsoft MAchine Reading COmprehension dataset
- **NFCorpus**: Nutrition Facts Corpus for medical information retrieval
- **NQ**: Natural Questions from Google

### Metrics
- **Recall@K**: Proportion of relevant documents in top-K results
- **p50 Latency**: Median query latency
- **p95 Latency**: 95th percentile query latency

### Configuration
- **Top-K**: 10
- **Iterations**: 100 queries per system
- **Embedding Model**: text-embedding-ada-002 (1536 dimensions)

## Results

*To be updated after benchmark execution*

## Notes

- Engram uses decentralized storage with (k,n) erasure coding
- Latency includes network round-trip time
- All systems tested under same conditions
- Benchmarks run on public cloud instances

## Reproduction

```bash
# Install dependencies
pip install -r requirements.txt

# Run benchmark
python scripts/bench/benchmark.py --dataset data/msmarco_sample.json --systems engram pinecone weaviate pgvector

# Generate report
python scripts/bench/benchmark.py --output docs/benchmarks.md
```

## References

- [BEIR Benchmark](https://github.com/beir-cellar/beir)
- [MSMARCO Dataset](https://microsoft.github.io/msmarco/)
- [Engram Documentation](https://github.com/Dipraise1/Engram)
27 changes: 27 additions & 0 deletions docs/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Engram Miner API Documentation</title>
<meta name="description" content="OpenAPI documentation for Engram Miner HTTP endpoints" />
<style>
body {
margin: 0;
padding: 0;
}
</style>
</head>
<body>
<redoc spec-url="openapi.yaml"
theme="dark"
hide-download-button="false"
hide-hostname="false"
required-props-first="true"
sort-props-alphabetically="true"
show-extensions="true"
path-in-middle-panel="true">
</redoc>
<script src="https://cdn.jsdelivr.net/npm/redoc@2.1.5/bundles/redoc.standalone.js"></script>
</body>
</html>
Loading