99 lines
2.6 KiB
Markdown
99 lines
2.6 KiB
Markdown
# Architecture
|
|
|
|
`GroundRecall` is the grounded knowledge substrate in a larger stack:
|
|
|
|
- `GroundRecall`: canonical knowledge ingestion, promotion, query, export, and future sync
|
|
- `Didactopus`: learner-facing workflows and educational tooling
|
|
- `GenieHive`: model and routing layer where runtime assistant/service resolution is needed
|
|
|
|
For governed model access, GroundRecall treats the GenieHive Foundation gateway
|
|
profile as an external endpoint and policy boundary. GroundRecall does not own
|
|
GenieHive credentials, request audit logs, provider routing, or budget state.
|
|
See [geniehive-foundation-gateway.md](geniehive-foundation-gateway.md).
|
|
|
|
## Core Design
|
|
|
|
The system is built around one canonical flow:
|
|
|
|
1. ingest weakly structured sources
|
|
2. normalize them into stable knowledge objects
|
|
3. lint and queue them for review
|
|
4. promote reviewed objects into a canonical store
|
|
5. query and export promoted state
|
|
|
|
## Core Objects
|
|
|
|
The canonical store is built from these object families:
|
|
|
|
- `Source`
|
|
- `Fragment`
|
|
- `Artifact`
|
|
- `Observation`
|
|
- `Claim`
|
|
- `Concept`
|
|
- `Relation`
|
|
- `ReviewCandidate`
|
|
- `PromotionRecord`
|
|
- `GroundRecallSnapshot`
|
|
|
|
These objects are assistant-neutral. Assistant-specific formatting belongs at the adapter layer.
|
|
|
|
## Package Surface
|
|
|
|
The main standalone package surface is:
|
|
|
|
- `groundrecall.ingest`
|
|
- `groundrecall.lint`
|
|
- `groundrecall.models`
|
|
- `groundrecall.store`
|
|
- `groundrecall.promotion`
|
|
- `groundrecall.query`
|
|
- `groundrecall.export`
|
|
- `groundrecall.assistant_export`
|
|
- `groundrecall.inspect`
|
|
- `groundrecall.source_adapters.*`
|
|
- `groundrecall.assistants.*`
|
|
|
|
There are also compatibility-style helper modules prefixed with `groundrecall_` inside the package. Those exist because the standalone repo was extracted from an earlier monorepo layout.
|
|
|
|
## Source Adapters
|
|
|
|
Adapters handle source-shape-specific discovery and mapping while the downstream pipeline stays generic.
|
|
|
|
Current adapter families include:
|
|
|
|
- `llmwiki`
|
|
- `markdown_notes`
|
|
- `transcript`
|
|
- `didactopus_pack`
|
|
|
|
## Assistant Boundary
|
|
|
|
Assistant integration is intentionally outside the core store and query semantics.
|
|
|
|
The rule is:
|
|
|
|
- core `GroundRecall` owns truth, provenance, lifecycle, and retrieval semantics
|
|
- assistant adapters own presentation, bundle shaping, and tool-specific exports
|
|
|
|
Current adapters include:
|
|
|
|
- `codex`
|
|
- `claude_code`
|
|
|
|
## Alpha Boundary
|
|
|
|
The current alpha is strong enough for:
|
|
|
|
- local import and promotion
|
|
- canonical query and export
|
|
- assistant-neutral bundles
|
|
- assistant-targeted bundle generation
|
|
|
|
It is not yet complete for:
|
|
|
|
- multi-node sync and merge
|
|
- re-import/update semantics
|
|
- richer review adjudication
|
|
- large-scale distributed corpus integration
|