# 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](docs/estimator-architecture.md) | Layers, project structure, TOML + env config, ports, flow | | [docs/estimator-web-ui.md](docs/estimator-web-ui.md) | HTMX + Jinja interface that talks to the API | | [docs/bot-estimation-market-data.md](docs/bot-estimation-market-data.md) | Market data sources, ETL, analytics snapshot, worked examples | ## Quick start ```bash 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/.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/.toml`. - Unknown keys in any section fail at startup. Priority, highest first: init args, env and `.env`, `config/.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.]`: provider, model, `max_tokens`, optional `temperature` and `reasoning_effort` (OpenAI), and an optional `[llm.steps..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): ```bash EST_LIVE_LLM=1 EST_LIVE_OPENAI_MODEL= 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 ```bash curl -s -X POST localhost:8000/api/estimates -H "X-API-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 ```bash 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: ```bash 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:,bob:" 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. ```bash # 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 ```bash 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).