Skip to content

SOW.md

Latest commit

 

History

History
208 lines (144 loc) · 6.95 KB

SOW.md

File metadata and controls

208 lines (144 loc) · 6.95 KB

SOW — Agentic Search Optimization Engine

1. Цель

Разработать Python-сервис с CLI-клиентом, который автоматически:

  1. получает SEO-сигналы целевого сайта;
  2. формирует гипотезы ниши;
  3. собирает и/или принимает конкурентов из SERP;
  4. анализирует контентные и keyword gaps;
  5. возвращает структурированное SEO-ядро и рекомендации.

2. Что было скорректировано в исходной постановке

2.1 Ниша

Полностью автоматически и безошибочно определить нишу нельзя, если у агента нет входных ограничений. Поэтому корректная модель такая:

  • агент предлагает 2–3 гипотезы ниши;
  • гипотезы строятся по SEO-сигналам целевого сайта;
  • пользователь или следующий слой системы может подтвердить гипотезу.

Это соответствует ранее согласованному варианту Option B.

2.2 SERP и конкуренты

Топ сайтов нельзя считать универсальным без параметров:

  • GEO
  • язык
  • search engine
  • device
  • query set

Поэтому корректная логика:

  • по каждой SERP-запросной группе агент собирает результаты;
  • хранит массив до 10 результатов;
  • в итоговый shortlist выделяет 5 основных конкурентов;
  • расширяет shortlist до 10, если результаты сильно различаются по интенту или сегменту.

2.3 LLM

LLM не должен быть первым источником истины. Корректный пайплайн:

  1. собрать crawl / on-page / competitor / SERP данные;
  2. нормализовать сигналы;
  3. затем использовать LLM для оценки, резюмирования и приоритизации.

3. In Scope

Phase 1 — MVP CLI

  • Python CLI-приложение
  • анализ одной целевой страницы или локального HTML
  • извлечение title, meta description, meta keywords, headings, links
  • heuristic niche discovery
  • сравнение с переданными конкурентами
  • построение keyword opportunities / SEO core
  • вывод в text / json

Phase 2 — Smart data acquisition

  • подключение SERP API или search provider
  • сбор top-5 / top-10 конкурентов
  • page-type classification
  • начальная site-wide агрегация

Phase 3 — LLM layer

  • LLM-based scoring
  • entity normalization
  • search intent enrichment
  • content brief generation
  • page recommendations

Phase 4 — Production system

  • API + job queue
  • persistence layer
  • dashboard
  • scheduled re-runs
  • exports and integrations

4. Out of Scope для текущего MVP

  • full-site distributed crawling
  • production SERP scraping at scale
  • bypass anti-bot protections
  • rank tracking history
  • external billing
  • multi-tenant auth

5. Входные данные

Обязательные:

  • target_domain или target_url или локальный HTML-файл

Опциональные:

  • competitor_sources[]
  • serp_file
  • geo
  • language
  • search_engine
  • max_competitors
  • max_core_terms

6. Выходной результат

Сервис должен возвращать объект с блоками:

  • niche_hypotheses
  • target
  • competitors
  • seo_core
  • insights
  • warnings

Каждый элемент seo_core должен включать:

  • term
  • cluster
  • intent
  • priority
  • source
  • competitor_count
  • target_score
  • competitor_score
  • supporting_terms
  • rationale

7. Functional requirements

FR-1. Target analysis

Система должна уметь анализировать локальный HTML, URL и домен.

FR-2. On-page extraction

Система должна извлекать базовые SEO-сигналы страницы.

FR-3. Niche hypotheses

Система должна возвращать до 3 гипотез ниши на базе найденных терминов.

FR-4. Competitor comparison

Система должна сравнивать целевую страницу с конкурентами и выделять overlap / gaps.

FR-5. SEO core generation

Система должна формировать итоговое SEO-ядро с приоритетом и обоснованием.

FR-6. Flexible competitor input

Система должна принимать конкурентов как повторяемые CLI-аргументы и как JSON-массив.

8. Non-functional requirements

  • простота локального запуска;
  • отсутствие обязательных внешних зависимостей в MVP;
  • расширяемость до API-first архитектуры;
  • детерминированный offline-friendly режим тестирования;
  • совместимость с Windows shell и локальным запуском Python.

9. Deliverables

Реализовано в текущем инкременте

10. Acceptance criteria для MVP

MVP считается принятым, если:

  1. запускается через CLI;
  2. принимает целевой сайт и конкурентов;
  3. извлекает SEO-сигналы из HTML;
  4. возвращает гипотезы ниши;
  5. строит keyword opportunities;
  6. проходит локальные unit tests;
  7. поддерживает JSON output.

11. Риски

  • SERP без API нестабилен и зависит от anti-bot ограничений;
  • нишевая классификация по heuristics ограничена;
  • keyword scoring без search volume является относительным, а не абсолютным;
  • без LLM и внешних SEO-данных приоритизация пока упрощённая.

12. Recommendation

Для production-версии рекомендован стек:

  • Python как core backend;
  • CLI + позже FastAPI;
  • optional Redis/PostgreSQL;
  • external SERP / SEO APIs;
  • LLM layer после стабилизации data pipeline.