113 lines
4.7 KiB
Markdown
113 lines
4.7 KiB
Markdown
|
# Gate Interface Contract
|
|||
|
|
|
|||
|
|
A gate is a small, independent recognizer that detects whether a particular relation family is likely relevant to the input. Gates are the cheapest component in the pipeline and run first, in parallel.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Design principle
|
|||
|
|
|
|||
|
|
Gates are **high-recall by design**. It is better to activate an unnecessary specialist than to miss a needed one. A false positive costs budget. A false negative corrupts the answer.
|
|||
|
|
|
|||
|
|
Gates do not solve the task. They do not produce objects, facets, or constraints. They only emit a `GateSignal`.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Input
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
GateInput {
|
|||
|
|
text: string -- raw input text
|
|||
|
|
context: string? -- optional prior context
|
|||
|
|
span_start: integer? -- if operating on a specific span
|
|||
|
|
span_end: integer?
|
|||
|
|
gate_id: string -- which gate is being invoked
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Output
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
GateSignal {
|
|||
|
|
gate_id: string -- must match the invoking gate_id
|
|||
|
|
activated: boolean -- did this gate fire?
|
|||
|
|
confidence: float [0, 1] -- confidence in the activation decision
|
|||
|
|
evidence_spans: Span[]? -- text spans that triggered the gate
|
|||
|
|
method: string -- "regex" | "rule" | "classifier" | "neural" | "hybrid"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
See `schemas/routing.json#/$defs/GateSignal` for the normative schema.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Invariants
|
|||
|
|
|
|||
|
|
Every gate implementation MUST satisfy all of the following:
|
|||
|
|
|
|||
|
|
1. **Bounded output.** A gate emits exactly one `GateSignal`. No additional text, no secondary outputs.
|
|||
|
|
|
|||
|
|
2. **Idempotent.** Calling a gate twice with the same input produces the same output.
|
|||
|
|
|
|||
|
|
3. **No side effects.** A gate does not modify WorldState. It only reads input text.
|
|||
|
|
|
|||
|
|
4. **Declared method.** The `method` field must accurately reflect how the gate works (regex, rule, classifier, neural, hybrid). This is used for diagnostic filtering.
|
|||
|
|
|
|||
|
|
5. **High-recall posture.** When uncertain, a gate should prefer `activated: true` with lower confidence over `activated: false`. A gate should only return `activated: false, confidence: 0.99` if the signal is clearly and definitively absent.
|
|||
|
|
|
|||
|
|
6. **Self-contained.** A gate may not depend on the outputs of other gates. Gates run in parallel with no inter-gate dependencies.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Standard gate IDs
|
|||
|
|
|
|||
|
|
Gates are identified by string IDs. The following IDs are reserved and have defined semantics. Additional domain-specific gates may be added to the registry.
|
|||
|
|
|
|||
|
|
| gate_id | Fires when input probably contains... |
|
|||
|
|
|---|---|
|
|||
|
|
| `is_math` | Numeric computation, arithmetic, algebra |
|
|||
|
|
| `is_code` | Source code, pseudocode, program structures |
|
|||
|
|
| `has_temporal_relation` | Before/after/during/recurring/sequence |
|
|||
|
|
| `has_spatial_relation` | Location, containment, direction, proximity |
|
|||
|
|
| `has_causal_relation` | Cause/effect/enable/block |
|
|||
|
|
| `has_entity_reference` | Named or implied entities |
|
|||
|
|
| `has_coreference` | Pronouns or aliases that refer back |
|
|||
|
|
| `has_quantity` | Counts, amounts, measures, percentages |
|
|||
|
|
| `has_logical_negation` | Not, unless, except, never |
|
|||
|
|
| `has_comparison` | More/less/same/different/equal |
|
|||
|
|
| `has_planning` | Steps, goals, prerequisites, sequencing |
|
|||
|
|
| `has_constraint` | Requirements, restrictions, conditions |
|
|||
|
|
| `has_state_change` | Status transitions, possession changes |
|
|||
|
|
| `has_ownership_transfer` | Give, sell, take, receive, lose |
|
|||
|
|
| `has_social_intent` | Belief, desire, obligation, deception, trust |
|
|||
|
|
| `requires_external_knowledge` | World facts not inferable from input alone |
|
|||
|
|
| `requires_synthesis_only` | Input is direct and needs no decomposition |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Testing a gate implementation
|
|||
|
|
|
|||
|
|
A gate implementation is valid if it passes all of the following test classes:
|
|||
|
|
|
|||
|
|
**Positive recall tests:** Given input known to contain the relation, the gate fires.
|
|||
|
|
**True negative tests:** Given input that clearly lacks the relation, the gate does not fire.
|
|||
|
|
**Confidence calibration tests:** Confidence scores are higher for clear positives than for ambiguous cases.
|
|||
|
|
**Boundary tests:** Very short input, empty input, non-linguistic input (numbers only, code only) produce valid GateSignal objects.
|
|||
|
|
**Idempotency tests:** Same input, same output on repeated calls.
|
|||
|
|
|
|||
|
|
See `tests/contracts/gate_contract_tests.md` for test case templates.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Implementation guide
|
|||
|
|
|
|||
|
|
A gate may be implemented in any language or framework, as long as it satisfies the contract above. Common approaches:
|
|||
|
|
|
|||
|
|
- **Regex / keyword rules:** fast, zero training cost, fragile on unusual phrasing
|
|||
|
|
- **Feature classifier:** small model trained on labeled examples, better generalization
|
|||
|
|
- **Small neural classifier:** ~1M–10M parameter binary classifier, highest recall potential
|
|||
|
|
- **Hybrid:** rules for high-confidence cases, classifier for uncertain cases
|
|||
|
|
|
|||
|
|
The gate registry (`gates/registry.md`) specifies how to register a new gate implementation.
|