Files
2026-11-09 08:43:30 +03:00

7.5 KiB

estimator

Service for estimating labor effort and cost of work. An agent decomposes and estimates the work (LLM, structured output); a deterministic calculator turns hours into money.

Status: stages 1-5 of the plan are done (config, domain, pricing, versioned market data with market check, API-key auth, multi-provider LLM layer, agent pipeline, PostgreSQL/SQLite storage with migrations, background jobs and the REST API for estimates). The HTMX web UI is built too (see below). Next: RAG and calibration, then the MCP wrapper. See section 13 of docs/estimator-architecture.md for status and deviations from the design.

Docs

File What it covers
docs/estimator-architecture.md Layers, project structure, TOML + env config, ports, flow
docs/estimator-web-ui.md HTMX + Jinja interface that talks to the API
docs/bot-estimation-market-data.md Market data sources, ETL, analytics snapshot, worked examples

Quick start

python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env          # fill in secrets (a key per provider that a step uses)
python -m estimator migrate   # create the database schema
python -m estimator           # http://localhost:8000/health (docs at /docs)
pytest
ruff check .

Configuration

  • Non-secret settings: config/default.toml, overridden by config/<EST_ENV>.toml.
  • Secrets and environment-specific values: env vars with prefix EST_, nested with __ (for example EST_LLM__API_KEY).
  • EST_CONFIG_DIR points to another config directory (default config, relative to the working dir).
  • Market reference data (rates, benchmarks) is versioned in config/market/<version>.toml.
  • Unknown keys in any section fail at startup.

Priority, highest first: init args, env and .env, config/<env>.toml, config/default.toml, defaults in config/sections.py.

LLM providers

OpenAI (Chat Completions) and Anthropic (Messages) are supported. Each pipeline step has its own route in [llm.steps.<step>]: provider, model, max_tokens, optional temperature and reasoning_effort (OpenAI), and an optional [llm.steps.<step>.fallback]. API keys come from EST_LLM__ANTHROPIC__API_KEY and EST_LLM__OPENAI__API_KEY; only providers that a step uses need one.

Live check against the real APIs (skipped by default):

EST_LIVE_LLM=1 EST_LIVE_OPENAI_MODEL=<model id> pytest tests/integration/test_llm_live.py -s

Prompts are in prompts/*.md; their hash is written to the audit log of every step.

Database

EST_DATABASE__DSN accepts postgresql://... (production, JSONB) or sqlite:///path.db (development). Apply migrations with python -m estimator migrate; the service refuses to start without a schema. Each estimate is an append-only list of versions: answers, recalculation and manual edits create a new version and keep the old ones.

API in short

curl -s -X POST localhost:8000/api/estimates -H "X-API-Key: <key>" -H "Idempotency-Key: job-42" \
     -H "Content-Type: application/json" \
     -d '{"requirements": "Telegram bot with a knowledge base and amoCRM", "region": "ru"}'
# -> 202 {"id": "...", "status": "pending", ...}   then poll GET /api/estimates/{id}

Statuses: pending, running, needs_input (answer via /answers), done, failed. The service runs background jobs inside the process, so run a single instance for now.

Tests

pytest                                                   # SQLite
TEST_PG_DSN=postgresql://user@host:5432/testdb pytest    # SQLite and PostgreSQL (drops the tables in testdb)

Web UI

Off by default. To enable it:

python -m estimator hash-password          # asks for a password (12+ characters), prints a hash
export EST_WEB__ENABLED=true
export EST_WEB__SESSION_SECRET=$(python -c "import secrets; print(secrets.token_urlsafe(48))")
export EST_WEB__USERS="alex:<hash from above>,bob:<another hash>"
python -m estimator                        # http://localhost:8000/ui/

Settings are in [web] of config/default.toml: workspace (shared or per_user), timezone, poll_interval_s, cookie_secure (set it behind HTTPS; prod.toml already does), login throttling. Behind a reverse proxy start uvicorn with --proxy-headers. The UI has no Node dependency; htmx is vendored in src/estimator/web/static/ (see VENDOR.md).

Pricing in short

without reserve = sum(hours x rate) x (1 + PM) x (1 + markup)          # a markup: 20% markup = 16.7% margin
reserve hours   = max(1.04 x sigma, 10% of expected hours)             # one reserve, added once
with reserve    = without reserve x (1 + reserve hours / expected hours)

Each estimate is sold either as fixed price (the price with the reserve is quoted) or as time and materials (the expected cost is quoted, the reserve becomes a budget ceiling, and client hourly rates per role are shown). Choose it per estimate in the UI or with engagement in the API, default in [pricing] default_engagement; switching a finished estimate creates a new version without a model call. The rates and parameters used are stored with every result, so repricing never depends on today's files. Reasoning and numbers: docs/adr/0001-reserve-policy-and-engagement.md.

VAT

Everything is calculated without VAT; VAT is added on top when quoting. The rate is chosen per estimate (default by the client's region in [pricing.vat]: Russian client 22%, EU client none) and stored with the version; changing it creates a new version without recalculation. Market benchmarks carry includes_vat/vat_rate and are converted to prices without VAT before the check. See docs/adr/0002-vat-layer.md.

Reference tasks (RAG)

Similar past work can anchor the estimate of every task. It is off by default; load a corpus first.

# refs.csv (UTF-8, header row): project,title,description,role,hours,hours_kind,source
#   role: analyst|backend|frontend|qa|devops|designer (may be empty); hours_kind: actual|estimate
python -m estimator rag import refs.csv --dry-run     # validate only
python -m estimator rag import refs.csv               # load and embed
python -m estimator rag stats                         # size and state of the corpus
python -m estimator rag search "integration with a CRM" --role backend
export EST_RAG__ENABLED=true                          # then switch retrieval on

PostgreSQL uses pgvector with an HNSW index (the migration runs CREATE EXTENSION vector, so the extension must be installed on the server); SQLite searches in Python, which is fine for development. Embeddings come from an OpenAI-compatible /embeddings endpoint (EST_RAG__API_KEY, or the OpenAI key of the llm section); EST_RAG__PROVIDER=hash is a weak offline embedder for development and tests. The vector size is fixed at 1536 by the schema. Details and limits: docs/adr/0003-rag-reference-tasks.md.

Docker

cp .env.example .env              # POSTGRES_PASSWORD, LLM key(s), EST_API__KEYS
docker compose up -d --build      # db -> migrate (applies the schema, then exits) -> app
curl http://localhost:8000/health

Start order: the database becomes healthy, the one-shot migrate service applies the migrations, and only if it succeeds does app start. MIGRATE_ON_START=true does the same inside one container. Backups, updates, creating UI users, loading the RAG corpus and running behind a reverse proxy: docs/deployment.md. The image runs as a non-root user and uses EST_ENV=prod (secure session cookies).