Init Project Flexly Estimator
This commit is contained in:
@@ -0,0 +1,123 @@
|
||||
# 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/<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):
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```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:<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 in New Issue
Block a user