dead-parrot 0.1.0__tar.gz

dead_parrot-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# macOS
+.DS_Store
+
+# dotenv
+.env
+
+# Virtual environments
+.venv/
+
+# Python
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# ruff
+.ruff_cache/
+
+# mypy
+.mypy_cache/
+
+# dead-parrot
+demos/ecb_ai_assistant/embeddings/

dead_parrot-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

dead_parrot-0.1.0/.vscode/extensions.json

@@ -0,0 +1,18 @@
+{
+    "recommendations": [
+        // Python
+        "ms-python.python",
+        "ms-python.vscode-pylance",
+        "ms-python.debugpy",
+
+        // Type checking
+        "ms-python.mypy-type-checker",
+
+        // Linting and formatting
+        "charliermarsh.ruff",
+
+        // Various
+        "github.github-vscode-theme",
+        "github.copilot-chat",
+    ]
+}

dead_parrot-0.1.0/.vscode/settings.json

@@ -0,0 +1,49 @@
+{
+    // Color theme
+    "workbench.colorTheme": "GitHub Dark Dimmed",
+
+    // Font
+    "editor.fontFamily": "JetBrains Mono, Menlo, Monaco",
+    "terminal.integrated.fontFamily": "JetBrains Mono, Menlo, Monaco",
+    "editor.fontSize": 12.5,
+    "terminal.integrated.fontSize": 12.5,
+    "editor.fontLigatures": true,
+    "terminal.integrated.fontLigatures.enabled": true,
+
+    // Indentation
+    "editor.detectIndentation": false,
+    "editor.insertSpaces": true,
+    "editor.tabSize": 4,
+
+    // Lines
+    "editor.rulers": [ 88 ],
+    "editor.wordWrap": "off",
+
+    // Whitespace
+    "editor.renderWhitespace": "boundary",
+    "files.trimTrailingWhitespace": true,
+    "files.insertFinalNewline": true,
+
+    // Various
+    "explorer.sortOrder": "type",
+    "files.autoSave": "onFocusChange",
+    "files.exclude": {
+        "**/.git": false,
+    },
+
+    // Python
+    "[python]": {
+        "editor.defaultFormatter": "charliermarsh.ruff",
+        "editor.formatOnSave": true,
+        "editor.codeActionsOnSave": {
+            "source.fixAll": "always",
+            "source.organizeImports": "always"
+        },
+    },
+    "mypy-type-checker.path": ["mypy"],
+
+    // Markdown
+    "[markdown]": {
+        "editor.wordWrap": "off",
+    },
+}

dead_parrot-0.1.0/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2026 Lucas Konstantin Bärenfänger (@pygumby)
+
+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.

