README.md

---
license: other
language:
- en
tags:
- urban-planning
- text-to-urban-plan
- masterplanning
- feasibility
- civic-ai
pipeline_tag: text-to-3d
library_name: transformers
gated: true
extra_gated_heading: "Request access to MAJLIS 1.0 Beta"
extra_gated_description: "Access is reviewed by UNLOCKLAND. Approval is required before using MAJLIS model artifacts, adapters, schemas, or protected implementation files."
extra_gated_button_content: "Request access"
extra_gated_prompt: "By requesting access, you agree not to redistribute MAJLIS files, adapters, schemas, model outputs, or protected artifacts without written permission from UNLOCKLAND."
extra_gated_fields:
  Company: text
  Role: text
  Country: country
  Intended use:
    type: select
    options:
    - Internal evaluation
    - Academic research
    - Commercial pilot
    - Government or public-sector planning
    - Other
  Project description: text
  I confirm I will not redistribute MAJLIS artifacts without written permission: checkbox
model-index:
- name: MAJLIS 1.0 Beta
  results: []
---

# MAJLIS 1.0 Beta

MAJLIS is a text-and-GIS-to-urban-plan reasoning model for feasibility-stage
masterplanning. It turns site, culture, policy, evidence, and developer intent
into a planner-reviewable spatial decision package.

This repository documents the model interface, output schema, reasoning
cadence, evaluation rubric, and reference implementation. Production MAJLIS
deployments use private domain adapters, proprietary planning corpora, and
customer-specific policy layers that are not distributed with this repository.

Access to protected artifacts is gated and manually reviewed by UNLOCKLAND. See
`ACCESS_POLICY.md` and `LICENSE.md`.

MAJLIS does not replace the planner and does not autonomously sign off a
masterplan. It generates, calculates, compares, cites, and structures the
decision space: scenario graph, GIS design layers, road network, blocks,
parcels, building typology assignments, frontage/massing rules, quantitative
schedules, evidence traceability, and unresolved decision prompts.

The planner judges, shapes, interrupts, defers, and signs off.

## Positioning

MAJLIS is:

- an intake copilot, not an autonomous masterplan generator;
- a decision-support engine, not standalone design software;
- a domain planning model, not a general-purpose chatbot.

## Commercialization Path

```text
Open-weight foundation model
↓
Private domain fine-tuning on planning workflows
↓
MAJLIS 1.0 Beta
↓
Hosted as SaaS, API, MCP server, or private deployment
↓
Customer-specific adapters and datasets remain private
```

The intended production path is domain adaptation rather than training from
scratch. A commercially permissive open-weight instruction model can be adapted
with supervised fine-tuning or LoRA adapters over urban planning workflows, then
served privately through a SaaS product, API, MCP server, or customer-specific
deployment.

## Deployment Surfaces

MAJLIS can be exposed through several approved surfaces:

- SaaS: planner-facing web workflow for dialogue, evidence, scenario review, and
  handoff.
- API: structured request/response interface for enterprise integrations.
- MCP server: tool interface for AI agents and planning copilots that need to
  query MAJLIS reasoning, GIS layers, metrics, and evidence packages.
- Private deployment: customer-specific environment with private adapters,
  policy layers, and data residency controls.

## Reasoning Modes

MAJLIS is structured around an adaptive set of planning reasoning modes:

- Constraint Reasoning: extracts site limits, policy constraints, risks, and
  missing evidence.
- Scenario Reasoning: generates, branches, merges, and refines planning
  alternatives across a dialogue. The scenario set grows from the project
  context rather than from a preset template.
- Tradeoff Reasoning: compares density, mobility, public realm, infrastructure,
  phasing, climate comfort, and delivery viability.
- Spatial Reasoning: converts parcel geometry, constraints, evidence points,
  and infrastructure assumptions into map-renderable layout layers: road
  network, blocks, parcels, building footprints, building typologies, massing,
  land use, open space, utilities, and phasing.

## Operating Rules

MAJLIS follows three operating rules:

- Surface, do not decide: the model brings evidence, options, conflicts, and
  confidence into view; planner confirmation is the decision.
