docs/GUEST_DISCOVERY_INTEGRATION.md

Guest Discovery Integration

Goal

External AI assistants are another doorway into Lojiz, not an alternative to AIDA. Guests can discover public listings without creating a Lojiz account. AIDA remains the only component that searches, ranks, recommends, compares, and explains properties.

Architecture

User -> external assistant -> /mcp on the AIDA Space -> AIDA discovery pipeline -> public listing cards -> exact Lojiz URL

The MCP surface runs in the AIDA FastAPI process and calls the existing Guest Mode services directly. It never receives a Lojiz user token. The protected REST Integration API remains available for future trusted adapters.

Backend endpoints

All routes are under /api/integrations/guest and require X-Lojiz-Integration-Key.

• GET /capabilities: Guest Mode and handoff boundary.
• POST /discover: natural-language public search or recommendation.
• POST /similar: AIDA-ranked alternatives to a public listing.
• POST /compare: fact-grounded comparison of two to five public listings.
• POST /events: presentation/open/limit analytics from trusted adapters.

X-Lojiz-Provider identifies the discovery channel and is normalized before it is used for analytics or UTM attribution.

Public data contract

The API returns an allowlisted card DTO: immutable public ID, title, sanitized summary, type, price, currency, period, location, public features, up to three public images, one public video, aggregate rating, verified-host flag, AIDA match reason, and canonical public URL.

It does not return MongoDB IDs, owner phone numbers, WhatsApp details, email addresses, claim tokens, private account data, or write capabilities. The backend re-fetches each search result from MongoDB before disclosure so stale vector payloads cannot expose inactive or unavailable listings.

Free Guest Mode

• Public natural-language listing search.
• Public recommendations from AIDA.
• Public property comparisons.
• Similar-property discovery.
• Public listing previews and photos.
• Recommendation explanations.
• Open the exact listing on Lojiz.

Continue on Lojiz

The external assistant must hand off for favorites, saved searches, alerts, contacting owners or hosts, bookings, scheduled visits, roommate matching, private messages, listing creation or management, account history, premium AIDA, and subscription management.

Configuration

Python backend:

• GUEST_INTEGRATION_API_KEYS: comma-separated, rotatable server credentials.
• GUEST_INTEGRATION_RATE_LIMIT: default 20/minute per integration route.
• GUEST_INTEGRATION_ALLOW_UNAUTHENTICATED_DEV: default false; never enable in production.
• PUBLIC_WEB_URL: canonical public listing origin.

Same-Space MCP endpoint:

• LOJIZ_MCP_PROVIDER: analytics attribution; defaults to chatgpt.
• LOJIZ_WIDGET_RESOURCE_DOMAINS: approved public image/CDN origins.
• MCP_RATE_LIMIT_PER_MINUTE: public MCP request limit; defaults to 30.

No second service, MCP port, base URL, or MCP-to-backend integration key is required.

Security and reliability

• Rotate integration keys without changing user accounts.
• Store keys only in deployment secret managers.
• Keep the MCP endpoint on public HTTPS with a stable /mcp URL.
• Keep the MCP request limiter enabled.
• Protected REST Integration API rate limits remain authoritative for external adapters.
• Tool errors are generic; credentials and raw upstream errors are never returned.
• Listing text is scrubbed for phone numbers, emails, and URLs before disclosure.
• Only public HTTPS media URLs are returned.
• Analytics failures never block discovery.

Analytics

The guest_discovery_events collection records provider, anonymous session ID, event type, sanitized query, public listing IDs, small scalar metadata, and timestamp. It does not identify a Lojiz account. Indexes cover provider, session, and event type by recency.

Deployment sequence

1. Deploy the AIDA backend with the same-process MCP files and mcp==1.29.0.
2. Verify /health and /mcp over HTTPS on the existing AIDA hostname.
3. Run MCP Inspector against https://destinyebuka-aida.hf.space/mcp.
4. Connect the same endpoint in ChatGPT developer mode.
5. Test direct, indirect, multilingual, empty-result, unavailable-listing, and out-of-scope prompts.
6. Confirm account actions lead to Lojiz rather than being completed inside the assistant.
7. Review analytics and rate-limit behavior before publishing.

Other assistants can use the same MCP service when compatible, or receive a thin adapter over the same Integration API. Provider-specific adapters must not reimplement ranking.