> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abacuslabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# The policy

> What the account should look like and what a change may cost: every field, its units and its default.

A policy is the person's rules in one object. `POST /v1/proposals` takes a `goal` in plain English, a `policy`, or both. Abacus Labs reads the goal into a policy, lays the fields you send over it, solves it, and echoes the result in `understood.policy`.

**Order (later wins):** the saved account's policy, then what Abacus Labs read from `goal`, then the `policy` you send.

To change one thing, edit that field in `understood.policy` and send it back. The same policy on the same account gives the same answer.

Every field is optional. Weights are fractions of the account (`0.10` = 10%). Money is in dollars.

```json theme={null}
{ "goal": "harvest_losses",
  "benchmark": "current",
  "tracking_error": 0.01,
  "max_volatility": 0.15,
  "tax": { "mode": "harvest", "max_tax": 2000, "rates": { "short_term": 0.37, "long_term": 0.20, "state": 0.05 } },
  "cash": { "min": 20000, "max": 30000, "invest": true },
  "keep": ["NVDA"], "exclude": ["MO"], "exclude_themes": ["tobacco", "fossil fuels"], "buy_only": [],
  "positions": { "NVDA": { "max": 0.15 } },
  "sectors": { "Information Technology": { "max": 0.30 } },
  "max_names": 100,
  "trading": { "whole_shares": true, "min_trade": 500, "max_trades": 40, "max_turnover": 0.10, "no_sells": false },
  "monitor": { "webhook": "https://...", "secret": "...", "harvest": true, "drift": 0.03, "rule_break": true } }
```

## Fields

