Communication: helvia-rag-pipelines

1-hop view of how this service communicates with its siblings. For the full system view, see service-communication.md.

Calls Out To

Service	Protocol	Purpose	Key calls / queues
Milvus	TCP (pymilvus SDK)	Primary vector DB	Collection CRUD, vector insert/search
Qdrant	HTTP/gRPC (qdrant-client SDK)	Secondary vector DB	Collection CRUD, vector insert/search
OpenAI	HTTP (openai SDK)	Embeddings, chat completions	Embeddings API, Chat Completions API
Azure OpenAI	HTTP (custom client)	Embeddings, chat completions	Custom HTTP calls
Google Gemini	HTTP (google-generativeai SDK)	Embeddings, chat completions	SDK method calls
Google Cloud Translate	HTTP (SDK)	Translation	Translation API
Azure Translator	HTTP	Translation	Translator API
Helvia SemCache	HTTP (custom client)	Semantic caching (optional)	Custom HTTP calls
MySQL	TCP (SQLAlchemy)	Corpus, pipeline config, NLP providers	ORM queries
Redis	TCP	Optional embedding cache	Key-value cache

Called By

Service	Protocol	How
hbf-nlp	HTTP POST	/pipelines/{id}:process, :search, /corpus (PUT), :train
hbf-bot	HTTP POST	/pipelines/{id}:search

Contracts

Inbound

• POST /pipelines/{id}:process -- process query through RAG pipeline
• POST /pipelines/{id}:search -- semantic search against indexed corpus
• PUT /pipelines/{id}/corpus -- full corpus update
• POST /pipelines/{id}:train -- trigger training (embedding + indexing)
• POST /pipelines/{id}:index -- trigger indexing only
• CRUD on /pipelines -- pipeline configuration management
• /admin/* -- administrative endpoints

Outbound

• Vector DBs: Milvus or Qdrant depending on VECTOR_DB config. Insert, search, delete operations.
• LLM providers: OpenAI, Azure OpenAI, or Google Gemini per pipeline configuration for embeddings and completions.
• Translation: Google Cloud Translate or Azure Translator per configuration.
• SemCache: Optional semantic caching layer for repeated queries.

Environment Variables

Variable	Target
VECTOR_DB	Vector DB selection (milvus or qdrant)
MILVUS_*	Milvus connection
QDRANT_*	Qdrant connection
MYSQL_URL	MySQL
OPENAI_API_KEY	OpenAI
AZURE_OPENAI_*	Azure OpenAI
GOOGLE_APPLICATION_CREDENTIALS	Google Cloud (Gemini, Translate)

Flows Involving This Service

• Message Processing
• RAG Knowledge Query