dead_parrot-0.1.0/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: dead-parrot
+Version: 0.1.0
+Summary: A Framework for Scalable AI Assistants
+Project-URL: source, https://github.com/pygumby/dead-parrot
+Author: Lucas Konstantin Bärenfänger
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: dspy>=3.1.3
+Requires-Dist: faiss-cpu>=1.13.2
+Requires-Dist: pandas>=3.0.1
+Requires-Dist: pypdf>=6.7.3
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# 😵🦜 dead-parrot
+## Framework for Scalable AI Assistants
+
+</div>
+
+**dead-parrot** is a Python package authored by Lucas Konstantin Bärenfänger ([@pygumby](https://github.com/pygumby)) in the context of his thesis for the master's program "Data Analytics & Management" at Frankfurt School of Finance & Management.
+
+----
+
+## Usage
+
+Please refer to the self-contained usage examples provided in the [demos](demos/) folder.
+
+## Development
+
+- Install dependencies: `uv sync`
+- Type-check: `uv run mypy .`
+- Lint: `uv run ruff check . --fix`
+- Format: `uv run ruff format .`
+
+## License
+
+[MIT License](LICENSE)

dead_parrot-0.1.0/README.md

@@ -0,0 +1,25 @@
+<div align="center">
+
+# 😵🦜 dead-parrot
+## Framework for Scalable AI Assistants
+
+</div>
+
+**dead-parrot** is a Python package authored by Lucas Konstantin Bärenfänger ([@pygumby](https://github.com/pygumby)) in the context of his thesis for the master's program "Data Analytics & Management" at Frankfurt School of Finance & Management.
+
+----
+
+## Usage
+
+Please refer to the self-contained usage examples provided in the [demos](demos/) folder.
+
+## Development
+
+- Install dependencies: `uv sync`
+- Type-check: `uv run mypy .`
+- Lint: `uv run ruff check . --fix`
+- Format: `uv run ruff format .`
+
+## License
+
+[MIT License](LICENSE)

dead_parrot-0.1.0/demos/ecb_ai_assistant/.env.example

@@ -0,0 +1 @@
+OPENAI_API_KEY=your_openai_api_key

dead_parrot-0.1.0/demos/ecb_ai_assistant/examples/ecb_staff_rules.json

@@ -0,0 +1,202 @@
+[
+    [
+        "What is the maximum duration of a non-convertible fixed-term contract issued to replace a member of staff on maternity leave?",
+        "The maximum duration for such a contract is six years, with the possibility of extension for up to ten years for the same replacement. This is specified in Article 2.0a.1(a) of the Staff Rules. (Page 45)"
+    ],
+    [
+        "How much time is a member of staff given to prepare their defense after receiving a final reasoned report in a disciplinary procedure?",
+        "A member of staff is given not less than 15 calendar days from the receipt of the report to prepare their defense. This rule applies to procedures both with and without the Disciplinary Committee. (Pages 125, 127)"
+    ],
+    [
+        "What are the core time periods for ECB staff on a Tuesday?",
+        "On Tuesdays, the core time periods during which staff must be present are from 10 a.m. to 12 p.m. and from 2 p.m. to 4.30 p.m. These hours are part of the standard flexitime arrangement. (Page 78)"
+    ],
+    [
+        "How many days of special leave are granted for the birth of a member of staff's child if they are not entitled to maternity leave?",
+        "A member of staff is entitled to 20 days of special leave per child for the birth of a legitimate or natural child. This entitlement is provided under Article 5.10.1(c). (Page 96)"
+    ],
+    [
+        "Under what condition can a member of staff accept hospitality from the private sector?",
+        "Hospitality may be accepted if it is offered in a work-related context, is not frequent, and has a value of up to EUR 50. However, no hospitality may be accepted from current or potential suppliers or credit institutions during inspections or audits. (Page 6)"
+    ],
+    [
+        "What is the maximum number of teleworking days allowed from a location outside the Union per calendar year?",
+        "Members of staff may telework from a location outside the Union for up to 20 working days per calendar year. This is part of the overall 90-day limit for teleworking away from the country of employment. (Page 84)"
+    ],
+    [
+        "What happens to excess working hours that exceed 48 hours at the end of a month?",
+        "Any excess hours accumulated under the flexitime arrangement that exceed 48 hours (six days) for full-time staff shall be forfeited. However, for staff entitled to overtime compensation, these may be approved as overtime by a manager. (Page 81)"
+    ],
+    [
+        "Who is eligible for an employment contract for an indefinite period (convertible contract)?",
+        "Staff assigned to permanent vacant posts below I band engaged for three years, and those at I band and above engaged for five years, are eligible. Conversion depends on at least overall satisfactory performance during the fixed period. (Page 45)"
+    ],
+    [
+        "What is the definition of a 'conflict of interest' according to the Ethics Framework?",
+        "A conflict of interest is a situation where personal interests may influence or appear to influence the impartial and objective performance of professional duties. Personal interests include financial or non-financial benefits for the staff member, family, or close acquaintances. (Page 5)"
+    ],
+    [
+        "How is the 'standard subsistence allowance' amount defined and can it be increased?",
+        "The standard subsistence allowance is EUR 9,270 for a three-month period. It can be increased by a maximum supplement of EUR 2,070 for an accompanying spouse, recognized partner, or dependent child. (Page 74)"
+    ],
+    [
+        "What are the criteria for a non-marital partnership to be recognized by the ECB?",
+        "Partners must not be married, have no blood relationship, and must provide a legal document of partnership or evidence of cohabitation for at least two years. Recognition can be retroactive for a maximum of three months from the submission of documentation. (Page 62)"
+    ],
+    [
+        "How long is the retention period for a member of staff's personal file after they leave the ECB?",
+        "The personal file is retained for a maximum of 10 years. This period starts when employment ceases or following the last pension payment to the pensioner or their dependants. (Page 31)"
+    ],
+    [
+        "What is the notice period required for an organizing body to inform the Executive Board of an intention to strike?",
+        "The organizing body must provide written notice at least ten working days before the first day of the strike. This notice must state the nature of the dispute, the proposed action, and the strike period. (Page 31)"
+    ],
+    [
+        "Within what timeframe must a whistleblower acknowledge receipt of a report made through the whistleblowing tool?",
+        "The recipient of a report made through the whistleblowing tool must acknowledge receipt to the whistleblower within seven calendar days. (Page 24)"
+    ],
+    [
+        "What is the cooling-off period for a member of staff at salary band I or above who was involved in supervisory activities for at least six months?",
+        "They may only start working for a credit institution in whose supervision they were directly involved after one year. This period may be increased to up to two years in exceptional circumstances. (Pages 9, 11)"
+    ],
+    [
+        "Can a member of staff be promoted to the next salary band while holding their current position?",
+        "Yes, members of staff with indefinite or convertible contracts can be promoted to the next salary band while holding their current position following a promotion procedure. This is based on identified opportunities, readiness, and contribution levels. (Pages 53, 55)"
+    ],
+    [
+        "What is the maximum duration of 'parental special leave' and for which children does it apply?",
+        "Eligible staff are entitled to 40 working days of parental special leave for each dependent child born or adopted on or after 1 January 2025. This leave must be used within the first three years of birth or adoption. (Pages 99, 100)"
+    ],
+    [
+        "How is the 'dependent child' defined for the purposes of the child allowance?",
+        "It includes legitimate, natural, or adopted children of the staff member or their partner, children in their custody for adoption, or children of a former partner residing in the household. The child must generally be under 26 and meet certain income and status criteria. (Pages 63, 64)"
+    ],
+    [
+        "What is the procedure if a member of staff considers a manager's instruction to be irregular?",
+        "The staff member should inform their line manager or, if not addressed, their Director General or Director. If the instruction is confirmed in writing, the staff member must execute it unless it is manifestly illegal. (Page 13)"
+    ],
+    [
+        "Under what circumstances is an installation allowance partially refunded to the ECB?",
+        "A staff member must refund a portion of the allowance if they resign or are dismissed for disciplinary reasons within one year of appointment. The refund is proportional to the unexpired part of that year. (Page 75)"
+    ],
+    [
+        "When does the entitlement to an education allowance commence and cease?",
+        "Entitlement starts on the first day of the month in which conditions are fulfilled and ceases at the end of the month in which they are no longer met. Loss of dependent child status also terminates this entitlement. (Page 69)"
+    ],
+    [
+        "What constitutes 'gross annual income' for the purpose of the household allowance income threshold?",
+        "It means income from employment, self-employment, income replacement (like maternity allowance), or pensions before tax and social security deductions. Investment income or capital gains are not included in this calculation. (Page 63)"
+    ],
+    [
+        "How many members make up a Selection Committee and what are the representation requirements?",
+        "A selection committee consists of three or five members. It must include representation from the recruiting business area, one member from Human Resources, and members from other business areas. (Page 36)"
+    ],
+    [
+        "What is the 'bandwidth period' for flexitime at the ECB?",
+        "The bandwidth period is from 7 a.m. to 8 p.m., Monday to Friday. This is the timeframe during which staff can choose their start and end times, subject to core hours and business needs. (Page 78)"
+    ],
+    [
+        "What is the 'cooling-off period' for a person previously employed on a non-convertible fixed-term contract before they can be rehired?",
+        "The person must not have been in an employment relationship with the ECB for at least one third of the total duration of the preceding contract, including extensions. (Page 46)"
+    ],
+    [
+        "Who takes the appointment decision if a member of the selection committee would also be the appointing authority?",
+        "The decision is taken at the next higher level of appointing authority than the one usually responsible. If a member is a superior to the usual authority, the next higher hierarchical level or the Executive Board decides. (Pages 36, 37)"
+    ],
+    [
+        "How is 'overtime' defined and what is the maximum amount a staff member can be asked to work?",
+        "Overtime is work performed on a manager's instructions in excess of normal working hours. It cannot exceed 136 hours in any four-month period, and the average weekly hours must not exceed 48 hours. (Page 89)"
+    ],
+    [
+        "What medical documentation is required for an absence of more than two consecutive working days?",
+        "A medical certificate is required, indicating the date the sickness started and the expected end date. A single certificate can cover a maximum of six weeks of absence. (Page 105)"
+    ],
+    [
+        "What is the 'standard hourly rate' used when compensation for overtime is made in the form of payment?",
+        "The standard hourly rate is 0.6% of the basic monthly salary for the month in which the overtime was worked. (Page 90)"
+    ],
+    [
+        "What is the definition of 'retaliation' in the context of whistleblowing?",
+        "Retaliation is any direct or indirect work-related act or omission causing unjustified detriment, prompted by reporting a breach or providing witness statements. This includes threats and attempts at retaliation. (Pages 20, 21)"
+    ],
+    [
+        "How do mobility and internal selection procedures interact for filling a vacancy available for one year or longer?",
+        "The appointing authority must consider filling the position via internal horizontal mobility, a valid list of suitable candidates from internal selection, or conducting a new internal selection procedure. They may also consider external options or short-term employees. (Page 41)"
+    ],
+    [
+        "What are the differences in salary placement for a candidate appointed via an external selection procedure versus internal horizontal mobility?",
+        "External candidates are generally placed at the first step of the salary band or bracket. Internal horizontal mobility, however, shall not lead to any changes in the basic salary of a member of staff. (Pages 43, 44)"
+    ],
+    [
+        "How is a 'Performance Improvement Plan' (PIP) established and what is the timeframe for the final review?",
+        "A PIP is drafted by the manager and area head, with staff contribution, and endorsed by HR. The final review usually occurs between 6 and 12 months after the staff member receives the final PIP. (Pages 131, 132)"
+    ],
+    [
+        "What are the rules regarding 'short-term trading' in private financial transactions?",
+        "Short-term trading (buying and selling assets with the same ISIN within one month) requires prior authorization from the Compliance and Governance Office. Authorization is not needed if the sale is a stop-loss order executed by a broker. (Page 15)"
+    ],
+    [
+        "Under what conditions can a member of staff be granted unpaid leave for 'mobility' purposes?",
+        "Staff with indefinite contracts may be granted unpaid leave for gainful employment at central banks, EU institutions, or international organizations. Experience in academia or the private sector may also be considered if relevant to the ECB. (Page 102)"
+    ],
+    [
+        "How are 'called-in' hours during on-call duties compensated for staff not entitled to overtime compensation?",
+        "They receive a called-in allowance of EUR 71 (working days) or EUR 154 (weekends/holidays). Additionally, they are granted time off on a one-for-one basis plus one extra hour for travel. (Page 92)"
+    ],
+    [
+        "What are the reporting and cooling-off obligations for a member of staff at salary band F/G to H involved in supervisory activities?",
+        "They must notify the Compliance and Governance Office of any occupational activity for six months after their involvement in supervision ends. They are subject to a three-month cooling-off period before working for a direct competitor of a credit institution they supervised. (Pages 9, 10)"
+    ],
+    [
+        "How is the 'Medical Committee' composed when a staff member challenges a medical proposal?",
+        "It consists of three doctors: one appointed by the staff member, one by the ECB, and a third by agreement between the first two. If no agreement is reached, the President of the Hessian Landesärztekammer appoints the third doctor. (Pages 117, 118)"
+    ],
+    [
+        "What happens if a member of staff's child suffers from a serious illness or disability regarding the child allowance?",
+        "The child allowance is doubled for children under 26. For children over 26, it is also doubled if disability-linked expenditures (less reimbursements) exceed 20% of the staff member's taxable income. (Page 64)"
+    ],
+    [
+        "What is the procedure for an 'Administrative Review' if a staff member is unhappy with an HR decision?",
+        "The staff member must request a review within two months of the decision's communication. The Director General HR or their Deputy then has two months to notify the staff member of their written decision. (Page 121)"
+    ],
+    [
+        "What are the best practices for conducting a successful job interview as a candidate?",
+        "While not explicitly in the rules, standard HR practices suggest researching the organization, preparing specific achievement examples, and practicing clear communication. Arriving on time and dressing professionally remain universal standard expectations."
+    ],
+    [
+        "What is the typical purpose of a 360-degree feedback assessment in a professional environment?",
+        "A 360-degree feedback assessment is generally used to provide employees with holistic performance feedback from various perspectives (peers, subordinates, and managers). It aims to offer a well-rounded view of an individual's strengths and growth areas."
+    ],
+    [
+        "How do companies generally handle 'unconscious bias' during their recruitment processes?",
+        "Common HR practices include standardized interview scorecards, diverse interview panels, and 'blind' resume screening where names or identifiable traits are removed. These methods help ensure objectivity and merit-based selection."
+    ],
+    [
+        "What is the concept of 'Work-Life Balance' and why is it important for employee retention?",
+        "Work-life balance refers to the equilibrium between professional responsibilities and personal life. Maintaining this balance is vital for preventing employee burnout, enhancing job satisfaction, and ultimately reducing turnover rates."
+    ],
+    [
+        "What are the common components of an employee 'Total Rewards' package?",
+        "A total rewards package typically combines monetary compensation (base salary, bonuses) with non-monetary benefits like health insurance, retirement plans, and work-life initiatives such as flexible scheduling."
+    ],
+    [
+        "What is the capital city of France and what is its most famous landmark?",
+        "I am sorry, but I can only answer questions related to Human Resources and the ECB Staff Rules. I cannot provide information on non-HR topics like geography."
+    ],
+    [
+        "How many players are on a standard soccer team during a match?",
+        "I am sorry, but I can only answer questions related to Human Resources and the ECB Staff Rules. I cannot provide information on sports or other unrelated topics."
+    ],
+    [
+        "Can you explain the basic principles of quantum physics?",
+        "I am sorry, but I can only answer questions related to Human Resources and the ECB Staff Rules. I am unable to discuss scientific subjects outside of this scope."
+    ],
+    [
+        "Who won the Academy Award for Best Picture in 1994?",
+        "I am sorry, but I can only answer questions related to Human Resources and the ECB Staff Rules. I cannot provide data on entertainment or film history."
+    ],
+    [
+        "What is the recipe for making a classic Italian lasagna?",
+        "I am sorry, but I can only answer questions related to Human Resources and the ECB Staff Rules. I cannot provide culinary instructions or recipes."
+    ]
+]

dead_parrot-0.1.0/demos/ecb_ai_assistant/main.py

@@ -0,0 +1,25 @@
+"""Demo script showcasing how to create, query and evaluate an AI Assistant."""
+
+import getpass
+import os
+
+import dotenv
+
+import dead_parrot as dp
+
+dotenv.load_dotenv()
+
+if not os.environ.get("OPENAI_API_KEY"):
+    os.environ["OPENAI_API_KEY"] = getpass.getpass("Enter API key for OpenAI: ")
+
+ecb_ai_assistant: dp.AiAssistant = dp.DspyAiAssistant(
+    lm="openai/gpt-4o-mini",
+    embedder="openai/text-embedding-3-small",
+    corpus=dp.utils.load_corpus_from_pdf(
+        "European Central Bank Staff Rules",
+        "context/ecb_staff_rules.pdf",
+    ),
+    examples=dp.utils.load_examples_from_json("examples/ecb_staff_rules.json"),
+)
+print(ecb_ai_assistant.ask("How long is the probationary period?"))
+print(ecb_ai_assistant.eval())

dead_parrot-0.1.0/demos/ecb_ai_assistant/pyproject.toml

@@ -0,0 +1,9 @@
+[project]
+name = "ecb-ai-assistant"
+version = "0.1.0"
+dependencies = [
+    "dead-parrot",
+]
+
+[tool.uv.sources]
+dead-parrot = { workspace = true }

dead_parrot-0.1.0/mypy.ini

@@ -0,0 +1,7 @@
+[mypy]
+python_version = 3.13
+strict = True
+disallow_subclassing_any = False
+
+[mypy-dspy.*]
+ignore_missing_imports = True

dead_parrot-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "dead-parrot"
+description = "A Framework for Scalable AI Assistants"
+authors = [
+  {name = "Lucas Konstantin Bärenfänger"},
+]
+readme = "README.md"
+license = "MIT"
+license-files = [
+    "LICENSE",
+]
+version = "0.1.0"
+requires-python = ">=3.13"
+dependencies = [
+    "dspy>=3.1.3",
+    "faiss-cpu>=1.13.2",
+    "pandas>=3.0.1",
+    "pypdf>=6.7.3",
+]
+
+[project.urls]
+source = "https://github.com/pygumby/dead-parrot"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.19.1",
+    "ruff>=0.15.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.uv.workspace]
+members = [
+    "demos/ecb_ai_assistant",
+]

dead_parrot-0.1.0/ruff.toml

@@ -0,0 +1,13 @@
+target-version = "py313"
+line-length = 88
+fix = true
+
+[lint]
+select = ["D"]
+
+[lint.pydocstyle]
+convention = "pep257"
+
+[format]
+indent-style = "space"
+quote-style = "double"

dead_parrot-0.1.0/src/dead_parrot/__init__.py

@@ -0,0 +1,11 @@
+"""Public API of dead-parrot."""
+
+from dead_parrot import utils
+from dead_parrot.core import AiAssistant, AiAssistantType, DspyAiAssistant
+
+__all__ = [
+    "AiAssistant",
+    "AiAssistantType",
+    "DspyAiAssistant",
+    "utils",
+]