90 |
91 |
92 |
93 |
79 |
80 |
87 |
88 |
89 |
94 |
28 |
60 |
61 |
65 |
66 |
112 |
113 |
118 |
121 |
122 |
123 |
124 |
125 |
126 |
127 |
--------------------------------------------------------------------------------
/_build/_static/doctools.js:
--------------------------------------------------------------------------------
1 | /*
2 | * Base JavaScript utilities for all Sphinx HTML documentation.
3 | */
4 | "use strict";
5 |
6 | const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([
7 | "TEXTAREA",
8 | "INPUT",
9 | "SELECT",
10 | "BUTTON",
11 | ]);
12 |
13 | const _ready = (callback) => {
14 | if (document.readyState !== "loading") {
15 | callback();
16 | } else {
17 | document.addEventListener("DOMContentLoaded", callback);
18 | }
19 | };
20 |
21 | /**
22 | * Small JavaScript module for the documentation.
23 | */
24 | const Documentation = {
25 | init: () => {
26 | Documentation.initDomainIndexTable();
27 | Documentation.initOnKeyListeners();
28 | },
29 |
30 | /**
31 | * i18n support
32 | */
33 | TRANSLATIONS: {},
34 | PLURAL_EXPR: (n) => (n === 1 ? 0 : 1),
35 | LOCALE: "unknown",
36 |
37 | // gettext and ngettext don't access this so that the functions
38 | // can safely bound to a different name (_ = Documentation.gettext)
39 | gettext: (string) => {
40 | const translated = Documentation.TRANSLATIONS[string];
41 | switch (typeof translated) {
42 | case "undefined":
43 | return string; // no translation
44 | case "string":
45 | return translated; // translation exists
46 | default:
47 | return translated[0]; // (singular, plural) translation tuple exists
48 | }
49 | },
50 |
51 | ngettext: (singular, plural, n) => {
52 | const translated = Documentation.TRANSLATIONS[singular];
53 | if (typeof translated !== "undefined")
54 | return translated[Documentation.PLURAL_EXPR(n)];
55 | return n === 1 ? singular : plural;
56 | },
57 |
58 | addTranslations: (catalog) => {
59 | Object.assign(Documentation.TRANSLATIONS, catalog.messages);
60 | Documentation.PLURAL_EXPR = new Function(
61 | "n",
62 | `return (${catalog.plural_expr})`
63 | );
64 | Documentation.LOCALE = catalog.locale;
65 | },
66 |
67 | /**
68 | * helper function to focus on search bar
69 | */
70 | focusSearchBar: () => {
71 | document.querySelectorAll("input[name=q]")[0]?.focus();
72 | },
73 |
74 | /**
75 | * Initialise the domain index toggle buttons
76 | */
77 | initDomainIndexTable: () => {
78 | const toggler = (el) => {
79 | const idNumber = el.id.substr(7);
80 | const toggledRows = document.querySelectorAll(`tr.cg-${idNumber}`);
81 | if (el.src.substr(-9) === "minus.png") {
82 | el.src = `${el.src.substr(0, el.src.length - 9)}plus.png`;
83 | toggledRows.forEach((el) => (el.style.display = "none"));
84 | } else {
85 | el.src = `${el.src.substr(0, el.src.length - 8)}minus.png`;
86 | toggledRows.forEach((el) => (el.style.display = ""));
87 | }
88 | };
89 |
90 | const togglerElements = document.querySelectorAll("img.toggler");
91 | togglerElements.forEach((el) =>
92 | el.addEventListener("click", (event) => toggler(event.currentTarget))
93 | );
94 | togglerElements.forEach((el) => (el.style.display = ""));
95 | if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler);
96 | },
97 |
98 | initOnKeyListeners: () => {
99 | // only install a listener if it is really needed
100 | if (
101 | !DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS &&
102 | !DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS
103 | )
104 | return;
105 |
106 | document.addEventListener("keydown", (event) => {
107 | // bail for input elements
108 | if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return;
109 | // bail with special keys
110 | if (event.altKey || event.ctrlKey || event.metaKey) return;
111 |
112 | if (!event.shiftKey) {
113 | switch (event.key) {
114 | case "ArrowLeft":
115 | if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break;
116 |
117 | const prevLink = document.querySelector('link[rel="prev"]');
118 | if (prevLink && prevLink.href) {
119 | window.location.href = prevLink.href;
120 | event.preventDefault();
121 | }
122 | break;
123 | case "ArrowRight":
124 | if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break;
125 |
126 | const nextLink = document.querySelector('link[rel="next"]');
127 | if (nextLink && nextLink.href) {
128 | window.location.href = nextLink.href;
129 | event.preventDefault();
130 | }
131 | break;
132 | }
133 | }
134 |
135 | // some keyboard layouts may need Shift to get /
136 | switch (event.key) {
137 | case "/":
138 | if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break;
139 | Documentation.focusSearchBar();
140 | event.preventDefault();
141 | }
142 | });
143 | },
144 | };
145 |
146 | // quick alias for translations
147 | const _ = Documentation.gettext;
148 |
149 | _ready(Documentation.init);
150 |
--------------------------------------------------------------------------------
/_build/_static/pygments.css:
--------------------------------------------------------------------------------
1 | pre { line-height: 125%; }
2 | td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
3 | span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
4 | td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
5 | span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
6 | .highlight .hll { background-color: #ffffcc }
7 | .highlight { background: #f8f8f8; }
8 | .highlight .c { color: #3D7B7B; font-style: italic } /* Comment */
9 | .highlight .err { border: 1px solid #F00 } /* Error */
10 | .highlight .k { color: #008000; font-weight: bold } /* Keyword */
11 | .highlight .o { color: #666 } /* Operator */
12 | .highlight .ch { color: #3D7B7B; font-style: italic } /* Comment.Hashbang */
13 | .highlight .cm { color: #3D7B7B; font-style: italic } /* Comment.Multiline */
14 | .highlight .cp { color: #9C6500 } /* Comment.Preproc */
15 | .highlight .cpf { color: #3D7B7B; font-style: italic } /* Comment.PreprocFile */
16 | .highlight .c1 { color: #3D7B7B; font-style: italic } /* Comment.Single */
17 | .highlight .cs { color: #3D7B7B; font-style: italic } /* Comment.Special */
18 | .highlight .gd { color: #A00000 } /* Generic.Deleted */
19 | .highlight .ge { font-style: italic } /* Generic.Emph */
20 | .highlight .ges { font-weight: bold; font-style: italic } /* Generic.EmphStrong */
21 | .highlight .gr { color: #E40000 } /* Generic.Error */
22 | .highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */
23 | .highlight .gi { color: #008400 } /* Generic.Inserted */
24 | .highlight .go { color: #717171 } /* Generic.Output */
25 | .highlight .gp { color: #000080; font-weight: bold } /* Generic.Prompt */
26 | .highlight .gs { font-weight: bold } /* Generic.Strong */
27 | .highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
28 | .highlight .gt { color: #04D } /* Generic.Traceback */
29 | .highlight .kc { color: #008000; font-weight: bold } /* Keyword.Constant */
30 | .highlight .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */
31 | .highlight .kn { color: #008000; font-weight: bold } /* Keyword.Namespace */
32 | .highlight .kp { color: #008000 } /* Keyword.Pseudo */
33 | .highlight .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */
34 | .highlight .kt { color: #B00040 } /* Keyword.Type */
35 | .highlight .m { color: #666 } /* Literal.Number */
36 | .highlight .s { color: #BA2121 } /* Literal.String */
37 | .highlight .na { color: #687822 } /* Name.Attribute */
38 | .highlight .nb { color: #008000 } /* Name.Builtin */
39 | .highlight .nc { color: #00F; font-weight: bold } /* Name.Class */
40 | .highlight .no { color: #800 } /* Name.Constant */
41 | .highlight .nd { color: #A2F } /* Name.Decorator */
42 | .highlight .ni { color: #717171; font-weight: bold } /* Name.Entity */
43 | .highlight .ne { color: #CB3F38; font-weight: bold } /* Name.Exception */
44 | .highlight .nf { color: #00F } /* Name.Function */
45 | .highlight .nl { color: #767600 } /* Name.Label */
46 | .highlight .nn { color: #00F; font-weight: bold } /* Name.Namespace */
47 | .highlight .nt { color: #008000; font-weight: bold } /* Name.Tag */
48 | .highlight .nv { color: #19177C } /* Name.Variable */
49 | .highlight .ow { color: #A2F; font-weight: bold } /* Operator.Word */
50 | .highlight .w { color: #BBB } /* Text.Whitespace */
51 | .highlight .mb { color: #666 } /* Literal.Number.Bin */
52 | .highlight .mf { color: #666 } /* Literal.Number.Float */
53 | .highlight .mh { color: #666 } /* Literal.Number.Hex */
54 | .highlight .mi { color: #666 } /* Literal.Number.Integer */
55 | .highlight .mo { color: #666 } /* Literal.Number.Oct */
56 | .highlight .sa { color: #BA2121 } /* Literal.String.Affix */
57 | .highlight .sb { color: #BA2121 } /* Literal.String.Backtick */
58 | .highlight .sc { color: #BA2121 } /* Literal.String.Char */
59 | .highlight .dl { color: #BA2121 } /* Literal.String.Delimiter */
60 | .highlight .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */
61 | .highlight .s2 { color: #BA2121 } /* Literal.String.Double */
62 | .highlight .se { color: #AA5D1F; font-weight: bold } /* Literal.String.Escape */
63 | .highlight .sh { color: #BA2121 } /* Literal.String.Heredoc */
64 | .highlight .si { color: #A45A77; font-weight: bold } /* Literal.String.Interpol */
65 | .highlight .sx { color: #008000 } /* Literal.String.Other */
66 | .highlight .sr { color: #A45A77 } /* Literal.String.Regex */
67 | .highlight .s1 { color: #BA2121 } /* Literal.String.Single */
68 | .highlight .ss { color: #19177C } /* Literal.String.Symbol */
69 | .highlight .bp { color: #008000 } /* Name.Builtin.Pseudo */
70 | .highlight .fm { color: #00F } /* Name.Function.Magic */
71 | .highlight .vc { color: #19177C } /* Name.Variable.Class */
72 | .highlight .vg { color: #19177C } /* Name.Variable.Global */
73 | .highlight .vi { color: #19177C } /* Name.Variable.Instance */
74 | .highlight .vm { color: #19177C } /* Name.Variable.Magic */
75 | .highlight .il { color: #666 } /* Literal.Number.Integer.Long */
--------------------------------------------------------------------------------
/src/service/objectives/cash_deployment/cash_deployment.py:
--------------------------------------------------------------------------------
1 | import pulp
2 | import pandas as pd
3 | from typing import Dict
4 | from src.service.helpers.constants import CASH_CUSIP_ID
5 | from src.service.helpers.constants import logger
6 |
7 | def calculate_cash_deployment_objective(
8 | prob: pulp.LpProblem,
9 | buys: Dict[str, pulp.LpVariable],
10 | sells: Dict[str, pulp.LpVariable],
11 | drift: pd.DataFrame,
12 | gain_loss: pd.DataFrame,
13 | total_value: float,
14 | prices: pd.DataFrame,
15 | cash_normalization: float,
16 | debug: bool = True,
17 | ) -> pulp.LpAffineExpression:
18 | """
19 | Calculate a penalty for holding excess cash above target.
20 | Only penalizes cash when it's above target, not when below.
21 |
22 | Args:
23 | prob: The optimization problem to add constraints to
24 | buys: Dictionary of buy variables
25 | sells: Dictionary of sell variables
26 | drift: DataFrame with drift report
27 | gain_loss: DataFrame with gain/loss report
28 | total_value: Total portfolio value
29 | prices: DataFrame with current prices
30 | debug: Enable debug logging
31 | cash_normalization: Normalization factor for cash penalty
32 |
33 | Returns:
34 | The cash penalty expression
35 | """
36 | # Get cash information from drift report
37 | cash_row = drift[drift['asset_class'] == CASH_CUSIP_ID]
38 | if cash_row.empty:
39 | if debug:
40 | logger.warning("CASH_CUSIP_ID not found in drift report for cash penalty calculation.")
41 | return 0 # No cash position defined
42 |
43 | cash_target = cash_row['target_weight'].iloc[0]
44 | current_cash = cash_row['actual_weight'].iloc[0]
45 |
46 | if debug:
47 | logger.info("Calculating Cash Deployment Component ===")
48 | logger.info(f" Current cash weight: {current_cash:.4%}")
49 |
50 | # Calculate total buys and sells in dollar terms
51 | total_buys = 0
52 | for identifier, buy_var in buys.items():
53 | if identifier != CASH_CUSIP_ID:
54 | price = prices.loc[prices['identifier'] == identifier, 'price'].iloc[0]
55 | total_buys += buy_var * price
56 |
57 | total_sells = 0
58 | for _, lot in gain_loss.iterrows():
59 | tax_lot_id = lot['tax_lot_id']
60 | if tax_lot_id in sells:
61 | price = prices.loc[prices['identifier'] == lot['identifier'], 'price'].iloc[0]
62 | total_sells += sells[tax_lot_id] * price
63 |
64 | # Calculate new cash weight after trades
65 | new_cash_dollars = (current_cash * total_value) + total_sells - total_buys
66 | new_cash_weight = new_cash_dollars / total_value
67 |
68 | # Calculate initial excess cash
69 | initial_excess_cash = max(0, current_cash - cash_target)
70 |
71 | # Create variable for excess cash after trades
72 | excess_cash = pulp.LpVariable(f"excess_cash", lowBound=0)
73 | prob += new_cash_weight - cash_target <= excess_cash, "cash_excess_constr"
74 |
75 | if debug:
76 | logger.info(f"Added cash deployment component (minimizing new_cash_weight)")
77 | logger.info(f" Initial excess cash: {initial_excess_cash:.4%}")
78 |
79 | # Create list of terms to sum
80 | cash_terms = [(excess_cash - initial_excess_cash) * cash_normalization]
81 |
82 | # Return the sum of all cash terms
83 | return pulp.lpSum(cash_terms)
84 |
85 |
86 | def calculate_max_withdrawal_objective(
87 | self,
88 | prob: pulp.LpProblem,
89 | buys: Dict[str, pulp.LpVariable],
90 | sells: Dict[str, pulp.LpVariable],
91 | gain_loss: pd.DataFrame,
92 | debug: bool = True
93 | ) -> pulp.LpAffineExpression:
94 | """
95 | Calculate an objective that maximizes cash withdrawal.
96 | Creates an objective that maximizes the cash generated from selling securities.
97 |
98 | Args:
99 | prob: PuLP optimization problem
100 | buys: Dictionary of buy variables
101 | sells: Dictionary of sell variables
102 | gain_loss: DataFrame with gain/loss report
103 | debug: Enable debug logging
104 |
105 | Returns:
106 | Cash withdrawal maximization objective term (negative since we're minimizing)
107 | """
108 | if debug:
109 | logger.info("Calculating max withdrawal objective")
110 |
111 | # Create a cash generation objective (for maximizing withdrawal)
112 | # We want to maximize cash, which means minimizing the negative of cash
113 | total_cash_generated = 0
114 | for _, lot in gain_loss.iterrows():
115 | tax_lot_id = lot['tax_lot_id']
116 | identifier = lot['identifier']
117 | price = self.strategy.prices.loc[self.strategy.prices['identifier'] == identifier, 'price'].iloc[0]
118 | total_cash_generated += sells[tax_lot_id] * price
119 |
120 | # In a minimization problem, we minimize the negative of what we want to maximize
121 | return -1 * total_cash_generated
122 |
--------------------------------------------------------------------------------
/src/service/reports/gain_loss_report.py:
--------------------------------------------------------------------------------
1 | import pandas as pd
2 | from datetime import date
3 | from typing import Optional
4 |
5 | def generate_gain_loss_report(
6 | tax_lots: pd.DataFrame,
7 | prices: pd.DataFrame,
8 | current_date: date,
9 | tax_rates: pd.DataFrame
10 | ) -> pd.DataFrame:
11 | """
12 | Generate a gain/loss report for all tax lots using current prices.
13 |
14 | Args:
15 | tax_lots: DataFrame of tax lots
16 | prices: DataFrame of current prices
17 | current_date: Current date for calculating holding period
18 | tax_rates: DataFrame with tax rates
19 |
20 | Returns:
21 | DataFrame with columns:
22 | - tax_lot_id: Unique identifier for the tax lot
23 | - identifier: Security identifier
24 | - quantity: Number of shares
25 | - cost_basis: Total cost basis for the lot
26 | - cost_per_share: Cost basis per share
27 | - current_price: Current price per share
28 | - market_value: Current total value (quantity * current_price)
29 | - unrealized_gain: Market value - cost basis
30 | - unrealized_gain_pct: Unrealized gain as percentage of cost basis
31 | - holding_period_days: Number of days position has been held
32 | - is_long_term: Whether the position qualifies for long-term capital gains (held > 365 days)
33 | - gain_type: Type of gain for tax purposes (short_term or long_term)
34 | - federal_tax_rate: Applicable federal tax rate
35 | - state_tax_rate: Applicable state tax rate
36 | - total_tax_rate: Combined federal and state tax rate
37 | - tax_liability: Estimated tax liability if sold at current price
38 | - per_share_tax_liability: Tax liability per share
39 | - tax_gain_loss_percentage: Tax gain/loss percentage (gain/loss percentage divided by tax rate)
40 | """
41 | # Define column order upfront for both empty and non-empty cases
42 | column_order = [
43 | 'tax_lot_id',
44 | 'identifier',
45 | 'quantity',
46 | 'cost_basis',
47 | 'cost_per_share',
48 | 'current_price',
49 | 'market_value',
50 | 'unrealized_gain',
51 | 'unrealized_gain_pct',
52 | 'holding_period_days',
53 | 'is_long_term',
54 | 'gain_type',
55 | 'federal_tax_rate',
56 | 'state_tax_rate',
57 | 'total_tax_rate',
58 | 'tax_liability',
59 | 'per_share_tax_liability',
60 | 'tax_gain_loss_percentage'
61 | ]
62 |
63 | # Return empty DataFrame with correct columns if tax_lots is empty
64 | if tax_lots.empty:
65 | return pd.DataFrame(columns=column_order)
66 |
67 | # Create copy to avoid modifying inputs
68 | report = tax_lots.copy()
69 |
70 | # Join with prices
71 | report = report.merge(
72 | prices[['identifier', 'price']],
73 | on='identifier',
74 | how='left',
75 | validate='many_to_one'
76 | )
77 |
78 | # Calculate derived values
79 | report['cost_per_share'] = report['cost_basis'] / report['quantity']
80 | report['market_value'] = report['quantity'] * report['price']
81 | report['unrealized_gain'] = report['market_value'] - report['cost_basis']
82 | report['unrealized_gain_pct'] = report['unrealized_gain'] / report['cost_basis']
83 | report['holding_period_days'] = (pd.Timestamp(current_date) - report['date']).dt.days
84 | report['is_long_term'] = report['holding_period_days'] > 365
85 |
86 | # Determine gain type for tax purposes
87 | report['gain_type'] = report['is_long_term'].map({True: 'long_term', False: 'short_term'})
88 |
89 | # Join with tax rates based on gain type
90 | report = report.merge(
91 | tax_rates[['gain_type', 'federal_rate', 'state_rate', 'total_rate']],
92 | on='gain_type',
93 | how='left',
94 | validate='many_to_one'
95 | )
96 |
97 | # Calculate tax impact
98 | # - Positive tax_liability means taxes owed on gains (unrealized_gain > 0)
99 | # - Negative tax_liability means potential tax benefit from losses (unrealized_gain < 0)
100 | # which can offset other gains when realized
101 | report['tax_liability'] = report['unrealized_gain'] * report['total_rate']
102 |
103 | # Calculate per-share tax liability for optimization
104 | report['per_share_tax_liability'] = report['tax_liability'] / report['quantity']
105 |
106 | # Calculate tax gain/loss percentage (gain/loss percentage divided by tax rate)
107 | # Note: Handle division by zero by replacing 0 tax rates with NaN
108 | safe_total_rate = report['total_rate'].replace(0, float('nan'))
109 | report['tax_gain_loss_percentage'] = report['unrealized_gain_pct'] * safe_total_rate
110 |
111 | # Rename columns for clarity
112 | report = report.rename(columns={
113 | 'price': 'current_price',
114 | 'federal_rate': 'federal_tax_rate',
115 | 'state_rate': 'state_tax_rate',
116 | 'total_rate': 'total_tax_rate'
117 | })
118 |
119 | return report[column_order]
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | # Byte-compiled / optimized / DLL files
2 | __pycache__/
3 | *.py[cod]
4 | *$py.class
5 |
6 | # C extensions
7 | *.so
8 |
9 | # Distribution / packaging
10 | .Python
11 | build/
12 | develop-eggs/
13 | dist/
14 | downloads/
15 | eggs/
16 | .eggs/
17 | lib/
18 | lib64/
19 | parts/
20 | sdist/
21 | var/
22 | wheels/
23 | share/python-wheels/
24 | *.egg-info/
25 | .installed.cfg
26 | *.egg
27 | MANIFEST
28 |
29 | # PyInstaller
30 | # Usually these files are written by a python script from a template
31 | # before PyInstaller builds the exe, so as to inject date/other infos into it.
32 | *.manifest
33 | *.spec
34 |
35 | # Installer logs
36 | pip-log.txt
37 | pip-delete-this-directory.txt
38 |
39 | # Unit test / coverage reports
40 | htmlcov/
41 | .tox/
42 | .nox/
43 | .coverage
44 | .coverage.*
45 | .cache
46 | nosetests.xml
47 | coverage.xml
48 | *.cover
49 | *.py,cover
50 | .hypothesis/
51 | .pytest_cache/
52 | cover/
53 |
54 | # Translations
55 | *.mo
56 | *.pot
57 |
58 | # Django stuff:
59 | *.log
60 | local_settings.py
61 | db.sqlite3
62 | db.sqlite3-journal
63 |
64 | # Flask stuff:
65 | instance/
66 | .webassets-cache
67 |
68 | # Scrapy stuff:
69 | .scrapy
70 |
71 | # Sphinx documentation
72 | docs/_build/
73 |
74 | # PyBuilder
75 | .pybuilder/
76 | target/
77 |
78 | # Jupyter Notebook
79 | .ipynb_checkpoints
80 |
81 | # IPython
82 | profile_default/
83 | ipython_config.py
84 |
85 | # pyenv
86 | # For a library or package, you might want to ignore these files since the code is
87 | # intended to run in multiple environments; otherwise, check them in:
88 | # .python-version
89 |
90 | # pipenv
91 | # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
92 | # However, in case of collaboration, if having platform-specific dependencies or dependencies
93 | # having no cross-platform support, pipenv may install dependencies that don't work, or not
94 | # install all needed dependencies.
95 | #Pipfile.lock
96 |
97 | # UV
98 | # Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
99 | # This is especially recommended for binary packages to ensure reproducibility, and is more
100 | # commonly ignored for libraries.
101 | #uv.lock
102 |
103 | # poetry
104 | # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
105 | # This is especially recommended for binary packages to ensure reproducibility, and is more
106 | # commonly ignored for libraries.
107 | # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
108 | #poetry.lock
109 |
110 | # pdm
111 | # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
112 | #pdm.lock
113 | # pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
114 | # in version control.
115 | # https://pdm.fming.dev/latest/usage/project/#working-with-version-control
116 | .pdm.toml
117 | .pdm-python
118 | .pdm-build/
119 |
120 | # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
121 | __pypackages__/
122 |
123 | # Celery stuff
124 | celerybeat-schedule
125 | celerybeat.pid
126 |
127 | # SageMath parsed files
128 | *.sage.py
129 |
130 | # Environments
131 | .env
132 | env_local.env
133 | .venv
134 | env/
135 | venv/
136 | ENV/
137 | env.bak/
138 | venv.bak/
139 |
140 | # Spyder project settings
141 | .spyderproject
142 | .spyproject
143 |
144 | # Rope project settings
145 | .ropeproject
146 |
147 | # mkdocs documentation
148 | /site
149 |
150 | # mypy
151 | .mypy_cache/
152 | .dmypy.json
153 | dmypy.json
154 |
155 | # Pyre type checker
156 | .pyre/
157 |
158 | # pytype static type analyzer
159 | .pytype/
160 |
161 | # Cython debug symbols
162 | cython_debug/
163 |
164 | # PyCharm
165 | # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
166 | # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
167 | # and can be added to the global gitignore or merged into this file. For a more nuclear
168 | # option (not recommended) you can uncomment the following to ignore the entire idea folder.
169 | #.idea/
170 |
171 | # Abstra
172 | # Abstra is an AI-powered process automation framework.
173 | # Ignore directories containing user credentials, local state, and settings.
174 | # Learn more at https://abstra.io/docs
175 | .abstra/
176 |
177 | # Visual Studio Code
178 | # Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
179 | # that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
180 | # and can be added to the global gitignore or merged into this file. However, if you prefer,
181 | # you could uncomment the following to ignore the enitre vscode folder
182 | # .vscode/
183 |
184 | # Ruff stuff:
185 | .ruff_cache/
186 |
187 | # PyPI configuration file
188 | .pypirc
189 |
190 | # Cursor
191 | # Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
192 | # exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
193 | # refer to https://docs.cursor.com/context/ignore-files
194 | .cursorignore
195 | .cursorindexingignore
--------------------------------------------------------------------------------
/src/service/constraints/holding_time/holding_time_validator.py:
--------------------------------------------------------------------------------
1 | from typing import Optional, Tuple
2 | import pandas as pd
3 | import pulp
4 | from datetime import timedelta
5 |
6 | from src.service.constraints.base_validator import BaseValidator
7 | from src.service.constraints.holding_time.trading_day_lookup import TradingDayLookup
8 |
9 | class HoldingTimeValidator(BaseValidator):
10 | """Validator for minimum holding time requirements."""
11 |
12 | def __init__(self, oracle_strategy, holding_time_delta: timedelta):
13 | """
14 | Initialize HoldingTimeValidator.
15 |
16 | Args:
17 | oracle_strategy: Reference to the OracleStrategy instance
18 | holding_time_delta: Minimum holding time required
19 | """
20 | super().__init__(oracle_strategy)
21 | self.holding_time_delta = holding_time_delta
22 | self.trading_day_lookup = TradingDayLookup()
23 | self._last_current_date = self.strategy.oracle.current_date
24 | self._before_date = self._calculate_before_date(self._last_current_date)
25 |
26 | def _calculate_before_date(self, current_date: pd.Timestamp) -> pd.Timestamp:
27 | """
28 | Calculate the before date for holding time calculations.
29 |
30 | Args:
31 | current_date: The current date to calculate from
32 |
33 | Returns:
34 | The effective before date for holding time calculations
35 | """
36 | target_date = current_date - self.holding_time_delta
37 |
38 | # Get the trading day information
39 | trading_day_info = self.trading_day_lookup.get_trading_day(target_date)
40 |
41 | # If no trading day info is found, use the target date directly
42 | if trading_day_info is None:
43 | return target_date
44 |
45 | # If the date is not a trading day, find the nearest trading day before the current date
46 | if trading_day_info['date'] != trading_day_info['nearest_trading_day']:
47 | return pd.to_datetime(trading_day_info['backward_trading_day'])
48 |
49 | return pd.to_datetime(trading_day_info['date'])
50 |
51 | def _get_before_date(self, current_date: pd.Timestamp) -> pd.Timestamp:
52 | """
53 | Get the before date for holding time calculations, with caching.
54 |
55 | Args:
56 | current_date: The current date to calculate from
57 |
58 | Returns:
59 | The effective before date for holding time calculations
60 | """
61 | # If we've already calculated for this current_date, return cached value
62 | if self._last_current_date == current_date and self._before_date is not None:
63 | return self._before_date
64 |
65 | # Calculate and cache new value
66 | self._last_current_date = current_date
67 | self._before_date = self._calculate_before_date(current_date)
68 | return self._before_date
69 |
70 | def validate_buy(self, identifier: str, quantity: float) -> Tuple[bool, Optional[str]]:
71 | """Buying is always allowed with respect to holding time."""
72 | return True, None
73 |
74 | def validate_sell(self, tax_lot_id: str, quantity: float) -> Tuple[bool, Optional[str]]:
75 | """Check if a tax lot has been held long enough to sell."""
76 | if self.holding_time_delta is None or self.holding_time_delta <= timedelta(days=0):
77 | return True, None
78 |
79 | # Get the lot information
80 | lot_info = self.strategy.tax_lots[self.strategy.tax_lots['tax_lot_id'] == tax_lot_id].iloc[0]
81 | purchase_date = lot_info['date'].date()
82 |
83 | # Get the before date using the cached method
84 | before_date = self._get_before_date(self.strategy.oracle.current_date)
85 |
86 | # If the purchase date is after or equal to the before_date, the lot cannot be sold
87 | if purchase_date >= before_date.date():
88 | days_remaining = (self.holding_time_delta - (self.strategy.oracle.current_date - purchase_date)).days
89 | return False, f"Tax lot must be held for {days_remaining + 1} more days"
90 |
91 | return True, None
92 |
93 | def add_to_problem(
94 | self,
95 | prob: pulp.LpProblem,
96 | sells: dict,
97 | tax_lots: pd.DataFrame,
98 | current_date: pd.Timestamp
99 | ) -> None:
100 | """Add holding time constraints to the optimization problem."""
101 | if self.holding_time_delta is None or self.holding_time_delta <= timedelta(days=0):
102 | return
103 |
104 | # Get the before date using the cached method
105 | before_date = self._get_before_date(current_date)
106 |
107 | # Find tax lots acquired within the holding time window
108 | recently_bought_lots = tax_lots[
109 | pd.to_datetime(tax_lots["date"]).dt.date >= before_date.date()
110 | ]
111 |
112 | # Add constraint to prevent selling these lots
113 | for _, lot in recently_bought_lots.iterrows():
114 | tax_lot_id = lot['tax_lot_id']
115 | if tax_lot_id in sells:
116 | prob += (
117 | sells[tax_lot_id] == 0,
118 | f"No_sell_recently_bought_{tax_lot_id}"
119 | )
--------------------------------------------------------------------------------
/_build/_static/language_data.js:
--------------------------------------------------------------------------------
1 | /*
2 | * This script contains the language-specific data used by searchtools.js,
3 | * namely the list of stopwords, stemmer, scorer and splitter.
4 | */
5 |
6 | var stopwords = ["a", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "near", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"];
7 |
8 |
9 | /* Non-minified version is copied as a separate JS file, if available */
10 |
11 | /**
12 | * Porter Stemmer
13 | */
14 | var Stemmer = function() {
15 |
16 | var step2list = {
17 | ational: 'ate',
18 | tional: 'tion',
19 | enci: 'ence',
20 | anci: 'ance',
21 | izer: 'ize',
22 | bli: 'ble',
23 | alli: 'al',
24 | entli: 'ent',
25 | eli: 'e',
26 | ousli: 'ous',
27 | ization: 'ize',
28 | ation: 'ate',
29 | ator: 'ate',
30 | alism: 'al',
31 | iveness: 'ive',
32 | fulness: 'ful',
33 | ousness: 'ous',
34 | aliti: 'al',
35 | iviti: 'ive',
36 | biliti: 'ble',
37 | logi: 'log'
38 | };
39 |
40 | var step3list = {
41 | icate: 'ic',
42 | ative: '',
43 | alize: 'al',
44 | iciti: 'ic',
45 | ical: 'ic',
46 | ful: '',
47 | ness: ''
48 | };
49 |
50 | var c = "[^aeiou]"; // consonant
51 | var v = "[aeiouy]"; // vowel
52 | var C = c + "[^aeiouy]*"; // consonant sequence
53 | var V = v + "[aeiou]*"; // vowel sequence
54 |
55 | var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0
56 | var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1
57 | var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1
58 | var s_v = "^(" + C + ")?" + v; // vowel in stem
59 |
60 | this.stemWord = function (w) {
61 | var stem;
62 | var suffix;
63 | var firstch;
64 | var origword = w;
65 |
66 | if (w.length < 3)
67 | return w;
68 |
69 | var re;
70 | var re2;
71 | var re3;
72 | var re4;
73 |
74 | firstch = w.substr(0,1);
75 | if (firstch == "y")
76 | w = firstch.toUpperCase() + w.substr(1);
77 |
78 | // Step 1a
79 | re = /^(.+?)(ss|i)es$/;
80 | re2 = /^(.+?)([^s])s$/;
81 |
82 | if (re.test(w))
83 | w = w.replace(re,"$1$2");
84 | else if (re2.test(w))
85 | w = w.replace(re2,"$1$2");
86 |
87 | // Step 1b
88 | re = /^(.+?)eed$/;
89 | re2 = /^(.+?)(ed|ing)$/;
90 | if (re.test(w)) {
91 | var fp = re.exec(w);
92 | re = new RegExp(mgr0);
93 | if (re.test(fp[1])) {
94 | re = /.$/;
95 | w = w.replace(re,"");
96 | }
97 | }
98 | else if (re2.test(w)) {
99 | var fp = re2.exec(w);
100 | stem = fp[1];
101 | re2 = new RegExp(s_v);
102 | if (re2.test(stem)) {
103 | w = stem;
104 | re2 = /(at|bl|iz)$/;
105 | re3 = new RegExp("([^aeiouylsz])\\1$");
106 | re4 = new RegExp("^" + C + v + "[^aeiouwxy]$");
107 | if (re2.test(w))
108 | w = w + "e";
109 | else if (re3.test(w)) {
110 | re = /.$/;
111 | w = w.replace(re,"");
112 | }
113 | else if (re4.test(w))
114 | w = w + "e";
115 | }
116 | }
117 |
118 | // Step 1c
119 | re = /^(.+?)y$/;
120 | if (re.test(w)) {
121 | var fp = re.exec(w);
122 | stem = fp[1];
123 | re = new RegExp(s_v);
124 | if (re.test(stem))
125 | w = stem + "i";
126 | }
127 |
128 | // Step 2
129 | re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/;
130 | if (re.test(w)) {
131 | var fp = re.exec(w);
132 | stem = fp[1];
133 | suffix = fp[2];
134 | re = new RegExp(mgr0);
135 | if (re.test(stem))
136 | w = stem + step2list[suffix];
137 | }
138 |
139 | // Step 3
140 | re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/;
141 | if (re.test(w)) {
142 | var fp = re.exec(w);
143 | stem = fp[1];
144 | suffix = fp[2];
145 | re = new RegExp(mgr0);
146 | if (re.test(stem))
147 | w = stem + step3list[suffix];
148 | }
149 |
150 | // Step 4
151 | re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/;
152 | re2 = /^(.+?)(s|t)(ion)$/;
153 | if (re.test(w)) {
154 | var fp = re.exec(w);
155 | stem = fp[1];
156 | re = new RegExp(mgr1);
157 | if (re.test(stem))
158 | w = stem;
159 | }
160 | else if (re2.test(w)) {
161 | var fp = re2.exec(w);
162 | stem = fp[1] + fp[2];
163 | re2 = new RegExp(mgr1);
164 | if (re2.test(stem))
165 | w = stem;
166 | }
167 |
168 | // Step 5
169 | re = /^(.+?)e$/;
170 | if (re.test(w)) {
171 | var fp = re.exec(w);
172 | stem = fp[1];
173 | re = new RegExp(mgr1);
174 | re2 = new RegExp(meq1);
175 | re3 = new RegExp("^" + C + v + "[^aeiouwxy]$");
176 | if (re.test(stem) || (re2.test(stem) && !(re3.test(stem))))
177 | w = stem;
178 | }
179 | re = /ll$/;
180 | re2 = new RegExp(mgr1);
181 | if (re.test(w) && re2.test(w)) {
182 | re = /.$/;
183 | w = w.replace(re,"");
184 | }
185 |
186 | // and turn initial Y back to y
187 | if (firstch == "y")
188 | w = firstch.toLowerCase() + w.substr(1);
189 | return w;
190 | }
191 | }
192 |
193 |
--------------------------------------------------------------------------------
/_build/_static/sphinx_highlight.js:
--------------------------------------------------------------------------------
1 | /* Highlighting utilities for Sphinx HTML documentation. */
2 | "use strict";
3 |
4 | const SPHINX_HIGHLIGHT_ENABLED = true
5 |
6 | /**
7 | * highlight a given string on a node by wrapping it in
8 | * span elements with the given class name.
9 | */
10 | const _highlight = (node, addItems, text, className) => {
11 | if (node.nodeType === Node.TEXT_NODE) {
12 | const val = node.nodeValue;
13 | const parent = node.parentNode;
14 | const pos = val.toLowerCase().indexOf(text);
15 | if (
16 | pos >= 0 &&
17 | !parent.classList.contains(className) &&
18 | !parent.classList.contains("nohighlight")
19 | ) {
20 | let span;
21 |
22 | const closestNode = parent.closest("body, svg, foreignObject");
23 | const isInSVG = closestNode && closestNode.matches("svg");
24 | if (isInSVG) {
25 | span = document.createElementNS("http://www.w3.org/2000/svg", "tspan");
26 | } else {
27 | span = document.createElement("span");
28 | span.classList.add(className);
29 | }
30 |
31 | span.appendChild(document.createTextNode(val.substr(pos, text.length)));
32 | const rest = document.createTextNode(val.substr(pos + text.length));
33 | parent.insertBefore(
34 | span,
35 | parent.insertBefore(
36 | rest,
37 | node.nextSibling
38 | )
39 | );
40 | node.nodeValue = val.substr(0, pos);
41 | /* There may be more occurrences of search term in this node. So call this
42 | * function recursively on the remaining fragment.
43 | */
44 | _highlight(rest, addItems, text, className);
45 |
46 | if (isInSVG) {
47 | const rect = document.createElementNS(
48 | "http://www.w3.org/2000/svg",
49 | "rect"
50 | );
51 | const bbox = parent.getBBox();
52 | rect.x.baseVal.value = bbox.x;
53 | rect.y.baseVal.value = bbox.y;
54 | rect.width.baseVal.value = bbox.width;
55 | rect.height.baseVal.value = bbox.height;
56 | rect.setAttribute("class", className);
57 | addItems.push({ parent: parent, target: rect });
58 | }
59 | }
60 | } else if (node.matches && !node.matches("button, select, textarea")) {
61 | node.childNodes.forEach((el) => _highlight(el, addItems, text, className));
62 | }
63 | };
64 | const _highlightText = (thisNode, text, className) => {
65 | let addItems = [];
66 | _highlight(thisNode, addItems, text, className);
67 | addItems.forEach((obj) =>
68 | obj.parent.insertAdjacentElement("beforebegin", obj.target)
69 | );
70 | };
71 |
72 | /**
73 | * Small JavaScript module for the documentation.
74 | */
75 | const SphinxHighlight = {
76 |
77 | /**
78 | * highlight the search words provided in localstorage in the text
79 | */
80 | highlightSearchWords: () => {
81 | if (!SPHINX_HIGHLIGHT_ENABLED) return; // bail if no highlight
82 |
83 | // get and clear terms from localstorage
84 | const url = new URL(window.location);
85 | const highlight =
86 | localStorage.getItem("sphinx_highlight_terms")
87 | || url.searchParams.get("highlight")
88 | || "";
89 | localStorage.removeItem("sphinx_highlight_terms")
90 | url.searchParams.delete("highlight");
91 | window.history.replaceState({}, "", url);
92 |
93 | // get individual terms from highlight string
94 | const terms = highlight.toLowerCase().split(/\s+/).filter(x => x);
95 | if (terms.length === 0) return; // nothing to do
96 |
97 | // There should never be more than one element matching "div.body"
98 | const divBody = document.querySelectorAll("div.body");
99 | const body = divBody.length ? divBody[0] : document.querySelector("body");
100 | window.setTimeout(() => {
101 | terms.forEach((term) => _highlightText(body, term, "highlighted"));
102 | }, 10);
103 |
104 | const searchBox = document.getElementById("searchbox");
105 | if (searchBox === null) return;
106 | searchBox.appendChild(
107 | document
108 | .createRange()
109 | .createContextualFragment(
110 | '
67 |
111 |
68 |
77 |
110 |
78 |
95 |
109 | ' + 111 | '' + 112 | _("Hide Search Matches") + 113 | "
" 114 | ) 115 | ); 116 | }, 117 | 118 | /** 119 | * helper function to hide the search marks again 120 | */ 121 | hideSearchWords: () => { 122 | document 123 | .querySelectorAll("#searchbox .highlight-link") 124 | .forEach((el) => el.remove()); 125 | document 126 | .querySelectorAll("span.highlighted") 127 | .forEach((el) => el.classList.remove("highlighted")); 128 | localStorage.removeItem("sphinx_highlight_terms") 129 | }, 130 | 131 | initEscapeListener: () => { 132 | // only install a listener if it is really needed 133 | if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return; 134 | 135 | document.addEventListener("keydown", (event) => { 136 | // bail for input elements 137 | if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return; 138 | // bail with special keys 139 | if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return; 140 | if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) { 141 | SphinxHighlight.hideSearchWords(); 142 | event.preventDefault(); 143 | } 144 | }); 145 | }, 146 | }; 147 | 148 | _ready(() => { 149 | /* Do not call highlightSearchWords() when we are on the search page. 150 | * It will highlight words from the *previous* search query. 151 | */ 152 | if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords(); 153 | SphinxHighlight.initEscapeListener(); 154 | }); 155 | -------------------------------------------------------------------------------- /src/service/constraints/restriction/restriction_validator.py: -------------------------------------------------------------------------------- 1 | from typing import Optional, Tuple, List 2 | import pandas as pd 3 | import pulp 4 | 5 | from src.service.constraints.base_validator import BaseValidator 6 | 7 | class RestrictionValidator(BaseValidator): 8 | """Validator for stock and wash sale restrictions.""" 9 | 10 | def __init__(self, strategy, enforce_wash_sale_prevention: bool = True): 11 | """Initialize the validator. 12 | 13 | Args: 14 | strategy: The strategy object containing portfolio information 15 | enforce_wash_sales: If False, wash sale restrictions will be ignored 16 | """ 17 | super().__init__(strategy) 18 | self.enforce_wash_sale_prevention = enforce_wash_sale_prevention 19 | 20 | def validate_buy(self, identifier: str, quantity: float) -> Tuple[bool, Optional[str]]: 21 | """Check if buying a security is allowed by restrictions.""" 22 | # Check stock restrictions 23 | if self.strategy.oracle.stock_restrictions is not None: 24 | restrictions = self.strategy.oracle.stock_restrictions 25 | if identifier in restrictions["identifier"].values: 26 | if not restrictions.loc[identifier, 'can_buy']: 27 | return False, f"Security {identifier} is restricted from buying" 28 | 29 | # Check wash sale restrictions 30 | if self.enforce_wash_sale_prevention and self.strategy.oracle.wash_sale_restrictions is not None: 31 | if self.strategy.oracle.wash_sale_restrictions.is_restricted_from_buying(identifier): 32 | return False, f"Security {identifier} is restricted due to wash sale rules" 33 | 34 | return True, None 35 | 36 | def validate_sell(self, tax_lot_id: str, quantity: float) -> Tuple[bool, Optional[str]]: 37 | """Check if selling a tax lot is allowed by restrictions.""" 38 | # Get the identifier for this tax lot 39 | lot_info = self.strategy.tax_lots[self.strategy.tax_lots['tax_lot_id'] == tax_lot_id].iloc[0] 40 | identifier = lot_info['identifier'] 41 | 42 | # Check stock restrictions 43 | if self.strategy.oracle.stock_restrictions is not None: 44 | restrictions = self.strategy.oracle.stock_restrictions 45 | if identifier in restrictions["identifier"].values: 46 | if not restrictions.loc[restrictions["identifier"] == identifier, 'can_sell'].iloc[0]: 47 | return False, f"Security {identifier} is restricted from selling" 48 | 49 | # Check wash sale restrictions 50 | if self.enforce_wash_sale_prevention and self.strategy.oracle.wash_sale_restrictions is not None: 51 | restricted_lots = self.strategy.oracle.wash_sale_restrictions.get_restricted_lots(identifier) 52 | if not restricted_lots.empty: 53 | for _, lot in restricted_lots.iterrows(): 54 | if lot['tax_lot_id'] == tax_lot_id: 55 | return False, f"Tax lot {tax_lot_id} is restricted due to wash sale rules" 56 | 57 | return True, None 58 | 59 | def add_to_problem( 60 | self, 61 | prob: pulp.LpProblem, 62 | buys: dict, 63 | sells: dict, 64 | gain_loss: pd.DataFrame, 65 | stock_restrictions: pd.DataFrame, 66 | wash_sale_restrictions, 67 | all_identifiers: List[str] 68 | ) -> None: 69 | """Add stock and wash sale restrictions to the optimization problem.""" 70 | # Add stock restrictions 71 | if stock_restrictions is not None: 72 | for _, row in stock_restrictions.iterrows(): 73 | identifier = row['identifier'] 74 | if not row['can_buy']: 75 | if identifier in buys: 76 | prob += (buys[identifier] == 0), f"no_buy_{identifier}" 77 | if not row['can_sell']: 78 | for _, lot in gain_loss[gain_loss['identifier'] == identifier].iterrows(): 79 | if lot['tax_lot_id'] in sells: 80 | prob += (sells[lot['tax_lot_id']] == 0), f"no_sell_{lot['tax_lot_id']}" 81 | 82 | # Wash sale restrictions 83 | if self.enforce_wash_sale_prevention and wash_sale_restrictions is not None: 84 | for identifier in all_identifiers: 85 | # Check buy restrictions 86 | if wash_sale_restrictions.is_restricted_from_buying(identifier): 87 | if identifier in buys: 88 | prob += (buys[identifier] == 0), f"wash_sale_buy_{identifier}" 89 | 90 | # Check sell restrictions - get all restricted lots for this identifier 91 | restricted_lots = wash_sale_restrictions.get_restricted_lots(identifier) 92 | if not restricted_lots.empty: 93 | # Add binary variable to track if liquidating 94 | liquidate = pulp.LpVariable(f"liquidate_{identifier}", cat='Binary') 95 | 96 | all_tax_lots = self.strategy.oracle.all_tax_lots 97 | all_quantity = all_tax_lots.loc[all_tax_lots['identifier'] == identifier, 'quantity'].sum() 98 | 99 | identifier_sells = [] 100 | for _, lot in gain_loss[gain_loss['identifier'] == identifier].iterrows(): 101 | if lot['tax_lot_id'] in sells: 102 | identifier_sells.append(sells[lot['tax_lot_id']]) 103 | 104 | prob += (pulp.lpSum(identifier_sells) >= (all_quantity * liquidate)), f"wash_sale_liquidate_{identifier}" 105 | 106 | for _, lot in restricted_lots.iterrows(): 107 | if lot['tax_lot_id'] in sells: 108 | prob += (sells[lot['tax_lot_id']] == (lot["quantity"] * liquidate)), f"wash_sale_sell_{lot['tax_lot_id']}" 109 | -------------------------------------------------------------------------------- /tests/test_onboarding.py: -------------------------------------------------------------------------------- 1 | from datetime import date 2 | import pandas as pd 3 | import unittest 4 | from src.service.initializers import ( 5 | initialize_targets, 6 | initialize_tax_lots, 7 | initialize_prices, 8 | initialize_spreads, 9 | initialize_factor_model 10 | ) 11 | from src.service.oracle import Oracle 12 | from src.service.oracle_strategy import OracleStrategy 13 | from src.service.helpers.enums import OracleOptimizationType 14 | from src.service.helpers.constants import CASH_CUSIP_ID 15 | 16 | class TestBasicPortfolioOptimization(unittest.TestCase): 17 | """Test basic portfolio optimization functionality.""" 18 | 19 | def setUp(self): 20 | """Set up test data for basic portfolio optimization. 21 | 22 | Initial State: 23 | - STOCK_A: $10k position (50%) 24 | - Price: $100/share, 100 shares 25 | - Cost basis: $100/share 26 | 27 | - STOCK_B: $10k position (50%) 28 | - Price: $100/share, 100 shares 29 | - Cost basis: $100/share 30 | 31 | Total Portfolio: $20k + $10k cash 32 | Target Weights: 40-40-20 (STOCK_A, STOCK_B, CASH) 33 | """ 34 | self.current_date = date(2024, 4, 20) 35 | 36 | # Create tax rates data 37 | self.tax_rates = pd.DataFrame([ 38 | { 39 | 'gain_type': 'short_term', 40 | 'federal_rate': 0.35, 41 | 'state_rate': 0.06, 42 | 'total_rate': 0.41 43 | }, 44 | { 45 | 'gain_type': 'long_term', 46 | 'federal_rate': 0.20, 47 | 'state_rate': 0.06, 48 | 'total_rate': 0.26 49 | }, 50 | { 51 | "gain_type": "qualified_dividend", 52 | "federal_rate": 0.15, 53 | "state_rate": 0.06, 54 | "total_rate": 0.21 55 | } 56 | ]) 57 | 58 | # Define test data based on documentation example 59 | self.targets_df = pd.DataFrame({ 60 | 'asset_class': ['STOCK_A', 'STOCK_B', 'CASH'], 61 | 'target_weight': [0.4, 0.4, 0.2], 62 | 'identifiers': [['STOCK_A'], ['STOCK_B'], [CASH_CUSIP_ID]] 63 | }) 64 | 65 | self.tax_lots_df = pd.DataFrame({ 66 | 'tax_lot_id': ['lot_a1', 'lot_b1'], 67 | 'identifier': ['STOCK_A', 'STOCK_B'], 68 | 'quantity': [100, 100], 69 | 'cost_basis': [100, 100], 70 | 'date': ['2024-01-01', '2024-01-01'] 71 | }) 72 | 73 | self.prices_df = pd.DataFrame([ 74 | { 75 | 'identifier': 'STOCK_A', 76 | 'price': 100.0, 77 | }, 78 | { 79 | 'identifier': 'STOCK_B', 80 | 'price': 100.0, 81 | }, 82 | { 83 | 'identifier': CASH_CUSIP_ID, 84 | 'price': 1.0, 85 | } 86 | ]) 87 | 88 | self.spreads_df = pd.DataFrame([ 89 | { 90 | 'identifier': 'STOCK_A', 91 | 'spread': 0.001 # 10 basis points 92 | }, 93 | { 94 | 'identifier': 'STOCK_B', 95 | 'spread': 0.001 # 10 basis points 96 | }, 97 | { 98 | 'identifier': CASH_CUSIP_ID, 99 | 'spread': 0.0 # No spread for cash 100 | } 101 | ]) 102 | 103 | # Create Oracle instance 104 | self.oracle = Oracle( 105 | current_date=self.current_date, 106 | recently_closed_lots=pd.DataFrame(), 107 | stock_restrictions=pd.DataFrame(), 108 | tax_rates=self.tax_rates 109 | ) 110 | 111 | # Create and configure strategy 112 | self.strategy = OracleStrategy( 113 | strategy_id="STRATEGY_1", 114 | tax_lots=self.tax_lots_df, 115 | prices=self.prices_df, 116 | cash=10000.0, 117 | targets=self.targets_df, 118 | asset_class_targets=None, 119 | spreads=self.spreads_df, 120 | factor_model=None, 121 | optimization_type=OracleOptimizationType.TAX_AWARE, 122 | deminimus_cash_target=0.0001, 123 | withdrawal_amount=0.0, 124 | enforce_wash_sale_prevention=True 125 | ) 126 | 127 | self.strategy.set_oracle(self.oracle) 128 | self.oracle.strategies = [self.strategy] 129 | self.oracle.initialize_wash_sale_restrictions(percentage_protection_from_inadvertent_wash_sales=0.003) 130 | 131 | def test_optimization_response_format(self): 132 | """Test that the optimization returns the expected response format.""" 133 | # Run optimization with settings from documentation 134 | results, netted_trades = self.oracle.compute_optimal_trades_for_all_strategies( 135 | settings={ 136 | "strategies": { 137 | "STRATEGY_1": { 138 | "weight_tax": 1.0, 139 | "weight_drift": 1.0, 140 | "weight_transaction": 1.0, 141 | "weight_factor_model": 0.0, 142 | "weight_cash_drag": 0.0, 143 | "rebalance_threshold": 0.001, 144 | "buy_threshold": 0.0005, 145 | "holding_time_days": 0, 146 | "should_tlh": True, 147 | "tlh_min_loss_threshold": 0.015, 148 | "range_min_weight_multiplier": 0.5, 149 | "range_max_weight_multiplier": 2.0, 150 | "min_notional": 0, 151 | "rank_penalty_factor": 0.0, 152 | "trade_rounding": 4 153 | } 154 | } 155 | } 156 | ) 157 | 158 | # Verify response format and basic expectations 159 | self.assertIsInstance(results, dict, "Results should be a dictionary") 160 | self.assertIsInstance(netted_trades, pd.DataFrame, "Netted trades should be a DataFrame") 161 | 162 | # Verify we have exactly 2 buy trades 163 | buy_trades = netted_trades[netted_trades["action"] == "buy"] 164 | self.assertEqual(len(buy_trades), 2, "Expected exactly 2 buy trades") 165 | 166 | 167 | if __name__ == '__main__': 168 | unittest.main() 169 | -------------------------------------------------------------------------------- /_build/_modules/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 |
25 |
57 |
58 |
62 |
63 |
119 |
120 |
125 |
126 |
127 |
--------------------------------------------------------------------------------
/_build/py-modindex.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 |
7 |
8 |
64 |
118 |
65 |
74 |
117 |
75 |
102 |
116 |
76 |
77 |
101 | All modules for which code is available
78 |- functools 79 |
- service.constraints.constraints_manager 80 |
- service.helpers.enums 81 |
- service.objectives.cash_deployment.cash_deployment 82 |
- service.objectives.drift.drift_optimization 83 |
- service.objectives.factor_model.factor_model_optimization 84 |
- service.objectives.objective_manager 85 |
- service.objectives.taxes.tax_optimization 86 |
- service.objectives.taxes.tlh 87 |
- service.objectives.transaction_costs.transaction_optimization 88 |
- service.oracle 89 |
- service.oracle_strategy 90 |
- src.service.initializers.closed_lots 91 |
- src.service.initializers.factor_model 92 |
- src.service.initializers.prices 93 |
- src.service.initializers.spreads 94 |
- src.service.initializers.stock_restrictions 95 |
- src.service.initializers.targets 96 |
- src.service.initializers.tax_lots 97 |
- src.service.initializers.tax_rates 98 |
28 |
60 |
61 |
65 |
66 |
149 |
150 |
155 |
156 |
157 |
--------------------------------------------------------------------------------
67 |
148 |
68 |
77 |
147 |
78 |
132 |
146 |
79 |
80 |
81 |
88 |
128 |
129 |
130 |
131 | Python Module Index
82 | 83 |
84 | s
85 |
86 |
87 | | 90 | s | ||
| 94 | |
95 | service | 96 | |
| 99 | |
100 | service.objectives.cash_deployment.cash_deployment | 101 | |
| 104 | |
105 | service.objectives.drift.drift_optimization | 106 | |
| 109 | |
110 | service.objectives.factor_model.factor_model_optimization | 111 | |
| 114 | |
115 | service.objectives.taxes.tax_optimization | 116 | |
| 119 | |
120 | service.objectives.taxes.tlh | 121 | |
| 124 | |
125 | service.objectives.transaction_costs.transaction_optimization | 126 | |
