poimen-memory/docs/api/T7_RANKING_API.md

# T7.4: Multi-Signal Ranking API Reference

## Overview

Advanced ranking with 7 configurable signals. Choose preset profiles or customize weights.

---

## Signals

### Semantic (Default Weight: 40%)
Vector similarity from pgvector. Range: 0.0-1.0.
- Higher = more semantically similar to query

### Lexical (Default Weight: 25%)
BM25 ranking from OpenSearch. Range: 0.0-1.0.
- Higher = more lexically similar to query

### Recency (Default Weight: 15%)
Time decay from last update. Formula: `exp(-age_days / 30)`
- Recent updates boost score
- 30-day half-life (score = 0.37 at 30 days)

### Frequency (Default Weight: 10%)
Access count log scale. Formula: `log(access_count + 1) / log(max_access + 1)`
- Frequently accessed entities ranked higher
- Normalized to 0.0-1.0

### Confidence (Default Weight: 5%)
Base confidence with staleness decay. Formula: `base * exp(-staleness_days / 90)`
- Entities confirmed recently score higher
- 90-day half-life

### Community (Default Weight: 3%)
Activity in connected community. Range: 0.0-1.0.
- Factor 1: Community size (0-100 entities)
- Factor 2: Recent edges (0-50 edges in 7 days)
- Score = (size_factor + activity_factor) / 2

### Contradiction (Default Weight: 2%)
Penalty for unresolved contradictions. Range: -0.3 to 0.0.
- Formula: `-min(0.3, ratio * 0.3)` where ratio = unresolved / total
- No contradictions = 0
- All contradictions = -0.3

---

## Endpoints

### GET /memory/ranking/profiles
List available ranking profiles

**Request**:
```bash
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8080/memory/ranking/profiles
```

**Response** (200 OK):
```json
{
  "profiles": [
    {
      "name": "default",
      "description": "Balanced multi-signal ranking",
      "weights": {
        "semantic": 0.40,
        "lexical": 0.25,
        "recency": 0.15,
        "frequency": 0.10,
        "confidence": 0.05,
        "community": 0.03,
        "contradiction": 0.02
      }
    },
    {
      "name": "recency_focused",
      "description": "Prioritize recent updates",
      "weights": {
        "semantic": 0.30,
        "lexical": 0.15,
        "recency": 0.35,
        "frequency": 0.10,
        "confidence": 0.05,
        "community": 0.03,
        "contradiction": 0.02
      }
    },
    {
      "name": "accuracy_focused",
      "description": "Prioritize high-confidence, no contradictions",
      "weights": {
        "semantic": 0.35,
        "lexical": 0.20,
        "recency": 0.10,
        "frequency": 0.05,
        "confidence": 0.20,
        "community": 0.05,
        "contradiction": 0.05
      }
    }
  ]
}
```

---

### POST /memory/query (with ranking profile)
Query with multi-signal ranking

**Request**:
```bash
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "kubernetes debugging",
    "ranking_profile": "recency_focused",
    "explain_ranking": true
  }' \
  http://localhost:8080/memory/query
```

**Response** (200 OK):
```json
{
  "query": "kubernetes debugging",
  "ranking_profile": "recency_focused",
  "results": [
    {
      "id": "e_k8s_debug",
      "name": "Kubernetes Debugging",
      "final_score": 0.92,
      "signal_breakdown": {
        "semantic": {
          "raw": 0.95,
          "weight": 0.30,
          "contribution": 0.285
        },
        "lexical": {
          "raw": 0.88,
          "weight": 0.15,
          "contribution": 0.132
        },
        "recency": {
          "raw": 0.98,
          "weight": 0.35,
          "contribution": 0.343
        },
        "frequency": {
          "raw": 0.72,
          "weight": 0.10,
          "contribution": 0.072
        },
        "confidence": {
          "raw": 0.90,
          "weight": 0.05,
          "contribution": 0.045
        },
        "community": {
          "raw": 0.65,
          "weight": 0.03,
          "contribution": 0.020
        },
        "contradiction": {
          "raw": 0.0,
          "weight": 0.02,
          "contribution": 0.0
        }
      }
    }
  ],
  "search_time_ms": 145
}
```

---

## Profiles

### default
Balanced ranking across all signals.

**When to use**:
- General queries
- No specific ranking priority
- Balanced experience

### recency_focused
Prioritize recently updated entities (35% weight).

**When to use**:
- Troubleshooting (recent solutions better)
- Current best practices
- Up-to-date documentation

**Example**:
```bash
curl -X POST http://localhost:8080/memory/query \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"query": "kubernetes 1.28 best practices", "ranking_profile": "recency_focused"}'
```

### accuracy_focused
High confidence (20%) + minimal contradictions (5% penalty weight).

**When to use**:
- Critical decisions (production deployments)
- Compliance audits
- High-stakes troubleshooting

**Example**:
```bash
curl -X POST http://localhost:8080/memory/query \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"query": "database backup procedures", "ranking_profile": "accuracy_focused"}'
```

---

## Custom Profiles (Future)

Currently, 3 preset profiles available. Future support for custom weights:

```bash
# (Not yet implemented)
curl -X POST http://localhost:8080/memory/ranking/profiles \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "my_custom",
    "weights": {
      "semantic": 0.5,
      "lexical": 0.3,
      "recency": 0.2,
      ...
    }
  }'
```

---

## Signal Analysis

### Score Contribution Example

Query: "kubernetes debugging"
Profile: recency_focused

| Signal | Raw | Weight | Contribution | Impact |
|--------|-----|--------|--------------|--------|
| semantic | 0.95 | 0.30 | 0.285 | High semantic match |
| lexical | 0.88 | 0.15 | 0.132 | Good BM25 match |
| recency | 0.98 | 0.35 | 0.343 | Very recent (days old) |
| frequency | 0.72 | 0.10 | 0.072 | Moderately accessed |
| confidence | 0.90 | 0.05 | 0.045 | Recently confirmed |
| community | 0.65 | 0.03 | 0.020 | Active community |
| contradiction | 0.0 | 0.02 | 0.0 | No issues |
| **TOTAL** | | | **0.897** | **89.7% relevance** |

---

## Tuning Guide

### If results are too general
- Increase semantic weight (0.40 → 0.50)
- Decrease lexical weight (0.25 → 0.15)
- Use `accuracy_focused` profile

### If results are too fresh
- Decrease recency weight (0.15 → 0.05)
- Increase confidence weight (0.05 → 0.15)
- Use `accuracy_focused` profile

### If results have errors
- Increase contradiction penalty (0.02 → 0.10)
- Increase confidence weight (0.05 → 0.20)
- Use `accuracy_focused` profile

---

## Rate Limits

| Endpoint | Limit |
|----------|-------|
| /ranking/profiles | 200/hr |
| /query with profile | 1000/hr |

---

## Performance

- Signal computation: < 20ms overhead per query
- Signal cache: 5-minute TTL
- Multi-signal ranking: No additional latency for scoring