# Pequi — Full AI-Powered Real Estate Platform Reference
> https://xpequi.xyz | Ibagué, Tolima, Colombia
> This file provides comprehensive documentation for AI crawlers and agents.

## Platform Overview

Pequi is an AI-powered real estate platform specialized in Ibagué, Tolima, Colombia. It combines property search, legal contract generation, digital payments, and an AI chat agent with 15 function-calling tools. Built with Next.js 15 and deployed on Vercel Edge.

### Target Users
- **Renters**: Search properties, sign digital contracts, pay rent via Wompi
- **Landlords**: List properties, manage tenants, receive rent payments
- **Buyers**: Find properties for sale, get investment analysis
- **Agents**: Multi-property management with AGENTE subscription ($30K COP/mo)
- **Complex Admins**: Manage residential complexes, collect admin fees (cuotas de administración)
- **Unit Owners**: Pay admin fees, track payment status

## Important Pages

| Page | URL | Description |
|------|-----|-------------|
| Home | https://xpequi.xyz/ | Landing page with property grid, search, and feature overview |
|| Blog | https://xpequi.xyz/blog | Blog inmobiliario — guías de arriendo, barrios y Ley 820 en Ibagué |
|| Property Search | https://xpequi.xyz/busca | Full search with map view, filters, infinite scroll |
|| AI Chat | https://xpequi.xyz/ai | Conversational AI agent with 16 tools |
| Pricing | https://xpequi.xyz/precios | Subscription plans (FREE, AGENTE, CONJUNTO) |
| Documentation | https://xpequi.xyz/docs | Platform documentation |
| Legal | https://xpequi.xyz/legal | Terms, privacy policy, Ley 820 info |
| About | https://xpequi.xyz/about | About Pequi |
| Dashboard | https://xpequi.xyz/dashboard | Role-based dashboard (auth required) |
| Property Detail | https://xpequi.xyz/propiedades/[id] | Individual property page with map, photos, contact |
| Complex Portal | https://xpequi.xyz/conjuntos/[slug] | Residential complex page with units and contact |
| Saved Properties | https://xpequi.xyz/saved | User's saved/favorited properties (auth required) |
| Messages | https://xpequi.xyz/messages | User-agent messaging (auth required) |
| Contracts | https://xpequi.xyz/contracts | Contract management (auth required) |
| Profile | https://xpequi.xyz/profile | User profile and settings (auth required) |

## Public API Endpoints

### Properties
- `GET /api/properties` — Search/filter properties. Params: `city`, `type`, `listingType`, `minPrice`, `maxPrice`, `bedrooms`, `bathrooms`, `neighborhood`, `complexName`, `limit`, `offset`
- `GET /api/properties/feed` — RSS-style property feed
- `POST /api/properties` — Create property listing (auth required, AGENTE+ plan)

### Complexes
- `GET /api/complexes` — List residential complexes
- `GET /api/complexes/[slug]` — Complex detail with units
- `GET /api/complexes/[slug]/properties` — Properties in a complex
- `GET /api/complexes/[slug]/units` — Units in a complex
- `GET /api/complexes/qr` — QR code generation for complexes

### AI Chat
- `POST /api/chat` — AI chat with streaming SSE response. Body: `{ messages, sessionId? }`. Supports 15 function-calling tools. Rate limited: 30 req/min (IP), 50 req/min (authenticated user).
- `GET /api/ai-status` — AI provider health check

### Contracts
- `GET /api/contracts` — List user contracts (auth required)
- `POST /api/contracts` — Create contract (auth required)
- `POST /api/contracts/generate` — Generate Ley 820 compliant contract
- `POST /api/contracts/analyze` — Analyze contract for illegal clauses
- `GET /api/contracts/[id]` — Contract detail
- `POST /api/contracts/[id]/generate-pdf` — Generate PDF
- `POST /api/contracts/[id]/send-signature-request` — Send e-signature request
- `POST /api/contracts/[id]/sign` — Sign contract with verification code

### Payments (Wompi)
- `POST /api/payments/create` — Create Wompi payment link
- `GET /api/payments/status/[paymentId]` — Payment status
- `GET /api/payments/history` — Payment history per tenancy
- `POST /api/payments/webhook/wompi` — Wompi webhook (SHA-256 verified)

### Subscriptions
- `GET /api/subscriptions/plans` — Available plans
- `GET /api/subscriptions/me` — Current subscription
- `POST /api/subscriptions/checkout` — Initiate subscription checkout
- `POST /api/subscriptions/addon` — Purchase addon blocks
- `POST /api/subscriptions/cancel` — Cancel subscription

### User
- `GET /api/user/profile` — User profile
- `GET /api/user/stats` — Dashboard statistics
- `POST /api/user/role` — Switch active role
- `GET/POST /api/user/bank-info` — Bank account info for payouts

### Visits
- `POST /api/visits` — Schedule a property visit. Body: `{ propertyId, date, duration?, notes? }`. Validates: not past, max 30 days ahead, no doubles per day, max 3/day.
- `GET /api/visits/mine` — Get all user's visits (as visitor + landlord)
- `GET /api/visits?propertyId=X` — Get visits for a property (landlord gets all, others get own)

### Other
- `GET /api/health` — Platform health check (version, region, checks)
- `GET /api/recommendations` — Property recommendations
- `POST /api/upload` — File upload (5MB max, images/PDFs)

## AI Chat Tools (16 Function-Calling Tools)

### Property Tools
- `analyzeProperty` — Investment analysis for a specific property (yield, ROI, risk score)
- `getNeighborhoodInfo` — Area insights, average prices, estrato, market data for Ibagué barrios
- `compareProperties` — Compare 2+ properties, rank by investment score
- `getEstratoInfo` — Official DANE estrato (1-6) for Ibagué neighborhoods
- `getComplexInfo` — Residential complex data (Fortezza, Arboleda, Leforet, M-Treinta, etc.)

### Legal & Contract Tools
- `searchLegalDatabase` — Search Ley 820/2003, Ley 675/2001, Ley 142/1994
- `getClosingCosts` — Calculate closing costs (gastos de escrituración)
- `generateContract` — Generate Ley 820 compliant contracts from templates
- `analyzeContract` — Detect illegal clauses in uploaded contracts
- `generateContractPDF` — PDF generation for contracts
- `sendSignatureRequest` — Digital signature workflows

### Market Intelligence Tools
- `getMarketTrends` — Market trends, yield, vacancy, investment scores
- `getInvestmentAdvice` — Personalized recommendations by budget

### Scheduling
- `scheduleVisit` — Schedule property visits (creates via POST /api/visits)

### Property Management
- `createProperty` — Publish new property listing
- `analyzeDocument` — Upload and analyze PDFs, contracts, invoices, IDs

## AI Provider Chain
```
Primary: DeepSeek V4 Flash (direct API, 256K context, $0.14/$0.28 per M tokens)
  → Fallback 1: Groq Llama 4 Scout (free, 30 RPM, fast inference)
  → Fallback 2: OpenRouter nemotron-nano (free, 31B)
  → Fallback 3: OpenRouter gemma-4-31b (free, 262K context)
  → Emergency: Static knowledge base (regex-based)
```

Features: Smart reasoning toggle (high/medium/low based on query intent), dynamic tool selection (only relevant tools per request), Redis session memory (24h TTL), streaming SSE responses, user-ID rate limiting.

## Data Format
- **Currency**: COP (Colombian Pesos). All prices in whole pesos.
- **Language**: Spanish (es-CO). All user-facing text in Spanish.
- **Property Types**: APARTMENT, HOUSE, ROOM, COMMERCIAL, OTHER
- **Listing Types**: RENT, SALE
- **Estratos**: 1-6 (official DANE socioeconomic stratification)
- **Locations**: 64 Ibagué neighborhoods, 8 Tolima cities (Ibagué, Cajamarca, Coello, Espinal, Mariquita, Líbano, Honda, Melgar)

## Property Data Structure
```json
{
  "id": "uuid",
  "name": "Apartamento Centro Histórico",
  "address": "Cra 3 #5-20, Ibagué",
  "city": "Ibagué",
  "propertyType": "APARTMENT",
  "listingType": "RENT",
  "monthlyRent": 1200000,
  "salePrice": null,
  "bedrooms": 2,
  "bathrooms": 1,
  "area": 65,
  "description": "Hermoso apartamento...",
  "images": ["https://..."],
  "complexName": "Fortezza Torres del Parque",
  "status": "ACTIVE"
}
```

## Subscription Plans
| Plan | Price (COP) | Properties | Features |
|------|-------------|------------|----------|
| FREE | $0 | 1 | Basic listing, AI chat, property search |
| AGENTE | $30K/mo or $300K/yr | 10 (+$15K/addon block) | Contracts, payments, analytics |
| CONJUNTO_50 | $50K/mo or $500K/yr | 50 units | Complex management, admin fee collection |
| CONJUNTO_150 | $150K/mo or $1.5M/yr | 150 units | Full complex suite |

## Legal Compliance
- **Ley 820 de 2003**: All rental contracts comply. Illegal clause detection (caución/deposit exceeding limits, unauthorized evictions).
- **Ley 527 de 1999**: Digital signatures recognized.
- **Ley 675 de 2001**: Property horizontals (conjuntos residenciales).
- **Ley 142 de 1994**: Public services framework.

## Public API Platform

Pequi offers a public REST API for real estate data. SDK and MCP server are open source.

- GitHub Repo: https://github.com/MCPVOT/xpequi-api
- TypeScript SDK: npm install @MCPVOT/api-client
- MCP Server: npx @MCPVOT/mcp-server (Claude Desktop, Cursor, Copilot)

### REST Endpoints (v1)
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | /api/v1/properties | Search properties with filters |
| GET | /api/v1/barrios | Neighborhoods with estrato + GIS |
| GET | /api/v1/benchmarks | Price per m benchmarks |
| GET | /api/v1/geocode | Address to lat/lng |

### Pricing: FREE ($0), AGENTE ($30K/mo), CONJUNTO ($150K/mo), ENTERPRISE (custom)

## Tech Stack
| Layer | Technology | Version |
|-------|-----------|---------|
| Framework | Next.js | 15.5 |
| UI | React | 19 |
| Styling | Tailwind CSS | 4 |
| Database | PostgreSQL (Neon) + Prisma | 6.x |
| Auth | Clerk | 6.x |
| AI | DeepSeek V4 Flash + Groq + OpenRouter | - |
| Payments | Wompi | Production |
| Cache | Upstash Redis | Free tier |
| Hosting | Vercel | Edge |
| Maps | Leaflet + OpenStreetMap | - |
| WhatsApp | Meta Cloud API | v25.0 |
| PDF | @react-pdf/renderer | 4.x |

## Robots & Crawling
- robots.txt: https://xpequi.xyz/robots.txt (allows GPTBot, Anthropic-AI, CCBot, PerplexityBot, Google-Extended)
- sitemap.xml: https://xpequi.xyz/sitemap.xml (static + dynamic pages)
- llms.txt: https://xpequi.xyz/llms.txt (this summary)
- llms-full.txt: https://xpequi.xyz/llms-full.txt (this full reference)