Configure Connectors and LLM Models

Configure optional connectors and the language model. All connectors are optional — the service starts without any of them. Each connector enables a distinct feature area; omitting one degrades only that area.

Connector requirements summary

Connector	Required environment variables	What breaks if missing
OpenAI (LLM)	OPENAI_API_KEY, LLM_MODEL	Answer generation. Work items will escalate with LLM error.
Weaviate	WEAVIATE_URL, WEAVIATE_API_KEY (Cloud only)	Semantic retrieval and RAG context. Generation falls back to registry-only context.
Neo4j	NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD	Contradiction detection and graph sync. Graph endpoints return errors.
Transcript sync scheduler	CONNECTOR_SYNC_POLL_INTERVAL_MINUTES	Celery beat polls connector sync state less or more frequently.
Confluence	CONFLUENCE_BASE_URL, CONFLUENCE_USERNAME, CONFLUENCE_API_TOKEN, CONFLUENCE_SPACE_KEY	Confluence pages excluded from RAG. Generation may escalate with no_content if Confluence is the only source.
Jira	JIRA_BASE_URL, JIRA_USERNAME, JIRA_API_TOKEN, JIRA_PROJECT_KEY	Jira issues excluded from RAG. Escalation work items cannot be created in Jira.

---

LLM configuration (OpenAI-compatible)

Raw to Knowledge uses an OpenAIAdapter that wraps any OpenAI-compatible API endpoint.

export OPENAI_API_KEY="sk-..."
export LLM_MODEL="gpt-4o"

LLM_MODEL is passed directly to the chat completions endpoint. Any model identifier valid for your provider works here — for example, gpt-4o-mini, gpt-4-turbo, or a fine-tuned model ID.

Using a non-OpenAI provider: If you need to point at an alternative base URL (Azure OpenAI, a local Ollama proxy, vLLM, etc.), subclass OpenAIAdapter and override the base_url parameter passed to the openai.AsyncOpenAI client. The adapter interface does not expose a base_url environment variable — this requires a code-level change.

---

Weaviate (vector retrieval)

Weaviate provides the semantic search index for RAG context assembly and the known-answer similarity check (≥ 0.92 cosine similarity triggers a known_answer_matched shortcut).

export WEAVIATE_URL="http://localhost:8080"
# Only required for Weaviate Cloud deployments:
export WEAVIATE_API_KEY="weaviate-cloud-key"

Running Weaviate locally:

docker run -d \
  --name weaviate \
  -p 8080:8080 \
  -e AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED=true \
  -e PERSISTENCE_DATA_PATH=/var/lib/weaviate \
  semitechnologies/weaviate:latest

Schema initialization: The Weaviate schema (ApprovedAnswer class with vector index) is created automatically on first API use by an idempotent ensure_schema() call. No manual schema setup is required. If the schema already exists, the call is a no-op.

---

Neo4j (graph and contradiction detection)

Neo4j stores the knowledge graph projection used for contradiction detection and relationship traversal.

export NEO4J_URI="bolt://localhost:7687"
export NEO4J_USERNAME="neo4j"
export NEO4J_PASSWORD="password"

The defaults shown above match a standard local Neo4j installation. Change them to match your deployment.

Running Neo4j locally:

docker run -d \
  --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/password \
  neo4j:5

Schema initialization: Uniqueness and existence constraints are created automatically via an idempotent ensure_constraints() call (IF NOT EXISTS semantics). No manual Cypher setup is required.

Note: Neo4j is a derived projection of PostgreSQL. If the Neo4j database is lost, it can be fully rebuilt by running the graph sync task against all approved answers. Do not treat Neo4j as a primary data store.

---

Confluence (RAG source)

When configured, Confluence pages from the specified spaces are retrieved as RAG context during answer generation.

export CONFLUENCE_BASE_URL="https://yourorg.atlassian.net/wiki"
export CONFLUENCE_USERNAME="admin@yourorg.com"
export CONFLUENCE_API_TOKEN="your-atlassian-api-token"
export CONFLUENCE_SPACE_KEY="KM,ENG"

CONFLUENCE_SPACE_KEY accepts a comma-separated list of space keys. All listed spaces are searched during RAG retrieval.

If any of the four Confluence variables is absent, the Confluence connector is skipped entirely. No error is raised at startup.

Generating an Atlassian API token: Log in to id.atlassian.com → Security → API tokens → Create API token.

---

Jira (RAG source and escalation target)

When configured, Jira issues from the specified project are searched as RAG context. Escalated work items can also be written back as Jira issues.

export JIRA_BASE_URL="https://yourorg.atlassian.net"
export JIRA_USERNAME="admin@yourorg.com"
export JIRA_API_TOKEN="your-atlassian-api-token"
export JIRA_PROJECT_KEY="KM"

If any Jira variable is absent, Jira is skipped as a source and escalation write-back is disabled.

---

Configuration validation at startup

On startup, pydantic-settings validates all environment variables. Type mismatches or values outside allowed ranges cause an immediate startup failure with a descriptive error message. Optional connectors are only validated when their variables are present — a missing CONFLUENCE_BASE_URL is not an error; a malformed URL in CONFLUENCE_BASE_URL is.

---

Transcript source sync configuration

Connector credentials only make a source available. Automatic retrieval requires persisted sync state per source:

• cadence: hourly, daily, or weekly
• legal_basis: default legal basis for scheduled/default pulls
• initial_since: first lower bound before any successful retrieval
• customer_scope: optional default scope label

Example:

curl -X PUT http://localhost:8000/v1/connectors/gong/sync \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "cadence": "daily",
    "legal_basis": "legitimate_interest",
    "customer_scope": "acme-corp",
    "initial_since": "2026-06-01T00:00:00Z"
  }'

Default pulls then use:

• first run: initial_since .. now
• later runs: last_successful_until .. now

The system still skips any transcript whose source_ref already exists, so overlapping windows remain safe.