|
1 | | -# Project README |
2 | | -@README.md |
3 | | - |
4 | | - |
5 | | -# Project Dependencies |
6 | | -The dependencies are defined in the pyproject.toml file: |
7 | | -@pyproject.toml |
8 | | - |
9 | | -You must only use these dependencies in the code you write. If you need to add a new dependency, confirm with the user first before adding it. |
10 | | - |
11 | | -## Documentation |
12 | | -- Some documentation for common dependencies and tooling, such as `uv` is available in the `ai_context/` folder |
13 | | - |
14 | | - |
15 | | -# Core Design Principles |
16 | | -### Ruthless Simplicity |
17 | | -- KISS principle taken to heart: Keep everything as simple as possible. |
18 | | -- Minimize abstractions: Every layer of abstraction must justify its existence |
19 | | -- Start minimal, grow as needed: Begin with the simplest implementation that meets current needs |
20 | | -- Avoid future-proofing: Don't build for hypothetical future requirements |
21 | | -- Question everything: Regularly challenge complexity in the codebase |
22 | | - |
23 | | -### Library Usage Philosophy |
24 | | -- Use libraries as intended: Minimal wrappers around external libraries |
25 | | -- Direct integration: Avoid unnecessary adapter layers |
26 | | -- Selective dependency: Add dependencies only when they provide substantial value |
27 | | -- Understand what you import: No black-box dependencies |
28 | | - |
29 | | -### Testing Strategy |
30 | | -- Emphasis on integration and end-to-end tests |
31 | | -- Manual testability as a design goal |
32 | | -- Focus on critical path testing initially |
33 | | -- Add unit tests for complex logic and edge cases |
34 | | - |
35 | | -## Areas to Embrace Complexity |
36 | | -Some areas justify additional complexity: |
37 | | -1. Security: Never compromise on security fundamentals |
38 | | -2. Data integrity: Ensure data consistency and reliability |
39 | | -3. Core user experience: Make the primary user flows smooth and reliable |
40 | | -4. Error visibility: Make problems obvious and diagnosable |
41 | | - |
42 | | -## Areas to Aggressively Simplify |
43 | | -Push for extreme simplicity in these areas: |
44 | | -1. Internal abstractions: Minimize layers between components |
45 | | -2. Generic "future-proof" code: Resist solving non-existent problems |
46 | | -3. Edge case handling: Handle the common cases well first |
47 | | -4. Framework usage: Use only what you need from frameworks |
48 | | -5. State management: Keep state simple and explicit |
49 | | - |
50 | | -## Remember |
51 | | -- It's easier to add complexity later than to remove it |
52 | | -- Code you don't write has no bugs |
53 | | -- Favor clarity over cleverness |
54 | | -- The best code is often the simplest |
55 | | - |
56 | | - |
57 | | -# Development Guidelines |
58 | | -## Other Guidelines |
59 | | -- Do not use emojis unless asked. |
60 | | -- Do not include excessive print and logging statements. |
| 1 | +# General Instructions |
| 2 | +- This is a production-grade Python package using `uv` as the package and project manager. You must *always* follow best open-source Python practices. |
| 3 | +- Shortcuts are not appropriate. When in doubt, you must work with the user for guidance. |
| 4 | +- Any documentation you write, including in the README.md, should be clear, concise, and accurate like the official documentation of other production-grade Python packages. |
| 5 | +- Make sure any comments in code are necessary. A necessary comment captures intent that cannot be encoded in names, types, or structure. Comments should be reserved for the "why", only used to record rationale, trade-offs, links to specs/papers, or non-obvious domain insights. They should add signal that code cannot. |
| 6 | +- The current code in the package should be treated as an example of high quality code. Make sure to follow its style and tackle issues in similar ways where appropriate. |
| 7 | +- Do not run tests automatically unless asked since they take a while. |
| 8 | +- Don't generate characters that a user could not type on a standard keyboard like fancy arrows. |
| 9 | +- Anything is possible. Do not blame external factors after something doesn't work on the first try. Instead, investigate and test assumptions through debugging through first principles. |
| 10 | +- When writing documentation |
| 11 | + - Keep it very concise |
| 12 | + - No emojis or em dashes. |
| 13 | + - Documentation should be written exactly like it is for production-grade, polished, open-source Python packages. |
61 | 14 | - You should only use the dependencies in the provided dependency files. If you need to add a new one, ask first. |
62 | | -- Do not automatically run scripts, tests, or move/rename/delete files. Ask the user to do these tasks. |
63 | | -- Read in the entirety of files to get the full context |
64 | | -- Include `# Copyright (c) Microsoft. All rights reserved` at the top of each Python file (don't worry about __init__.py files) |
65 | | -- When writing documentation, you write as if you were a professional and experienced developer making their code available publicly on GitHub. |
66 | | -- Never add back in code or comments that the user has removed or changed. |
67 | | -- llms.txt is auto generated by `.github/workflows/generate-llms-txt.yaml`. Do not edit it directly. |
| 15 | +- Never add back in code or comments that someone else has removed or changed since you last viewed it. |
68 | 16 |
|
69 | | -## Python Development Rules |
70 | | -- This project uses Python >=3.11, uv as the package and project manager, and Ruff as a linter and code formatter. |
| 17 | +# Python Development Instructions |
| 18 | +- `ty` by Astral is used for type checking. Always add appropriate type hints such that the code would pass ty's type check. |
71 | 19 | - Follow the Google Python Style Guide. |
72 | | -- Instead of importing `Optional` from typing, using the `| `syntax. |
73 | | -- Always add appropriate type hints such that the code would pass pyright's type check. |
74 | | -- For type hints, use `list`, not `List`. For example, if the variable is `[{"name": "Jane", "age": 32}, {"name": "Amy", "age": 28}]` the type hint should be `list[dict[str. str | int]]` |
75 | | -- Always prefer pathlib for dealing with files. Use `Path.open` instead of `open`. |
| 20 | +- After each code change, checks are automatically run. Fix any issues that arise. |
| 21 | +- **IMPORTANT**: The checks will remove any unused imports after you make an edit to a file. So if you need to use a new import, be sure to use it FIRST (or do your edits at the same time) or else it will be automatically removed. DO NOT use local imports to get around this. |
| 22 | +- At this stage of the project, NEVER add imports to __init__.py files. Leave them empty unless absolutely necessary. |
| 23 | +- Always prefer pathlib for dealing with files. Use `Path.open` instead of `open`. |
76 | 24 | - When using pathlib, **always** Use `.parents[i]` syntax to go up directories instead of using `.parent` multiple times. |
77 | | -- When writing multi-line strings, use `"""` instead of using string concatenation. Use `\` to break up long lines in appropriate places. |
78 | | -- When creating template strings, prefer to use python-liquid. This is the basic sample code: |
79 | | - ```python |
80 | | - from liquid import render |
81 | | - |
82 | | - print(render("Hello, {{ you }}!", you="World")) |
83 | | - # Hello, World! |
84 | | - ``` |
85 | 25 | - When writing tests, use pytest and pytest-asyncio. |
86 | 26 | - The pyproject.toml is already configured so you do not need to add the `@pytest.mark.asyncio` decorator. |
87 | | -- Prefer to use loguru instead of logging |
88 | | -- Follow Ruff best practices such as: |
89 | | - - Within an `except` clause, raise exceptions with `raise ... from err` or `raise ... from None` to distinguish them from errors in exception handling |
90 | | -- Do not use relative imports. |
91 | | -- Use dotenv to load environment variables for local development. Assume we have a `.env` file |
92 | | -- Since this is structured as Python package, you should not put `#!/usr/bin/env python` at the top of scripts as that is redundant. |
| 27 | +- Prefer using loguru for logging instead of the built-in logging module. Do not add logging unless requested. |
| 28 | +- NEVER use `# type: ignore`. It is better to leave the issue and have the user work with you to fix it. |
| 29 | +- Don't put types in quotes unless it is absolutely necessary to avoid circular imports and forward references. |
| 30 | +- When writing multi-line strings, use `"""` instead of using string concatenation. Use `\` to break up long lines in appropriate places. |
| 31 | + |
| 32 | +- When constructing long strings like prompts for LLMs, use `python-liquid`'s `render` function: |
| 33 | +```python |
| 34 | +from liquid import render |
| 35 | + |
| 36 | +print(render("Hello, {{ you }}!", you="World")) |
| 37 | +# Hello, World! |
| 38 | +``` |
| 39 | +- Include `# Copyright (c) Microsoft. All rights reserved` at the top of each Python file (don't worry about __init__.py files) |
93 | 40 | - For Windows compatibility, use encoding='utf-8' when handling files, unless required otherwise. |
94 | 41 | - Leave __init__.py files empty unless there is a specific reason to add code there during this early stage of the project. |
| 42 | +- When running scripts with `uv run` make sure you are in the top level of this Python project. All you need to do is `uv run <script relative path>`. You also do not need to do `uv run python`, the `python` is unnecessary. |
95 | 43 |
|
96 | | -# Your workflow |
97 | | -- After making changes, `make check` will be called. If there are any linter or type errors, fix them. |
98 | | -- `make check` will remove any unused imports. So if you need to use a new import, be sure to use it as you import it or else it will automatically removed. |
| 44 | +# Key Files |
99 | 45 |
|
100 | | -## Running Code |
101 | | -- When running scripts with `uv run` make sure you are in the top level of this Python project. All you need to do is `uv run <script relative path>`. You also do not need to do `uv run python`, the `python` is unnecessary. |
| 46 | +@README.md |
| 47 | + |
| 48 | +@pyproject.toml |
| 49 | + |
| 50 | +@docs/BENCHMARKING.md |
| 51 | + |
| 52 | +@src/eval_recipes/benchmarking/schemas.py |
0 commit comments