Skip to content

docs: RFC for adapting Agno's knowledge/vectordb architecture into HUF#178

Draft
esafwan wants to merge 1 commit into
developfrom
feature/wider-agent-knowledge-agno-style
Draft

docs: RFC for adapting Agno's knowledge/vectordb architecture into HUF#178
esafwan wants to merge 1 commit into
developfrom
feature/wider-agent-knowledge-agno-style

Conversation

@esafwan

@esafwan esafwan commented Mar 3, 2026

Copy link
Copy Markdown
Contributor

Comprehensive analysis and implementation plan for bringing Agno's vector database, embedder, reader, and chunker architecture into HUF's existing knowledge system.

Key points:

  • Adapt interfaces (VectorDb, Embedder, ChunkingStrategy) not the orchestration layer — keep HUF's Frappe-native pipeline
  • Phase 1: Embedder system via LiteLLM (25+ providers, zero new deps)
  • Phase 2: 3 vector backends (Qdrant, ChromaDB, LanceDB)
  • Phase 3: Enhanced readers (Excel, PPTX) and chunkers (recursive, markdown, code-aware)
  • Phase 4: Hybrid search (BM25 + vector with RRF)
  • Zero breaking changes to existing SQLite FTS5 users
  • All new dependencies are optional extras
  • Agno is Apache 2.0 licensed — compatible with adaptation

Relationship to scoped memory/data management

This PR should be read together with #274, which proposes the bridge between conversation data management, scoped Memory/Data Records, Knowledge Sources, Agno-style retrieval architecture, and Hindsight-style long-term memory.

In that combined model, this Agno-style architecture is the indexing/retrieval half of the bridge:

Memory/Data Record selected for knowledge
        ↓
Knowledge Projection
        ↓
Agno-style indexing pipeline
        ↓
FTS/vector/hybrid retrieval

This PR should not decide what becomes canonical memory. Instead, it should improve how selected/promoted records and normal Knowledge Sources are embedded, chunked, indexed, filtered, and retrieved.

Related:

Comprehensive analysis and implementation plan for bringing Agno's
vector database, embedder, reader, and chunker architecture into HUF's
existing knowledge system. Key points:

- Adapt interfaces (VectorDb, Embedder, ChunkingStrategy) not the
  orchestration layer — keep HUF's Frappe-native pipeline
- Phase 1: Embedder system via LiteLLM (25+ providers, zero new deps)
- Phase 2: 3 vector backends (Qdrant, ChromaDB, LanceDB)
- Phase 3: Enhanced readers (Excel, PPTX) and chunkers (recursive,
  markdown, code-aware)
- Phase 4: Hybrid search (BM25 + vector with RRF)
- Zero breaking changes to existing SQLite FTS5 users
- All new dependencies are optional extras
- Agno is Apache 2.0 licensed — compatible with adaptation

https://claude.ai/code/session_01GmUsXDeU47V7sCMNKzYkkj
@esafwan

esafwan commented Jul 19, 2026

Copy link
Copy Markdown
Contributor Author

TODO before this PR is taken up: update the RFC to reflect PR #280

Since this PR was opened, HUF adopted, via PR #280 (in review), the LlamaIndex-adapter pattern for vector backends and the get_advanced_config_schema() + generic advanced_config renderer for tuning params. This RFC should be updated to show which proposals are now implemented/superseded and which remain open.

  • Update docs/rfcs/agno-knowledge-vectordb-adaptation.md to state that HUF uses thin LlamaIndex adapters (see pgvector_backend.py / chroma_backend.py in PR feat: add PGVector knowledge source #280) and HUF-side embeddings via huf.ai.knowledge.embedding.
  • Mark the proposed separate Embedder class and huf/ai/knowledge/embedders/ module as superseded by the existing huf.ai.knowledge.embedding module.
  • Mark the proposed Knowledge Source field changes (connection_config, search_type, vector_dimensions, etc.) as superseded by field groups + advanced_config; map any missing knobs to get_advanced_config_schema() entries.
  • Mark Qdrant/Chroma/LanceDB backend ports as "future standardization PRs" that must follow the PR feat: add PGVector knowledge source #280 contract (subclass KnowledgeBackend, implement get_advanced_config_schema(), register via get_backend()).
  • Keep the enhanced readers (Excel, PPTX) and chunkers (recursive, markdown, code-aware) as open proposals, since these are not covered by PR feat: add PGVector knowledge source #280 and can be pursued independently.
  • Add a status section listing each proposal as Implemented / Superseded / Open, with links to PR feat: add PGVector knowledge source #280 and the cross-backend audit.

No code changes are required in this PR; once the RFC is updated it can be merged as documentation.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant