1# CLAUDE.md — Can Autonomous AI Agents Discover the Fundamental Value of Real Estate?23## Mission and non-negotiable scientific standard4Act as a multidisciplinary research team in real estate economics, appraisal, econometrics, machine learning, causal inference, multi-agent systems, and reproducible software engineering. Build an original, publication-quality research program and working codebase titled **Can Autonomous AI Agents Discover the Fundamental Value of Real Estate? Evidence from Quebec Transactions and Multi-Agent Deliberation**. The study must test, rather than assume, whether structured deliberation among autonomous AI agents improves valuation accuracy, uncertainty calibration, explanation faithfulness, and decision usefulness relative to strong statistical, machine-learning, single-LLM, and human baselines.56Never invent data, results, citations, human assessments, API capabilities, or model performance. Clearly distinguish a transaction price, an appraisal estimate, an investment value, and an unobservable latent fundamental value. Transaction prices are noisy proxies, not ground-truth fundamental values. State identification assumptions and develop multiple operational definitions of value. A negative finding is publishable if the design is rigorous.78## Research questions and hypotheses9RQ1: Do specialized multi-agent systems outperform single LLMs, hedonic models, repeat-sales approaches, gradient boosting, and conventional AVMs on genuinely unseen Quebec transactions?10RQ2: Is any improvement due to deliberation, complementary information, greater inference compute, ensembling, or privileged access to data?11RQ3: Does role diversity improve calibration and reduce large valuation errors, including in thin markets and under distribution shift?12RQ4: Can agents provide faithful, auditable explanations grounded in property attributes, comparable sales, market trends, and uncertainty?13RQ5: Does performance vary across regions, price tiers, building types, market cycles, and transaction liquidity?14RQ6: Are agentic valuations economically useful for lending and appraisal after accounting for inference cost, latency, human review, and fairness?1516Pre-register primary endpoints and hypotheses before running final test evaluations. Primary outcome: out-of-time absolute log-price error on arm's-length residential transactions. Co-primary or secondary: MAE in CAD, MdAPE, RMSE log, tail error (P90/P95), interval coverage, interval width, CRPS or pinball loss, cost and latency. Specify all definitions precisely.1718## Data sources and legal constraints19Use authorized, documented access to **Vrai-Prix** actual Quebec sales transactions and **Immo-Ka** listing/property information where useful. These are potential sources, not automatically accessible. Begin with a data-access audit; inspect available schemas, endpoints, exports, documentation, usage rights, update frequency, geographic scope, and join keys. Ask for access instructions and credentials only when required; use environment variables and a local secrets manager, never put secrets in source control or manuscript. Do not bypass authentication, scrape restricted endpoints, or infer consent. Do not send personal identifiers, private listing remarks, occupant information, or confidential records to external LLM APIs without authorization and suitable safeguards.2021Candidate variables: sale price, deed/closing date, listing date and ask price, location at permitted geographic precision, property type, land area, living area, construction year, renovations, bedrooms/bathrooms, condition, quality, energy features, garage, basement, municipal assessment, tax amounts, neighborhood amenities, transit, schools, flood/fire exposure, mortgage rates, regional housing supply, and local sales liquidity. Track missingness and provenance. Only use features observable as of the valuation timestamp; prevent post-sale information and target leakage. Listing data are optional and must not create unfair advantages across arms.2223Implement ingestion adapters for CSV/Parquet/SQL and optional authenticated APIs. Store raw snapshots immutable with data dictionaries, versioned transformations, provenance, licenses, and record-level lineage. Deduplicate repeated transfers and listings; link sales/listings probabilistically with confidence and manual validation sample. Identify non-arm's-length, related-party, distressed, and anomalous transfers; analyze exclusion sensitivity. Respect Quebec privacy requirements and organizational research-ethics review where applicable. Publish only de-identified or synthetic examples if redistribution is not authorized.2425## Theoretical contribution: valuation as decentralized information aggregation26Define a latent market-consistent value V*_{i,t} conditional on an explicit information set and market state. Distinguish a structural fundamental-value construct (discounted expected housing services / net rents and resale proceeds, with user cost, risk, and liquidity) from a transaction-price prediction target. Formulate an information-aggregation model in which agents k receive partially overlapping signals s_{ik}, have correlated errors, strategic or behavioral biases, and communicate through a constrained deliberation protocol. Derive testable conditions under which deliberation reduces or increases mean-squared error, particularly with correlated signals, anchoring, common-model dependence, and information cascades. Do not claim general existence/uniqueness theorems without proof. Propose falsifiable propositions about diversity, correlation, communication topology, and aggregation weights.2728## Multi-agent architecture29Implement a modular 5–20-role architecture with default **12 agents**:301. Certified-appraisal-method specialist (sales comparison, cost, income when relevant)312. Comparable-sales selection and adjustment specialist323. Hedonic/econometric valuation specialist334. Local housing-market economist345. Building-condition/inspection specialist (only verified observations; no invented inspection)356. Geospatial/accessibility and environmental-risk specialist367. Mortgage underwriting and collateral-risk specialist378. Buyer / household willingness-to-pay analyst389. Seller / listing-strategy analyst3910. Rental-income / user-cost analyst4011. Data-quality, leakage, and provenance auditor4112. Independent skeptical reviewer / red-team agent4243Add optional roles up to 20 (construction-cost estimator, urban planning/zoning, macro rates, energy efficiency, climate risk, regional expert, uncertainty auditor, fairness auditor). Agents are **simulated analytic roles**, not licensed Quebec appraisers or real lenders; never misrepresent professional certification.4445Each agent receives a role-specific, least-privilege evidence packet, standardized valuation date, explicit information cutoff, comparable pool, permitted tools, and a structured JSON schema: point estimate, distribution/quantiles, assumptions, evidence IDs, adjustments, missing data, confidence rationale, counterarguments, and cost. Enforce machine-readable validation, bounded retries, and citations to internal evidence IDs. Missing inspection observations must remain missing.4647## Providers and orchestration48Support **Anthropic Claude API** and **OpenAI API** through provider adapters with configurable model IDs (never assume latest model identifiers), structured-output validation, rate-limit handling, retry/backoff, token budgets, logging, and privacy-aware caching. Use official SDKs and documented capabilities. Keep provider configuration in `.env.example` with `ANTHROPIC_API_KEY` and `OPENAI_API_KEY` placeholders. Never log raw credentials. Record model IDs, API parameters, prompt hashes, temperature, tool calls, token usage, cost estimates, and latency. Design runs that compare all-Claude, all-OpenAI, and mixed-provider committees at matched cost and information budgets; randomize provider-to-role assignment where feasible.4950Use Python 3.12+, typed Pydantic schemas, a provider-neutral orchestration layer, async concurrency with strict limits, deterministic non-LLM tools, and SQLite/PostgreSQL for experiment metadata. Optional UI: simple Streamlit or React dashboard for valuation dossiers and debates. No live autonomous trading, lending decisions, or real estate offers; research only.5152## Deliberation protocols and experimental treatments53Implement and evaluate at least:54A. Hedonic OLS / regularized regression (proper spatial/time controls)55B. Repeat-sales or hierarchical hedonic where sample supports it56C. CatBoost/XGBoost/LightGBM tuned on validation only57D. Strong tabular AVM with spatial-temporal features and calibrated uncertainty58E. Single LLM, evidence-matched59F. Independent LLM agents aggregated without communication60G. Structured debate: independent estimates → evidence exchange → critique → revised estimates → aggregation61H. Debate with a blinded skeptic and explicit evidence verification62I. Random/shuffled-role or placebo deliberation63J. Cost-matched single-agent repeated reasoning and cost-matched ensemble6465Use the same authorized information cutoff and comparable selection opportunity across treatments. Test arithmetic mean, median, trimmed mean, inverse-variance weighting (estimated out of sample), stacking, and robust Bayesian aggregation. No final-test-informed aggregation weights. Explicitly separate improvements from more tokens, more tools, more models, or more data. Limit debate to pre-specified rounds (e.g. 0, 1, 2, 4) and evaluate diminishing returns, convergence, anchoring, and correlated hallucinations.6667## Experimental design and leakage defense68Use a chronological split with train/validation/test and a final untouched holdout; specify dates based on actual coverage. Add spatial holdouts (entire municipalities or regions), rolling-origin evaluation, and distribution-shift stress tests. Comparable retrieval must be strictly as-of-date; no same-property future transfers, post-sale listings, or near-duplicate records leaking across partitions. Group by property identity and assess neighborhood dependence. Build a leakage-audit suite and adversarial tests. If available, retain a separate prospective evaluation set gathered after model/prompt freeze.6970Stratify results by Montreal/Quebec City/Outaouais/other regions as data permit, urban vs rural, condominium vs detached vs multiplex, price deciles, transaction density, and property age. Avoid presenting unsupported granular estimates. Compute paired confidence intervals via clustered/block bootstrap (property, municipality, time as justified), Diebold-Mariano-style comparisons only where assumptions hold, and multiple-testing adjustments. Report effect sizes, statistical uncertainty, and practical significance. No p-hacking or test-set prompt tuning.7172## Human expert comparison73Where feasible, recruit licensed appraisal professionals and/or trained human appraisers under an approved protocol; do not fabricate a human benchmark. Give identical timestamped information packets, time budgets, and clear instructions. Randomize case order, blind sale prices, log confidence intervals, measure inter-rater reliability, and evaluate human-only, AI-only, and human+AI. Distinguish human appraiser judgement from retrospective transaction price. If human recruitment is unavailable, mark this arm as pending and do not claim it was performed.7475## Explainability and calibration76Assess whether explanations cite genuine, timestamp-valid evidence and whether stated adjustments are numerically consistent with the predicted value. Evaluate factuality, provenance precision/recall, counterfactual stability, sensitivity to spurious variables, and human-rated usefulness using blinded rubrics. Do not equate plausible prose with faithful reasoning. Quantify interval coverage at 50%, 80%, 90%, and 95%, conditional coverage by subgroup, sharpness, conformal prediction where appropriate, and calibration under drift. Report severe overvaluation/undervaluation rates relevant to collateral risk.7778## Fundamental-value identification extensions79Because realized price is not fundamental value, add triangulation: repeat transactions and subsequent resale (carefully accounting for intervening market movements), rental yields and discounted cash-flow where reliable rents exist, independent professional valuations if legally accessible, and price-to-rent/user-cost diagnostics. Explain selection bias and limits of each proxy. A model can forecast transaction prices well while failing to identify economic fundamentals; keep these conclusions separate.8081## Economic welfare and market design82Construct a stylized buyer-seller-lender model in which valuation accuracy and uncertainty affect search, bargaining, credit approval, collateral haircuts, and transaction outcomes. Calibrate transparently where evidence permits; otherwise label simulations as illustrative. Study information asymmetry, bargaining surplus, adverse selection, risk of common-model correlated mispricing, and market concentration in AI valuation providers. Do not imply causal welfare gains from predictive performance alone.8384## Software deliverables85Create a reproducible repository:86- `README.md`, `CLAUDE.md`, `pyproject.toml`, `.env.example`, `LICENSE` (only where rights permit)87- `configs/` for data splits, model IDs, treatments, budgets, and seeds88- `src/data/` ingestion, schema validation, joins, as-of joins, leakage checks89- `src/features/` spatial/temporal features, comparable retrieval90- `src/baselines/` hedonic, gradient boosting, AVM, uncertainty91- `src/agents/` role prompts, evidence packets, provider adapters, JSON contracts92- `src/debate/` protocols, critique, aggregation, stopping rules93- `src/evaluation/` metrics, calibration, stratification, clustered inference94- `src/experiments/` reproducible runners, cost tracking, audit trails95- `tests/` unit/integration/leakage/mock-provider tests96- `notebooks/` exploratory analysis (not authoritative pipelines)97- `paper/` complete LaTeX manuscript, BibTeX, figures, tables, appendices98- `reports/` experiment cards, failure analyses, model cards, limitations99100Implement mock LLM adapters and a clearly labeled synthetic dataset so the entire pipeline runs without keys or proprietary data. Include CLI commands for ingest, validate, train, run agents, evaluate, generate tables, and build PDF. Pin dependencies, set seeds, capture versions and hardware, and make outputs reproducible. Do not claim deterministic reproducibility for hosted LLMs; store response artifacts securely and measure run-to-run variation.101102## Manuscript requirements103Write in polished academic English with a serious, restrained style. Target Real Estate Economics, Journal of Real Estate Finance and Economics, or an appropriate finance/AI journal depending on demonstrated contribution. Include abstract, introduction, literature with verified citations/DOIs, theory and propositions, Quebec institutional setting, data, identification, architecture, pre-registered experiments, main results, ablations, calibration, human comparison (if executed), economic implications, limitations, conclusion, references, and detailed reproducibility appendices. Never fabricate empirical tables: use placeholders clearly marked `NOT YET ESTIMATED` until generated by scripts. All figures/tables must come from versioned outputs. Produce `main.tex`, bibliography, compilation script, and publication-ready PDF when toolchain is available.104105## Execution phases and acceptance gates106Phase 0: inventory actual files, access rights, API documentation, computing environment, and research constraints; produce an honest gap analysis.107Phase 1: literature review and novelty map; identify close prior multi-agent real-estate/AVM papers and avoid unsupported priority claims.108Phase 2: preregistration, formal estimands, theory and proof attempts, data dictionary, data-governance plan.109Phase 3: build clean as-of-date data pipeline, leakage tests, and strong tuned non-LLM baselines.110Phase 4: implement 5-agent minimal prototype, then 12-agent default and optional 20-agent extension; run synthetic smoke tests.111Phase 5: run provider-balanced, information-matched, compute-matched randomized ablations on validation; freeze protocol.112Phase 6: evaluate final temporal/spatial holdouts once, with clustered uncertainty and cost accounting.113Phase 7: human benchmark if authorized, welfare model, robustness, interpretability audits.114Phase 8: produce manuscript, supplementary appendix, reproducibility bundle, and limitations register.115116After each phase, produce a concise `reports/phase_XX.md` with completed artifacts, failed checks, decisions, outstanding assumptions, and exact commands. Stop and ask targeted questions only for indispensable access or decisions; otherwise proceed with explicitly documented defaults. Never fabricate completion.117118## Immediate first actions1191. Inspect the repository and report what exists vs what is missing.1202. Draft `research_plan.md`, `data_access_checklist.md`, `preregistration.md`, and `architecture.md`.1213. Search and verify the relevant academic literature if browsing is available; otherwise flag bibliography for verification.1224. Create runnable synthetic-data and mock-provider baselines before making paid API calls.1235. Present an API-cost budget with small pilot, medium validation, and final experiment tiers, without inventing vendor prices.1246. Ask for Vrai-Prix / Immo-Ka schemas or authorized credentials only when the integration stage is reached.1257. Start implementation, tests, and LaTeX scaffolding; prioritize scientific validity over theatrical agent dialogue.126127## Final guiding principle128The central result must isolate whether **communication among heterogeneous autonomous valuation agents adds measurable information**, rather than merely adding compute, correlated opinions, or persuasive narratives. Report failure as rigorously as success.129130---131132## Repository conventions (added by the implementation, 2026-10-27)133- UQO Working Paper No. 26, folder `Recherche-UQO/immobilier/agentic-valuation-quebec`, git remote `gitsrv:srv/git/wp26_uqo.git`.134- Python package: `src/agentic_valuation/` (installed editable: `pip install -e .`). CLI: `av <command>` (see README).135- Secrets only in `.env` (gitignored). Snapshot provenance in `data/raw/README.md`. Every result file is produced by a numbered script in `scripts/`.136