{"openapi":"3.1.0","info":{"title":"Calibrated Similarity Search API","description":"Stateless NMI + cosine fusion with entropy-driven alpha calibration","contact":{"email":"dasaanrod@gmail.com"},"version":"1.0.0"},"paths":{"/similarity/search":{"post":{"summary":"Stateless NMI+cosine fusion search over an inline corpus","operationId":"search_corpus_by_calibrated_similarity_similarity_search_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimilaritySearchRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimilaritySearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment Required"}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.01"},"protocols":[{"x402":{}}]}}},"/similarity/calibrate-alpha":{"post":{"summary":"Compute entropy-calibrated alpha for a corpus without running a query","operationId":"compute_corpus_entropy_calibrated_alpha_similarity_calibrate_alpha_post","security":[{"APIKeyHeader":[]}],"parameters":[{"name":"nmi_bins","in":"query","required":false,"schema":{"type":"integer","default":10,"title":"Nmi Bins"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CorpusVector"},"title":"Corpus"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlphaCalibrationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/similarity/calibrate-alpha/v1":{"post":{"summary":"Inspect entropy-calibrated alpha for a corpus before committing to a search","operationId":"inspect_corpus_entropy_and_alpha_similarity_calibrate_alpha_v1_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlphaCalibrateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlphaCalibrationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment Required"}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.01"},"protocols":[{"x402":{}}]}}},"/similarity/batch-score":{"post":{"summary":"Score up to 10,000 vector pairs with a fixed alpha — no corpus overhead","operationId":"score_vector_pairs_with_fixed_alpha_similarity_batch_score_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchScoreRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchScoreResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment Required"}},"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.01"},"protocols":[{"x402":{}}]}}},"/health":{"get":{"summary":"Liveness probe — no auth required","operationId":"liveness_probe_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Liveness Probe Health Get"}}}}},"security":[]}},"/stripe/webhook":{"post":{"summary":" Nexus Stripe Webhook","operationId":"_nexus_stripe_webhook_stripe_webhook_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"AlphaCalibrateRequest":{"properties":{"corpus":{"items":{"$ref":"#/components/schemas/CorpusVector"},"type":"array","maxItems":500000,"minItems":1,"title":"Corpus"},"nmi_bins":{"type":"integer","maximum":50.0,"minimum":3.0,"title":"Nmi Bins","default":10}},"type":"object","required":["corpus"],"title":"AlphaCalibrateRequest"},"AlphaCalibrationResponse":{"properties":{"calibrated_alpha":{"type":"number","title":"Calibrated Alpha"},"corpus_entropy":{"type":"number","title":"Corpus Entropy"},"corpus_size":{"type":"integer","title":"Corpus Size"},"vector_dim":{"type":"integer","title":"Vector Dim"},"latency_ms":{"type":"number","title":"Latency Ms"}},"type":"object","required":["calibrated_alpha","corpus_entropy","corpus_size","vector_dim","latency_ms"],"title":"AlphaCalibrationResponse"},"BatchScoreRequest":{"properties":{"pairs":{"items":{"prefixItems":[{"items":{"type":"number"},"type":"array"},{"items":{"type":"number"},"type":"array"}],"type":"array","maxItems":2,"minItems":2},"type":"array","maxItems":10000,"minItems":1,"title":"Pairs"},"alpha":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Alpha","default":0.5},"nmi_bins":{"type":"integer","maximum":50.0,"minimum":3.0,"title":"Nmi Bins","default":10}},"type":"object","required":["pairs"],"title":"BatchScoreRequest"},"BatchScoreResponse":{"properties":{"scores":{"items":{"type":"number"},"type":"array","title":"Scores"},"alpha_used":{"type":"number","title":"Alpha Used"},"pair_count":{"type":"integer","title":"Pair Count"},"latency_ms":{"type":"number","title":"Latency Ms"}},"type":"object","required":["scores","alpha_used","pair_count","latency_ms"],"title":"BatchScoreResponse"},"CorpusVector":{"properties":{"id":{"type":"string","maxLength":256,"minLength":1,"title":"Id"},"vector":{"items":{"type":"number"},"type":"array","maxItems":4096,"minItems":2,"title":"Vector"}},"type":"object","required":["id","vector"],"title":"CorpusVector"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"SimilarityResult":{"properties":{"id":{"type":"string","title":"Id"},"composite_score":{"type":"number","title":"Composite Score"},"cosine_similarity":{"type":"number","title":"Cosine Similarity"},"nmi_score":{"type":"number","title":"Nmi Score"},"rank":{"type":"integer","title":"Rank"}},"type":"object","required":["id","composite_score","cosine_similarity","nmi_score","rank"],"title":"SimilarityResult"},"SimilaritySearchRequest":{"properties":{"query":{"$ref":"#/components/schemas/CorpusVector"},"corpus":{"items":{"$ref":"#/components/schemas/CorpusVector"},"type":"array","maxItems":500000,"minItems":1,"title":"Corpus"},"top_k":{"type":"integer","maximum":1000.0,"minimum":1.0,"title":"Top K","default":10},"nmi_bins":{"type":"integer","maximum":50.0,"minimum":3.0,"title":"Nmi Bins","default":10},"alpha_override":{"anyOf":[{"type":"number","maximum":1.0,"minimum":0.0},{"type":"null"}],"title":"Alpha Override","description":"Pin alpha manually [0,1]. If None, entropy-calibrated alpha is used."}},"type":"object","required":["query","corpus"],"title":"SimilaritySearchRequest"},"SimilaritySearchResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/SimilarityResult"},"type":"array","title":"Results"},"calibrated_alpha":{"type":"number","title":"Calibrated Alpha"},"corpus_entropy":{"type":"number","title":"Corpus Entropy"},"query_id":{"type":"string","title":"Query Id"},"corpus_size":{"type":"integer","title":"Corpus Size"},"latency_ms":{"type":"number","title":"Latency Ms"},"request_fingerprint":{"type":"string","title":"Request Fingerprint"}},"type":"object","required":["results","calibrated_alpha","corpus_entropy","query_id","corpus_size","latency_ms","request_fingerprint"],"title":"SimilaritySearchResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"}}}}