Metadata-Version: 2.4
Name: noori
Version: 0.1.1
Summary: Agent-friendly real estate scenario analysis CLI and API.
License: MIT License
        
        Copyright (c) 2026 Ramy Shoker
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/CoastalBoltman/re_agent
Project-URL: Repository, https://github.com/CoastalBoltman/re_agent
Project-URL: Issues, https://github.com/CoastalBoltman/re_agent/issues
Keywords: real-estate,mortgage,rent,cli,financial-modeling
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic<3,>=2
Provides-Extra: api
Requires-Dist: fastapi<1,>=0.115; extra == "api"
Requires-Dist: uvicorn<1,>=0.32; extra == "api"
Requires-Dist: httpx<1,>=0.28; extra == "api"
Dynamic: license-file

# Noori

Noori is an agent-friendly real estate analysis toolkit for comparing big housing decisions with plain JSON inputs and transparent calculation outputs.

It is built for people and AI agents who need a consistent way to ask questions like:

- Is it financially better to buy a home or keep renting?
- If I move, should I sell my current home or keep it as a rental?
- How do mortgage costs, rent growth, appreciation, closing costs, and investment returns change the answer?

Noori currently ships as a Python CLI, a reusable calculation library, and a small FastAPI wrapper. It is an educational decision-support tool, not legal, tax, investment, or financial advice.

## What Noori Can Analyze

- **Buy vs Rent**: compare buying a target home against continuing to rent and investing available cash.
- **Keep and Rent**: compare keeping a current home as a rental while buying another home.
- **Sell and Buy**: project selling a current home and redeploying equity into a new purchase.

Each scenario returns structured results and the assumptions used, so humans can inspect the math and agents can reliably consume the output.

## Quick Start

Install the CLI in an isolated environment with `pipx`:

```bash
pipx install noori
```

List supported scenario types:

```bash
noori scenarios
```

Create a starter scenario file:

```bash
noori example buy-vs-rent --output scenario.json
```

Validate the scenario:

```bash
noori validate scenario.json
```

Run the calculation:

```bash
noori calculate scenario.json --output result.json
```

Inspect default assumptions:

```bash
noori assumptions buy-vs-rent
```

## Example Workflow

```bash
noori example keep-and-rent --output move_scenario.json
noori validate move_scenario.json
noori calculate move_scenario.json --output move_result.json
```

The generated JSON is meant to be edited. Change the home price, loan balance, rent, holding period, expected appreciation, or other assumptions, then run the calculation again.

## Financial Planning App Integration

Noori can be embedded in financial planning products as the housing-decision engine behind a broader planning experience.

Common integration patterns include:

- **Planning dashboards**: run Noori scenarios alongside household cash flow, retirement projections, debt payoff plans, and portfolio allocation models.
- **Advisor and client portals**: let users compare buy, rent, sell, and keep-as-rental choices from the same assumptions used in the rest of their plan.
- **AI planning agents**: generate or update scenario JSON from a conversation, call the CLI or API, then explain the results with the returned assumptions and recommendation.
- **What-if analysis**: rerun scenarios as interest rates, rent, home prices, down payments, or investment return assumptions change.
- **Audit trails**: store each input JSON and result JSON so users can see which assumptions produced each recommendation.

The interface is intentionally structured around JSON. Applications can create a scenario payload, submit it through the Python dispatcher, CLI, or FastAPI endpoint, and persist the response for charts, reports, or conversational summaries.

## Python And API Usage

This repo includes a website-ready stack for real-estate scenario analysis:

- Backend API in `src/re_agent/api.py` using FastAPI.
- Shared calculation contract in `src/re_agent/schemas.py` and dispatcher in `src/re_agent/dispatcher.py`.
- CLI entry point exposed as `noori`.
- Frontend React wizard app in `frontend/` using Vite.
- API integration tests in `tests/test_api.py`.

The current wizard supports:

- Buy vs Rent
- Keep and Rent Current Home
- Sell Current Home and Buy

### Backend endpoints

- `GET /healthz`
- `POST /api/calculate`

`POST /api/calculate` accepts a `scenario` value and dispatches to the matching engine.

Example backend run command:

```bash
PYTHONPATH=src uvicorn re_agent.api:app --reload
```

Example frontend run command:

```bash
cd frontend
npm install
npm run dev
```

If your backend is not running on `http://localhost:8000`, set `VITE_API_BASE_URL` in the frontend environment before starting Vite.

### Local Development

For local development from this repo, install the package in editable mode:

```bash
pipx install --editable .
```

You can also run the checked-in example directly:

```bash
noori calculate examples/buy_vs_rent.json
```

The CLI uses the same shared schemas and dispatcher as the API, so it is the stable interface for scripts and agent tools.

If you are developing or running the API server locally, install the API extra:

```bash
python -m pip install -e ".[api]"
```

### Publishing

Noori publishes from tagged GitHub releases using PyPI Trusted Publishing.

The PyPI project uses a trusted publisher with:

- Repository: `CoastalBoltman/re_agent`
- Workflow: `.github/workflows/publish.yml`
- Environment: `pypi`

Publish a release by pushing a version tag that matches `pyproject.toml`:

```bash
git tag v0.1.1
git push origin v0.1.1
```

After the workflow completes, users can install the CLI with:

```bash
pipx install noori
```
