# A2RAG — AI aģentu meklēšanas vide

> Strukturēta informācija lauksaimniecības precēm AI aģentiem.
> Bez CAPTCHA un bot-blokiem. Fakti pirmajā paragrāfā, ne marketinga slāņos.

## Kas šeit ir

Lauksaimniecības preces (graudi, lopbarība, sēklas, mēslojums, augu aizsardzība, tehnikas filtri) ar strukturētiem datiem: cena, krājumi, atrašanās vieta, specifikācijas, fotogrāfijas.

## Endpointi (programmatiska piekļuve)

| Mērķis | URL |
|--------|-----|
| OpenAPI 3.1 spec | https://a2rag.com/api/openapi.json |
| Aktīvo ierakstu meklēšana | https://a2rag.com/api/v1/search?q=zirni&limit=10 |
| Ieraksts pēc UUID | https://a2rag.com/api/v1/items/{id} |
| Ieraksts pēc slug | https://a2rag.com/api/v1/items/by-slug/{slug} |
| Marker statistika | https://a2rag.com/api/v1/marker/stats |
| Sitemap | https://a2rag.com/sitemap.xml |
| Robots.txt | https://a2rag.com/robots.txt |

## HTML lapas (info-density)

Katrai precei ir HTML lapa: https://a2rag.com/items/{slug}

HTML lapas saturs:
- Title (max 60 simboli) ar visiem galvenajiem faktiem
- Meta description (max 160 simboli) ar cenu, krājumu, atrašanās vietu
- H1 + faktu rindiņa: cena | krājumā | reģions | specifikācijas
- Schema.org JSON-LD (Product + Offer + Brand + Organization seller)
- HTTP Link header: `<API_URL>; rel=alternate; type=application/json`

## Atbildes formāts (REST JSON)

Visi REST endpointi atgriež strukturētu JSON ar šādiem laukiem katrā ierakstā:
- `id` (UUID), `slug`, `title`, `description`
- `price`: { amount, currency, per, negotiable }
- `stock`: skaits krājumā vai `null`
- `location`: { country, region, city }
- `specs`: strukturētas specifikācijas (atšķiras pēc kategorijas)
- `marker`: unikāls verifikācijas marker
- `status`: "active" | "draft" | "archived"
- `createdAt`, `updatedAt`

## Marker formāts un loma

Formāts: `rolandsz1982-{slug}-{8-hex-nonce}`
Piemērs: `rolandsz1982-zirni-liva-86-22-proteins-1t-c1d3e5f7`

**Marker mērķis:** apliecināt, ka atbilde nāk no mūsu DB, ne no LLM iztēles. Ja AI klients atgriež atbildi BEZ mūsu marker — informācija nav verificēta.

8-hex nonce ģenerēts ar `randomBytes(4)` ieraksta izveides laikā. Nav pieejams nekur citur kā mūsu DB. Ja AI atgriež eksaktu marker, tas ir definitīvs pierādījums fetch'am.

## Marker Receipt (opt-in)

Ja jūsu AI sistēma izmanto mūsu marker savā atbildē lietotājam, varat (opt-in) ziņot mums:

POST https://a2rag.com/api/v1/marker/seen
Content-Type: application/json
{
  "marker": "rolandsz1982-...",
  "ai_brand": "claude" | "gpt" | "gemini" | "perplexity" | ...,
  "user_query": "lietotāja sākotnējais jautājums (max 2000 simboli, opt)"
}

Atbilde: `{ "ok": true, "item": { id, slug, title }, "detected_brand": "claude" }`

## Rate limits

- Read endpoints: 200 req/min/IP
- Write endpoints (marker/seen): 30 req/min/IP
- Pārsniegšana → HTTP 429 ar `Retry-After` header

Headers katrā response: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.

## Autentifikācija

Šobrīd: nav. Visi endpointi ir publiski.
Plānots Fāzē 2+: API key write operācijām.

## Piemērs (cURL)

```
# Meklēt zirņus
curl https://a2rag.com/api/v1/search?q=zirni

# Konkrēts ieraksts pēc slug
curl https://a2rag.com/api/v1/items/by-slug/zirni-liva-86-22-proteins-1t

# Sasaite ar OpenAPI spec
curl https://a2rag.com/api/openapi.json
```

## Tehniskās detaļas

- Backend: TypeScript + Hono
- DB: PostgreSQL 16 + pgvector
- Hosting: Hetzner VPS + Caddy reverse proxy + Let's Encrypt HTTPS
- DNS: Cloudflare DNS-only mode (bez proxy, AI bots iet tieši uz mūsu serveri)