| Field | Type | Default | Meaning |
| - | - | - | - |
| `goal` | string | read from the text | What to do. See [Goals](#goals). |
| `benchmark` | string or object | see below | What the solver tracks. See [Benchmark](#benchmark). |
| `tracking_error` | fraction, or `tight`, `moderate`, `loose` | none | Most tracking error against the benchmark. `tight` = 1%, `moderate` = 2%, `loose` = 4%. |
| `max_volatility` | fraction | none | Most total volatility of the account, annual. |
| `tax.mode` | `harvest`, `minimize`, `neutral`, `ignore` | from the goal | `harvest`: realize losses. `minimize`: weigh tax against the goal. `neutral`: realize no net gain. `ignore`: tax plays no part. |
| `tax.max_tax` | dollars | none | Most estimated tax this change may cost, at `tax.rates` ("keep the tax under \$2,000"). |
| `tax.max_gain` | dollars | none | Most net capital gain this change may realize ("no more than \$5,000 of gains"). Short- and long-term gains and losses net against each other. For no net gain at all, use `tax.mode: neutral`. |
| `tax.rates` | `{short_term, long_term, state?, niit?}` | top federal rates | All-in marginal rates as fractions. They set `estimated_tax` on every option and commit. Without them Abacus Labs uses 40.8% short term and 23.8% long term, and says so in `warnings`. |
| `cash.min` | dollars | none | Cash to hold after the trades, at least. "I need \$20k" = `20000`. |
| `cash.max` | dollars | none | Cash to hold after the trades, at most. |
| `cash.invest` | boolean | none | Put the cash to work. Abacus Labs keeps about 1% as a buffer unless `cash.max` says otherwise. |
| `keep` | tickers | `[]` | Never sell these. |
| `exclude` | tickers | `[]` | Never buy these. |
| `exclude_themes` | theme words | `[]` | Never buy names in these industries. See [Themes](#themes). |
| `buy_only` | tickers | `[]` | Buy only from this list (names the account does not hold yet are fine). Without it, see "Where the buys come from" in [Proposals](https://docs.abacuslabs.ai/concepts/proposals.md). |
| `positions` | `{TICKER: {min?, max?}}` | `{}` | Per-holding weight limits. |
| `sectors` | `{GICS sector: {min?, max?}}` | `{}` | Per-sector weight limits. Names: Information Technology, Health Care, Financials, Consumer Discretionary, Communication Services, Industrials, Consumer Staples, Energy, Utilities, Real Estate, Materials. |
| `max_names` | integer | none | Most holdings after the trades. |
| `max_position` | fraction | none | No holding above this weight after the trades. A holding already above it may not grow. |
| `trading.whole_shares` | boolean | the account's rule, else `true` | Trade whole shares only. |
| `trading.min_trade` | dollars | none | Smallest trade. A full sale may be smaller. |
| `trading.max_trades` | integer | none | Most trades. |
| `trading.max_turnover` | fraction | none | (bought + sold) / 2 / account value. |
| `trading.no_sells` | boolean | `false` | Buy only, sell nothing. |
| `trading.sell_lots` | `any`, `short_term_only`, `long_term_only` | `any` | Which lots may be sold. `short_term_only`: "don't sell anything I've held over a year" (long-term lots stay). `long_term_only`: "no short-term sales". Checked by trade checks too. |
| `theme` | string | none | `tilt_theme` only: the theme to add (`ai`, `dividends`, ...). |
| `trades` | list | none | `check_trades` only: drafted trades. Prefer [`POST /v1/trades/check`](https://docs.abacuslabs.ai/concepts/trade-checks). |
| `monitor` | object | none | Saved accounts only. See [Monitoring](https://docs.abacuslabs.ai/concepts/saved-accounts.md#monitoring). |

Unknown fields are refused with `422 invalid_policy`; `param` names the field.

## Goals

| `goal` | What Abacus Labs does | Engine |
| - | - | - |
| `harvest_losses` | Sell loss lots, buy replacements that keep the account close, block wash sales. | layered |
| `invest_cash` | Put cash to work toward the benchmark. | layered |
| `raise_cash` | Sell to reach `cash.min`. Tax counts as `tax.mode` says. | layered |
| `reduce_concentration` | Cut a position named in `positions`. | layered |
| `reduce_sector` | Cut a sector named in `sectors`. | layered |
| `lower_risk` | Lower volatility (to `max_volatility` if set). | layered |
| `track_benchmark` | Move the account toward the benchmark. | layered |
| `rebalance` | Back to a stated target mix. | layered |
| `tilt_theme` | Add a theme. | templates |
| `check_trades` | Check drafted trades. | rule checker |

The layered solver gives exact rules and a proven bound. Templates are rule-based. `provenance.engine` says which ran, and `warnings` says why when the layered solver was not used.

## Benchmark

| Form | Example | Resolves to |
| - | - | - |
| `current` | `"current"` | The account as it is now: stay close to it. |
| Ticker or index | `"SPY"`, `"QQQ"`, `"S&P 500"` | The fund's holdings from its latest SEC N-PORT report, rolled forward with prices. An index resolves through the ETF that tracks it. |
| Plain English | `"half S&P 500, half ARKK"` | Abacus Labs reads it into a definition. |
| Blend | `{"mix": [{"benchmark": "SPY", "weight": 0.5}, {"benchmark": "ARKK", "weight": 0.5}]}` | The weighted sum of its parts. Weights are scaled to add to 1. |
| 13F manager | `{"manager": "Pershing Square"}` | The manager's newest public 13F book: long US-listed stocks at quarter end. It trails the real portfolio by up to about four and a half months. |
| Custom weights | `{"weights": {"AAPL": 0.3, "MSFT": 0.3, "NVDA": 0.4}}` | Your weights. An ETF in the list is replaced by its holdings. |

**Default:** `current` for most goals. For `invest_cash`, `track_benchmark` and `rebalance`, and for an account that is mostly cash, the account's index: SPY unless you set one. `understood.resolved.benchmark` shows what was used.

## Themes

`exclude_themes` accepts: `alcohol`, `banks`, `defense`, `firearms`, `fossil fuels`, `gambling`, `oil and gas`, `pharma`, `reits`, `semiconductors`, `tobacco`. Common words map to them (`coal` and `energy` to `fossil fuels`, `guns` to `firearms`, `casinos` to `gambling`, `chips` to `semiconductors`). Industry themes use the risk model's industry groups; the others use a short ticker list. A theme word Abacus Labs does not know is named in `warnings`.

## What a saved account keeps

With `save: true`, the account keeps the standing parts of the policy: benchmark (unless `current`), tracking error, tax rates, `max_tax` and `max_gain`, keep and exclude lists, position and sector limits (except the one a concentration or sector goal was cutting), trading rules and `monitor`. It drops the one-off parts: `goal`, `trades`, `theme`, `cash` and `tax.mode`.

## Examples

| The person says | Abacus Labs reads |
| - | - |
| "Harvest my losses but keep the portfolio close to what I have now. Whole shares only." | `goal: harvest_losses`, `benchmark: current`, `tax.mode: harvest`, `trading.whole_shares: true` |
| "Get NVDA under 10%, keep taxes low" | `goal: reduce_concentration`, `positions: {NVDA: {max: 0.10}}`, `tax.mode: minimize` |
| "I need $20k by Friday, no more than $1,500 in tax" | `goal: raise_cash`, `cash.min: 20000`, `tax.max_tax: 1500` |
| "Get NVDA below 40% without more than \$5,000 of gains" | `goal: reduce_concentration`, `positions: {NVDA: {max: 0.40}}`, `tax.max_gain: 5000` |
| "Invest my cash to track the S\&P 500 closely, no tobacco, at most 50 stocks" | `goal: invest_cash`, `benchmark: "S&P 500"`, `tracking_error: tight`, `exclude_themes: [tobacco]`, `max_names: 50` |
| "Tech below 30%, don't sell AAPL" | `goal: reduce_sector`, `sectors: {Information Technology: {max: 0.30}}`, `keep: [AAPL]` |

`understood.read_from_text` lists the fields Abacus Labs took from the goal, and `understood.confidence` how sure it was. Below the threshold, `outcome` is `clarify` and `understood.question` says what to ask the person.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.