Alkiviades — Development Setup¶

Prerequisites¶

Python 3.12+
Node.js 22+
Git

Quick Start¶

git clone https://github.com/Rumbleaxe/Alkiviades.git
cd Alkiviades

Backend¶

cd backend
pip install -r requirements.txt

# Create secrets file (copy template)
cp ../secrets.txt.template ../secrets.txt
# Edit secrets.txt with your DeepSeek and Tavily API keys

# Run CLI (builds knowledge base on first run)
python run.py

# Run web API
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Frontend¶

cd frontend
npm install
npm run dev -- --port 3001

Opens at http://localhost:3001. Backend at http://localhost:8000.

Combined (PowerShell)¶

.\start.ps1

Starts backend on port 8000 and frontend on port 3001.

Environment Variables¶

Variable	Default	Required	Purpose
`DEEPSEEK_API_KEY`	(from secrets.txt)	Yes	DeepSeek API key
`TAVILY_API_KEY`	""	For web search	Tavily search API key
`ALKIVIADES_ADMIN_EMAIL`	""	For web UI	Admin user email for bootstrap
`ALKIVIADES_ADMIN_PASSWORD`	""	For web UI	Admin user password
`JWT_SECRET`	(auto-generated)	Production	Stable JWT signing secret
`CORS_ORIGINS`	localhost origins	Production	Comma-separated allowed origins
`COOKIE_SAMESITE`	lax	Production	SameSite cookie attribute
`COOKIE_SECURE`	false	Production	Set to "true" for HTTPS
`COOKIE_DOMAIN`	""	Production	Cookie domain (e.g. ".alkiviades.cc")
`EMBED_DTYPE`	float16	Memory	TF-IDF precision (float32/float16)
`MAX_VOCAB_SIZE`	15000	Memory	Vocabulary size limit (0=no cap)
`VECTORS_MMAP`	true	Memory	Use mmap for vector loading
`DATABASE_URL`	.alkiviades.db	Override	SQLite database path

Project Structure¶

alkiviades/
├── backend/               # Python backend
│   ├── run.py             # CLI entry point
│   ├── build_kb.py        # Deploy-time KB builder
│   ├── requirements.txt
│   ├── tests/             # Pytest test suite
│   └── app/               # Application modules
│       ├── main.py        # FastAPI app
│       ├── agent.py       # Agent orchestrator
│       ├── rag.py         # RAG pipeline
│       ├── embed.py       # TF-IDF vectorizer
│       ├── tools.py       # Tool registry
│       ├── auth.py        # JWT + bcrypt auth
│       ├── database.py    # SQLite schema
│       ├── session.py     # Session persistence
│       ├── config.py      # Configuration
│       ├── utils.py       # Shared utilities
│       ├── prompt.py      # Prompt assembly
│       ├── models.py      # Data models
│       ├── files.py       # File I/O tools
│       ├── report.py      # Report generation
│       ├── stream_events.py  # SSE events
│       ├── user_store.py  # Agent registry
│       ├── logging_config.py # Logging setup
│       └── prompt.txt     # System prompt
├── frontend/              # Next.js frontend
│   └── src/
│       ├── app/           # Pages (landing, chat)
│       ├── components/    # React components
│       ├── hooks/         # Custom hooks
│       └── lib/           # API client, store, types
├── docs/                  # Documentation
├── Dockerfile             # Render deployment
├── processed/             # Preprocessed documents
├── stratcom/              # Strategy communications
├── knowledgebase/         # Curated references
├── party_docs/            # Raw source documents
├── preprocess.py          # HTML/PDF → markdown
└── batch_preprocess.py    # Batch preprocessor

Running Tests¶

# All unit tests (50 tests)
python -m pytest backend/tests/ -v --tb=short

# Exclude integration tests (no API key needed)
python -m pytest backend/tests/ \
  --ignore=backend/tests/test_auth_endpoints.py \
  --ignore=backend/tests/test_database.py \
  --ignore=backend/tests/test_streaming_agent.py \
  --ignore=backend/tests/test_httpx_streaming.py \
  --ignore=backend/tests/test_user_store.py \
  -v --tb=short

# Single file
python -m pytest backend/tests/test_rag.py -v

Knowledge Base Rebuild¶

# From project root
python backend/build_kb.py

# Via CLI
cd backend && python run.py  # then /rebuild

# Via API (admin only)
curl -X POST https://api.alkiviades.cc/rebuild \
  -H "Authorization: Bearer <token>"

Preprocessing Documents¶

# Single file
python preprocess.py "party_docs/some_file.html"

# All files
python batch_preprocess.py

Supports .html and .pdf. Uses beautifulsoup4, markdownify, pymupdf.