# appraisal-forge-sdk

Python SDK + CLI for interacting with the Appraisal Forge API.

## Install

```bash
pip install appraisal-forge-sdk
```

## Environment

```bash
export APPRAISAL_FORGE_URL=https://your-instance.com
export APPRAISAL_FORGE_TOKEN=your-api-token
```

## CLI

Create appraisal:

```bash
appraisal-forge create --name "123 Main" --subject-address "123 Main St, Raleigh, NC 27601"
```

Read fields:

```bash
appraisal-forge fields-read --appraisal-id 123 --prefix 0100
```

Write fields from JSON file:

```bash
appraisal-forge fields-write --appraisal-id 123 --json fields.json
```

Validate:

```bash
appraisal-forge validate --appraisal-id 123
```

Status summary:

```bash
appraisal-forge status --appraisal-id 123
```

Upload photo:

```bash
appraisal-forge upload-photo --appraisal-id 123 --field-id 2100.0087 --image-path ./front.jpg --label Front
```

Token and connectivity helpers:

```bash
appraisal-forge tokens
appraisal-forge create-token --label "Claude Desktop" --scope full
appraisal-forge revoke-token --token-id 12
appraisal-forge verify-token
appraisal-forge connection-info
appraisal-forge login --api-url http://localhost:8090
appraisal-forge relay-status
appraisal-forge relay-start --agent-cmd "codex exec '{message}'"
appraisal-forge relay-resume
appraisal-forge relay-watch
appraisal-forge relay-stop
```

Notes:

- `create-token` defaults to a `sdk`-scoped token; use `--scope full` only for CLI/SDK token-management or connection bootstrap tasks.
- `connection-info` returns MCP and field-api endpoints, including a ready-to-copy `claude_cli_config` stanza.
- `verify-token` validates the current bearer token and returns a normalized payload with `valid`, `error`, and token metadata.
- `login` runs browser-based device auth and saves token/api-url to `~/.appraisal-forge/config.json` (or `APPRAISAL_FORGE_CONFIG_DIR`).
- `relay-start` and `relay-resume` default to local-worker mode (runs on the user's machine, not the server container).
- Use `--mode server` only for diagnostics.
- `relay-resume` is the restart command for users after closing/reopening CLI; it reuses the last saved relay command and appraisal id.
- `relay-watch` keeps the local worker alive and auto-restarts it if it exits.

Config-driven fill:

```bash
appraisal-forge fill --config ./fill-config.json
```

Resume existing appraisal:

```bash
appraisal-forge fill --config ./fill-config.json --appraisal-id 123
```

Dry run:

```bash
appraisal-forge fill --config ./fill-config.json --dry-run
```

Example `fill-config.json`:

```json
{
  "report_name": "123 Main",
  "subject_address": "123 Main St, Raleigh, NC 27601",
  "property_config": "ADDRESS: 123 Main St, Raleigh, NC 27601",
  "uad_fields": {
    "0100.0009": "Raleigh",
    "0100.0011": "NC",
    "0100.0012": "27601"
  },
  "validate_after": true
}
```

## Python SDK

```python
from appraisal_forge_sdk import AppraisalForgeClient

client = AppraisalForgeClient(
    api_url="https://your-instance.com",
    token="your-api-token",
)

created = client.create_appraisal("123 Main", "123 Main St, Raleigh, NC 27601")
appraisal_id = created["id"]

client.write_fields(appraisal_id, {
    "0100.0009": "Raleigh",
    "0100.0011": "NC",
})

validation = client.validate(appraisal_id)
print(validation)
```

## Auth model

v0.1 uses existing Bearer token auth from the Appraisal Forge API.

## Runtime requirements

- Python 3.10+
- Reachable Appraisal Forge API URL
- Valid API token
