main

FastAPI application — Alkiviades streaming SSE chat endpoint with authentication.

admin_create_user(body=Body(..., embed=False), user=Depends(require_admin)) async

Create a new user account. Admin only.

admin_delete_user(user_id, user=Depends(require_admin)) async

Delete a user and all their associated data. Admin only.

admin_list_users(user=Depends(require_admin)) async

List all users with API key status. Admin only.

admin_logs(limit=100, user=Depends(require_admin)) async

Return the last N lines of the application log file.

Admin only. Reads from the rotating file log.

Parameters:

Name	Type	Description	Default
limit	int	Maximum number of log lines to return (default 100).	100
user	dict	Decoded JWT payload — must have admin role.	Depends(require_admin)

Returns:

Type	Description
dict	Dict with a 'lines' key containing the log lines as a list of strings.

admin_logs_stream(request, user=Depends(require_admin)) async

SSE stream of new log entries.

Admin only. Polls the log file every 2 seconds for new content and pushes each new line as an SSE event. Automatically stops when the client disconnects.

Parameters:

Name	Type	Description	Default
request	Request	FastAPI Request for disconnect detection.	required
user	dict	Decoded JWT payload — must have admin role.	Depends(require_admin)

Returns:

Type	Description
EventSourceResponse	EventSourceResponse yielding 'log' events with new log lines.

admin_purge_legacy(user=Depends(require_admin)) async

Delete plaintext (pre-encryption) messages and blank legacy titles.

Admin only. Irreversible — rows written before runtime encryption existed. Encrypted rows are never touched.

Parameters:

Name	Type	Description	Default
user	dict	Decoded JWT payload — must have admin role.	Depends(require_admin)

Returns:

Type	Description
dict	Dict with counts of deleted message rows and cleared titles.

admin_reset_user_keys(user_id, user=Depends(require_admin)) async

Clear a user's personal API keys. Admin only.

auth_me(user=Depends(get_current_user)) async

Return current user profile including role.

chat(body, request, user=Depends(get_current_user)) async

Non-streaming chat endpoint — runs agent and returns complete response.

Fallback for clients that don't support SSE. Resolves all tool calls and streaming internally, then returns the full reply.

Parameters:

Name	Type	Description	Default
body	ChatRequest	ChatRequest with message, session_id, and optional axes override.	required
user	dict	Decoded JWT payload.	Depends(get_current_user)

Returns:

Type	Description
dict	Dict with reply, session_id, and sources list.

Raises:

Type	Description
HTTPException	400 if no DeepSeek API key is configured.

chat_stream(body, request, user=Depends(get_current_user)) async

SSE streaming chat endpoint.

Streams the agent's response token by token alongside RAG source citations, tool call events, and tool results. Sends heartbeat events every 15 seconds to keep the connection alive. On completion, persists the conversation turn to SQLite.

Parameters:

Name	Type	Description	Default
body	ChatRequest	ChatRequest with message, session_id, and optional axes override.	required
request	Request	FastAPI Request for disconnect detection.	required
user	dict	Decoded JWT payload.	Depends(get_current_user)

Returns:

Type	Description
EventSourceResponse	EventSourceResponse yielding token, source, tool_call,
EventSourceResponse	tool_result, done, error, and heartbeat events.

Raises:

Type	Description
HTTPException	400 if no DeepSeek API key is configured.

clear_user_keys(user=Depends(get_current_user)) async

Remove all personal API keys, reverting to system keys.

Parameters:

Name	Type	Description	Default
user	dict	Decoded JWT payload.	Depends(get_current_user)

Returns:

Type	Description
dict	Dict with updated key status showing system fallback for all providers.

delete_session_endpoint(session_id, user=Depends(get_current_user)) async

Delete a session and all its messages.

Parameters:

Name	Type	Description	Default
session_id	str	UUID of the session to delete.	required
user	dict	Decoded JWT payload.	Depends(get_current_user)

Returns:

Type	Description
dict	Dict with status 'deleted'.

Raises:

Type	Description
HTTPException	404 if session not found or not owned by user.

get_axes() async

Get the current global axis values.

Returns the three political axes (ethical, alignment, social) that modulate all agent responses.

Returns:

Type	Description
dict	Dict with ethical, alignment, and social float values.

get_session(session_id, request, user=Depends(get_current_user), preview=False) async

Get session details with full conversation history.

Returns all turns by default. With ?preview=true, returns only the first 3 turns (for sidebar hover previews).

Parameters:

Name	Type	Description	Default
session_id	str	UUID of the session to load.	required
user	dict	Decoded JWT payload.	Depends(get_current_user)
preview	bool	If true, return only the first 3 turns.	False

Returns:

Type	Description
dict	Session dict with id, title, axes, turns list, and timestamps.

Raises:

Type	Description
HTTPException	404 if session not found or not owned by user.

get_sql_session_mgr()

Return the process-wide SQLSessionManager singleton.

Lazily initialized on first use; shared by all request handlers so the (stateless) manager object is created once per process.

get_user_keys(user=Depends(get_current_user)) async

Return the current user's API key status.

Values are redacted — only indicates whether each key is configured (user-provided or system fallback).

Parameters:

Name	Type	Description	Default
user	dict	Decoded JWT payload.	Depends(get_current_user)

Returns:

Type	Description
dict	Dict with deepseek, tavily, and scrapingant key status entries.

health() async

Public health check endpoint.

Returns:

Type	Description
dict[str, str]	Dict with status 'ok'.

health_debug(user=Depends(require_admin)) async

System diagnostics endpoint — admin only.

Returns Python version, API key status, knowledge base size, embedding configuration, and environment variables (with secrets redacted).

Parameters:

Name	Type	Description	Default
user	dict	Decoded JWT payload — must have admin role.	Depends(require_admin)

Returns:

Type	Description
dict	Dict with system diagnostic information.

lifespan(app) async

Application lifespan — init DB, bootstrap admin, migrate legacy sessions on startup.

list_sessions(request, user=Depends(get_current_user)) async

List sessions for the authenticated user.

Parameters:

Name	Type	Description	Default
request	Request	Incoming request — carries the optional X-DEK header.	required
user	dict	Decoded JWT payload.	Depends(get_current_user)

Returns:

Type	Description
list[dict]	List of session dicts with id, title, created_at, updated_at,
list[dict]	and turn_count for each session.

login(body, response, request) async

Authenticate user with email/password, return JWT access token and set refresh cookie.

logout(request, response) async

Revoke refresh token and clear cookie.

rebuild_kb(user=Depends(require_admin)) async

Rebuild the knowledge base from source files.

Admin only. Re-processes all files in processed/ and stratcom/, rebuilding chunk vectors and saving to the vector pickle file. Returns a diff of files added, removed, and changed.

Parameters:

Name	Type	Description	Default
user	dict	Decoded JWT payload — must have admin role.	Depends(require_admin)

Returns:

Type	Description
dict	Dict with chunk count and diff dict (added, removed, changed lists).

refresh(request, response) async

Issue a new access token using a valid refresh token from the httpOnly cookie.

save_user_crypto(body=Body(..., embed=False), user=Depends(get_current_user)) async

Store the user's wrapped DEK and KDF salt (client-side crypto bootstrap).

The server stores only ciphertext key material: wrapped_dek is the DEK sealed with a password-derived KEK that never leaves the browser, and dek_salt is the public PBKDF2 salt. The server can never recover the DEK from these fields on its own.

Parameters:

Name	Type	Description	Default
body	dict	Dict with 'wrapped_dek' (envelope string) and 'dek_salt' (base64url 16-byte salt).	Body(..., embed=False)
user	dict	Decoded JWT payload.	Depends(get_current_user)

Returns:

Type	Description
dict	Dict with the new key_version.

Raises:

Type	Description
HTTPException	422 if fields are missing, 400 if malformed.

set_axes(body=Body(..., embed=False), user=Depends(get_current_user)) async

Update the global axis values.

Accepts partial updates — only provided keys are modified. Values are clamped to the range [-1.0, 1.0].

Parameters:

Name	Type	Description	Default
body	dict	Dict with any of 'ethical', 'alignment', 'social' keys.	Body(..., embed=False)
user	dict	Decoded JWT payload (any authenticated user).	Depends(get_current_user)

Returns:

Type	Description
dict	The updated axes dict with all three current values.

set_user_keys(body=Body(..., embed=False), user=Depends(get_current_user)) async

Save personal API keys for the current user.

Partial update — only provided keys are stored. Supported keys: deepseek, tavily, scrapingant. Values are Fernet-encrypted at rest.

Parameters:

Name	Type	Description	Default
body	dict	Dict with optional 'deepseek', 'tavily', 'scrapingant' string values.	Body(..., embed=False)
user	dict	Decoded JWT payload.	Depends(get_current_user)

Returns:

Type	Description
dict	Dict with updated key status for all three providers.