.env.example

# ============================================================================
# Dialectical Framework — environment configuration
#
# Copy this file to `.env` and fill in the values. `.env` is gitignored.
#
# Convention:
#   - UNCOMMENTED vars are REQUIRED — you must set them.
#   - COMMENTED vars are optional; the value shown IS the code default.
#     Leave them commented to inherit the default (so future default changes
#     reach you automatically); uncomment only to pin a different value.
# ============================================================================

# ----------------------------------------------------------------------------
# LLM model (REQUIRED)
# ----------------------------------------------------------------------------
# Single combined "provider/model" string. The provider prefix selects the
# Mirascope provider; supported prefixes: `anthropic/`, `openai/`, `bedrock/`.
# The value below is an EXAMPLE, not a default — there is no fallback in code.
#   anthropic/claude-opus-4-1-20250805
#   openai/gpt-4o
#   bedrock/global.anthropic.claude-haiku-4-5-20251001-v1:0
DIALEXITY_DEFAULT_MODEL=bedrock/global.anthropic.claude-haiku-4-5-20251001-v1:0

# ----------------------------------------------------------------------------
# Provider credentials (set the ones matching your DIALEXITY_DEFAULT_MODEL)
# ----------------------------------------------------------------------------
# For `anthropic/*` models — read directly by the Anthropic SDK:
# ANTHROPIC_API_KEY=sk-ant-...

# For `openai/*` models — read directly by the OpenAI SDK:
# OPENAI_API_KEY=sk-...

# For `bedrock/*` models — routed through a custom Mirascope provider using
# `AnthropicBedrock()`, which resolves AWS credentials via the standard AWS
# chain (profile, env vars, or instance role). Typically:
# AWS_PROFILE=your-profile
# AWS_REGION=us-east-1

# ----------------------------------------------------------------------------
# Graph database (Memgraph or Neo4j)
# ----------------------------------------------------------------------------
# Vendor: "memgraph" or "neo4j".
# DIALEXITY_GRAPH_DB_VENDOR=memgraph
# DIALEXITY_GRAPH_DB_HOST=127.0.0.1
# DIALEXITY_GRAPH_DB_PORT=7687
# Username/password: required for Neo4j, optional for Memgraph (no default).
# DIALEXITY_GRAPH_DB_USERNAME=
# DIALEXITY_GRAPH_DB_PASSWORD=
# Use an encrypted (SSL/TLS) connection. "true" or "false".
# DIALEXITY_GRAPH_DB_ENCRYPTED=false
# Client name reported to the database for connection identification.
# DIALEXITY_GRAPH_DB_CLIENT_NAME=dialectical_framework

# ----------------------------------------------------------------------------
# Generation tuning (optional)
# ----------------------------------------------------------------------------
# Approximate word length of a component headline (T, A, T+, ...).
# DIALEXITY_DEFAULT_COMPONENT_LENGTH=7
# Approximate max word length of a (fuller) transition statement.
# DIALEXITY_DEFAULT_TRANSITION_LENGTH=15
# Max wheel layer (PP count per wheel) to build. Higher layers are skipped
# regardless of nexus size — bounds combinatorial explosion.
# DIALEXITY_MAX_WHEEL_LAYER=4

# Extended thinking budget. Unset = disabled. One of:
#   none | minimal | low | medium | high | max
# Maps to provider-specific token budgets (% of max_tokens for Anthropic).
# Silently ignored (with a warning) if the model doesn't support thinking.
# DIALEXITY_THINKING_LEVEL=medium

# ----------------------------------------------------------------------------
# Advisor runtime budgets (optional)
# ----------------------------------------------------------------------------
# The Advisor agent runs the framework SILENTLY behind a conversation, so it
# decides on its own what to read and how deep to explore. These vars bound
# that autonomy: what enters its context window (quality filter) and how much
# LLM work one exploration call may spend (depth budget). The Navigator
# agents (Analyst/Explorer) are user-driven and ignore all of them.

# --- Context quality filter ---
# What the Advisor "knows" is a graph dump rendered into its system prompt
# (at construction / on sync). A weak tension presented confidently is bad
# advice, so low-quality material is filtered OUT of the dump rather than
# merely down-ranked. Nothing is deleted: suppressed items are noted with a
# count line and stay reachable via the Advisor's inspect tool. Nexus
# members (user-built explorations) are never suppressed. Quality scales:
# docs/scoring.md.