- Cite, do not claim: every planning claim should carry source provenance,
  evidence level, and confidence.
- Ask, do not assume: when context is missing or confidence is low, MAJLIS asks
  a better question instead of silently filling the gap.

## Corpus Depth

The current research corpus includes:

- 56 livable-city case references across the Middle East, Asia, Europe, and the
  Americas;
- structured planning data across 8 jurisdictions, organized into land,
  building, and infrastructure categories;
- 200+ park and landmark precedent cases for spatial identity decisions;
- planner-designed inquiry domains covering core, specialist, and edge-case
  planning situations.

The corpus is used to surface comparables and decision prompts, not to replace
local professional judgment.

Production deployments also support live retrieval for local regulations,
national policy updates, and customer-approved regulatory repositories. Live
sources carry freshness metadata, jurisdiction filters, provenance, evidence
level, confidence, and conflict checks before a claim is shown to a planner.

See `docs/corpus_architecture.md`.

## Local Product Intelligence

This repository is aligned with the local MAJLIS planning engine. The system
uses a context-adaptive inquiry graph, a five-step reasoning cadence, phase-end
compliance gates, evidence-level claims, source provenance classes,
accountability tiers, and a human-centered scorecard. Questions are generated
from national direction, city strategy, policy constraints, developer goals,
market assumptions, site GIS, and the evolving planner dialogue.

See:

- `docs/MAJLIS_REASONING_SYSTEM.md`
- `docs/context_inquiry_examples.json`
- `docs/decision_rubric.json`
- `docs/building_typologies.json`
- `docs/WHY_MAJLIS.md`
- `docs/interoperability.md`
- `docs/corpus_architecture.md`
- `case_studies/dammam_815ha.md`
- `model/model_manifest.json`
- `artifacts/protected_artifacts.json`

## Intended Use

Input:

```json
{
  "site_brief": "Plan a walkable residential district near a future metro station.",
  "gis": {
    "coordinate_reference_system": "EPSG:4326",
    "centroid": [26.3671, 50.1666],
    "site_boundary": "GeoJSON FeatureCollection",
    "constraint_layers": [
      "wadi buffer",
      "legacy use due-diligence zone",
      "flood footprint",
      "sabkha pockets"
    ],
    "infrastructure_layers": [
      "future metro catchment",
      "district cooling reservation",
      "utility capacity nodes"
    ]
  },
  "priorities": ["family housing", "shaded public realm", "district cooling"]
}
```

Output:

```text
MAJLIS 1.0 Beta

Structured planning rationale
1. The future metro catchment supports the highest density and strongest mixed
   use activity near the station.
2. Family housing requires a finer-grain network of schools, parks, local
   retail, and shaded daily walking routes.
3. District cooling, utilities, and mobility corridors should be reserved before
   parcel subdivision.

Seed scenario: Transit-Oriented Compact Core
- Planning thesis: concentrate density and mixed use around the metro station.
- Best fit: strongest for transit ridership, retail viability, and early civic
  identity.
- Risk: depends on metro timing and high-quality pedestrian comfort.

Seed scenario: Family Neighborhood Network
- Planning thesis: distribute schools, parks, and neighborhood centers across
  walkable residential clusters.
- Best fit: strongest for family housing, phasing flexibility, and social
  infrastructure.
- Risk: may dilute the station-area center if retail frontage is fragmented.

Seed scenario: Climate-Resilient Green Spine
- Planning thesis: organize development around a continuous shaded landscape and
  blue-green infrastructure corridor.
- Best fit: strongest for heat mitigation, public realm identity, and long-term
  climate comfort.
- Risk: requires disciplined infrastructure reservation and maintenance funding.

Recommendation
Advance the compact-core and green-spine seeds as a merged preferred direction,
then keep the family-neighborhood seed as the phasing and housing fallback. The
planner can branch, merge, reject, or refine scenarios in later turns.

Design and GIS outputs
- Baseline: site boundary, evidence points, hydrology constraints,
  infrastructure assumptions.
- Layout: concept blocks, parcelization, land-use polygons, centers, edges, and
  reserved corridors.
- Buildings: footprints, typologies, height bands, massing assumptions, frontage
  rules, privacy/entry logic, majlis variants, civic anchors, and landmark
  candidates.
- Road network: street hierarchy, centerlines, intersections, access loops,
  pedestrian/cycle spines, and service routes.
- Public realm: parks, plazas, shaded streets, blue-green corridors, school
  walksheds, and civic anchors.
- Utilities and phasing: district cooling reservations, utility corridors,
  phase boundaries, and delivery sequence geographies.
```

## Reference API

The included `inference.py` file exposes a deterministic reference
implementation for local interface testing:

```bash
python inference.py "Plan a compact waterfront district with mixed-use streets"
```

It returns structured rationale, a dynamic scenario set, a tradeoff matrix,
scenario lineage, GIS layers, and recommended next actions.

## Model Details

- Name: MAJLIS 1.0 Beta
- Task type: text to urban plan / urban planning reasoning
- Status: private production adaptation path with public interface contract
- Inputs: site descriptions, development priorities, constraints, policy goals,
  parcel geometry, GIS layers, infrastructure assumptions, evidence points
- Outputs: structured planning rationale, a dynamic scenario graph, tradeoff
  matrix, risks, handoff actions, and map-renderable design/GIS feature
  collections
- Base model path: open-weight instruction model
- Adaptation path: supervised fine-tuning or LoRA on planning workflows
- Access model: public model card with gated artifact access and manual approval

## Training Approach

Target production training uses a private domain corpus assembled from planning
briefs, site constraints, feasibility memos, design review comments, mobility
strategies, public realm guidance, infrastructure assumptions, phasing plans,
and handoff documents.

The model is optimized for structured outputs rather than free-form prose:

- planning rationale
- constraint extraction
- scenario generation
- scenario branching, merging, and refinement
- GIS layer generation
- road network and layout generation
- building footprint, typology, frontage, and massing generation
- tradeoff comparison
- evidence requests
- risk register
- planner handoff brief

See `training/qlora_config.yaml` for the public training recipe skeleton.
Production adapters and datasets are private.

Additional public artifact descriptors:

- `model/model_manifest.json`
- `model/generation_config.json`
- `training/dataset_manifest.json`
- `training/training_run_2026_05.md`

## API Shape

```json
{
  "model": "UNLOCKLAND/MAJLIS",
  "mode": "scenario_graph",
  "scenario_controls": {
    "seed_count": "adaptive",
    "allow_branching": true,
    "allow_merging": true,
    "max_scenarios": null
  },
  "input": {
    "site_brief": "Plan a 120 hectare residential district near a future metro station.",
    "gis": {
      "coordinate_reference_system": "EPSG:4326",
      "site_boundary": "GeoJSON FeatureCollection",
      "constraint_layers": [],
      "infrastructure_layers": []
    }
  },
  "outputs": {
    "rationale": [],
    "scenario_graph": {},
    "scenarios": [],
    "gis_layers": {
      "baseline": {},
      "scenario_layers": []
    },
    "tradeoff_matrix": [],
    "recommendation": ""
  }
}
```

See `schemas/urban_plan_reasoner.schema.json` and the `examples/` folder for a
more explicit API contract.

Planning metrics are defined in `schemas/planning_metrics.schema.json`, with an
example response in `examples/planning_metrics_response.json`.

## Evaluation

The public `evals/` folder contains sample prompts and planner review rubrics
for scenario diversity, GIS validity, urban design quality, building typology
fit, metrics quality, evidence traceability, and handoff quality. Production
benchmark scores are not published because the private adapter and private
evaluation set are not distributed.

## Limitations

This package should not be used for statutory planning decisions, engineering
design, legal review, investment approval, or public consultation without
qualified professional review. GIS outputs are concept-level planning layers,
not survey-grade geometry, engineering design, traffic modeling, infrastructure
sizing, environmental assessment, or statutory code compliance.

## Suggested Citation

```bibtex
@misc{majlis_1_0_beta,
  title = {MAJLIS 1.0 Beta},
  year = {2026},
  note = {Text-to-urban-plan reasoning interface for private domain adaptation}
}
```