# POLARITY quality floor: how genuine the T-A opposition is.
# HS (heuristic similarity) on the antithesis measures how well A captures
# the ideal antithesis of T (0.0-1.0):
#   0.9-1.0 perfect | 0.7-0.9 strong | 0.5-0.7 moderate
#   0.3-0.5 weak    | 0.1-0.3 barely an antithesis | <0.1 wrong category
# Perspectives whose polarity scores below the floor are suppressed.
# 0 disables. (For calibration: the analysis pipeline itself expands only
# tensions with HS >= 0.7 — below-0.5 material usually predates that gate
# or came from user-anchored input.)
# DIALEXITY_ADVISOR_POLARITY_QUALITY_MIN_HS=0.5

# PERSPECTIVE quality floors — the SP + DV pair mirrors the paper's
# acceptance criterion (SP AND DV) as soft context-pruning.
#
# SP floor: how differentiated the tetrad is.
# SP (Synthesis Potential, code name `area`) =
# [Ks(T+) - Ks(T-)] + [Ks(A+) - Ks(A-)] — how clearly constructive
# aspects rise above destructive ones. Well-formed tetrads land ~0 to 2:
#   >= 0.7 clear differentiation | 0.3-0.7 acceptable
#   <  0.3 aspects blur together — structure too weak to counsel from
# Perspectives below the floor are suppressed. 0 disables.
# DIALEXITY_ADVISOR_PERSPECTIVE_QUALITY_MIN_SP=0.3

# DV floor: how NATURAL the tension's dialectical relationship is (0-1).
# Low DV = forced/distorted framing (one pole arbitrarily privileged,
# dynamics held together by coercion or ideology). Comparative signal,
# conservative default. Perspectives below the floor are suppressed.
# 0 disables.
# DIALEXITY_ADVISOR_PERSPECTIVE_QUALITY_MIN_DV=0.3

# Competing causal arrangements (wheels) per cycle shown in the dump —
# the top few by normalized plausibility (%); the rest get a count line.
# Applies to the standalone Advisor's dump only: the counsel mode of an
# exploration (Explorer handover) always sees the user-built exploration
# in full. 0 = unlimited.
# DIALEXITY_ADVISOR_WHEEL_QUALITY_TOP_PLAUSIBLE=3

# --- Silent-explore depth budget ---
# One Advisor explore call builds and ranks ALL causal arrangements (cheap,
# structural), then deep-generates pathways + synthesis ONLY for the single
# most plausible one — that is where the real LLM cost sits (a 3-perspective
# nexus has 17 wheels; deep-generating all of them is ~10x the spend for
# material the Advisor won't present). Fixed policy, not a knob. Nothing is
# lost — shallow wheels stay ranked, and the Advisor's `deepen` tool
# develops any of them on demand when the conversation picks a different
# reading; excess perspectives are reported back as deferred for a
# follow-up call.

# Max perspectives woven into the nexus per explore call; excess is
# reported as deferred (never silently dropped). Bounds the latency of one
# conversation turn, not total work (DIALEXITY_MAX_WHEEL_LAYER bounds the
# eventual structure). 0 = unlimited.
# DIALEXITY_ADVISOR_MAX_PERSPECTIVES_PER_EXPLORATION=2

# ----------------------------------------------------------------------------
# Concurrency / rate limiting (optional)
# ----------------------------------------------------------------------------
# Cap on concurrent LLM calls, as runaway protection. 0 = no limit
# (rely on rate-limit retry). Set to a positive integer to enable.
# DIALEXITY_MAX_CONCURRENT_LLM_CALLS=0

# ----------------------------------------------------------------------------
# Observability (optional)
# ----------------------------------------------------------------------------
# Effect logging: directory for JSONL effect logs. Unset = disabled. When set,
# graph mutations and tool calls are written to <dir>/<sid>/<agent|pipeline>.jsonl
# DIALEXITY_GRAPH_LOG_DIR=./effect-logs

# Langfuse tracing (auto-detected by the Langfuse SDK when these are present).
# Leave unset to disable tracing.
# LANGFUSE_PUBLIC_KEY=pk-lf-...
# LANGFUSE_SECRET_KEY=sk-lf-...
# LANGFUSE_HOST=https://cloud.langfuse.com
# LANGFUSE_TRACING_ENVIRONMENT=development

# ----------------------------------------------------------------------------
# Tests (optional)
# ----------------------------------------------------------------------------
# "true" cleans the test graph before/after each test; "false" keeps
# test data for inspection. Used by tests/conftest.py only.
# DIALEXITY_TEST_CLEANUP=true