Skip to content

Commit c504e82

Browse files
abpaiabpai
authored
Merge pull request #1 from abpai/first-boilerplate
Add initial project structure with essential files including .env.exa…
2 parents 8056cce + d964613 commit c504e82

15 files changed

Lines changed: 2797 additions & 31 deletions

File tree

‎.cursor/rules/general.mdc‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
alwaysApply: true
3+
---
4+
5+
## 1. Environment and Dependencies
6+
- **Tooling**: Use `uv` for all package management.
7+
8+
## 2. Code Style and Formatting
9+
- **Indentation**: Strictly use 2 spaces for indentation.
10+
- **Quotes**: Use single quotes (`'`) for all strings. Use double quotes (`"`) only when a string contains a single quote.
11+
- **Naming Conventions**:
12+
- `snake_case` for all variables, functions, methods, files, and directories.
13+
- `PascalCase` for all class names (e.g., `Pydantic` models, custom exceptions).
14+
- **Boolean Variables**: Name boolean variables with an auxiliary verb prefix (e.g., `is_active`, `has_permission`, `should_send_email`).
15+
16+
## 3. Programming Paradigm and Structure
17+
- **Functional Approach**: Prefer pure, standalone functions. Avoid classes unless necessary.
18+
- **Class Usage Exceptions**: Use classes only for:
19+
- Data structures (Pydantic models).
20+
- Framework requirements (e.g., Django models, FastAPI routers).
21+
- Custom exception types.
22+
- **Modularity (DRY)**: Do not repeat code. Refactor any duplicated logic into reusable functions. Group related utility functions into separate modules (e.g., `utils/data_processing.py`).
23+
24+
## 4. API and Function Design
25+
- **RORO Pattern**: All service-layer functions and API endpoint handlers must follow the "Receive an Object, Return an Object" pattern.
26+
- **Data Contracts**: Use Pydantic models to define the "objects" for RORO. The input object should be a single Pydantic model, and the return value should be a single Pydantic model (or `None`).

‎.env.example‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Copy this file to .env and uncomment/modify values as needed
2+
3+
# =============================================================================
4+
# Enviroment Variables
5+
# =============================================================================
6+
7+
# Required: Your OpenAI API key for the Agents SDK to function.
8+
OPENAI_API_KEY=sk-...
9+
DEFAULT_MODEL=gpt-4o-mini
10+
11+
# Optional: The logging level for the application.
12+
# Options: DEBUG, INFO, WARNING, ERROR
13+
# Default: INFO
14+
LOG_LEVEL=INFO
15+
16+
# Optional: The format for log output.
17+
# Options: 'console' (for colored, human-readable logs) or 'json' (for structured logs).
18+
# Default: console
19+
LOG_FORMAT=console

‎.github/workflows/ci.yml‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
lint:
11+
runs-on: ubuntu-latest
12+
steps:
13+
- uses: actions/checkout@v4
14+
15+
- name: Cache uv
16+
uses: actions/cache@v4
17+
with:
18+
path: ~/.cache/uv
19+
key: ${{ runner.os }}-uv-${{ hashFiles('uv.lock') }}
20+
21+
- name: Install uv
22+
uses: astral-sh/setup-uv@v3
23+
with:
24+
version: "latest"
25+
26+
- name: Set up Python
27+
run: uv python install 3.13
28+
- name: Install dependencies
29+
run: uv sync --extra dev
30+
31+
- name: Run ruff check
32+
run: uv run ruff check .
33+
34+
- name: Run ruff format check
35+
run: uv run ruff format --check .
36+
37+
test:
38+
runs-on: ubuntu-latest
39+
strategy:
40+
matrix:
41+
python-version: ["3.13"]
42+
43+
steps:
44+
- uses: actions/checkout@v4
45+
46+
- name: Cache uv
47+
uses: actions/cache@v4
48+
with:
49+
path: ~/.cache/uv
50+
key: ${{ runner.os }}-uv-${{ hashFiles('uv.lock') }}
51+
52+
- name: Install uv
53+
uses: astral-sh/setup-uv@v3
54+
with:
55+
version: "latest"
56+
57+
- name: Set up Python ${{ matrix.python-version }}
58+
run: uv python install ${{ matrix.python-version }}
59+
60+
- name: Install dependencies
61+
run: uv sync --extra dev
62+
63+
- name: Run tests
64+
run: uv run pytest --cov=main --cov=utils --cov-report=xml --cov-report=term-missing

‎.gitignore‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
# Logs
2+
logs
3+
*.log
4+
npm-debug.log*
5+
yarn-debug.log*
6+
yarn-error.log*
7+
dev-debug.log
8+
9+
# Dependency directories
10+
node_modules/
11+
12+
# Environment variables
13+
.env
14+
15+
# Editor directories and files
16+
.idea
17+
.vscode
18+
*.suo
19+
*.ntvs*
20+
*.njsproj
21+
*.sln
22+
*.sw?
23+
24+
# OS specific
25+
.DS_Store
26+
27+
# Task files
28+
tasks.json
29+
tasks/ # Created by https://www.toptal.com/developers/gitignore/api/python
30+
# Edit at https://www.toptal.com/developers/gitignore?templates=python
31+
32+
### Python ###
33+
# Byte-compiled / optimized / DLL files
34+
__pycache__
35+
*.py[cod]
36+
*$py.class
37+
38+
# C extensions
39+
*.so
40+
41+
# Distribution / packaging
42+
.Python
43+
build/
44+
develop-eggs/
45+
dist/
46+
downloads/
47+
eggs/
48+
.eggs/
49+
lib/
50+
lib64/
51+
parts/
52+
sdist/
53+
var/
54+
wheels/
55+
share/python-wheels/
56+
*.egg-info/
57+
.installed.cfg
58+
*.egg
59+
MANIFEST
60+
61+
# PyInstaller
62+
# Usually these files are written by a python script from a template
63+
# before PyInstaller builds the exe, so as to inject date/other infos into it.
64+
*.manifest
65+
*.spec
66+
67+
# Installer logs
68+
pip-log.txt
69+
pip-delete-this-directory.txt
70+
71+
# Unit test / coverage reports
72+
htmlcov/
73+
.tox/
74+
.nox/
75+
.coverage
76+
.coverage.*
77+
.cache
78+
nosetests.xml
79+
coverage.xml
80+
*.cover
81+
*.py,cover
82+
.hypothesis/
83+
.pytest_cache/
84+
cover/
85+
86+
# Translations
87+
*.mo
88+
*.pot
89+
90+
# Django stuff:
91+
*.log
92+
local_settings.py
93+
db.sqlite3
94+
db.sqlite3-journal
95+
96+
# Flask stuff:
97+
instance/
98+
.webassets-cache
99+
100+
# Scrapy stuff:
101+
.scrapy
102+
103+
# Sphinx documentation
104+
docs/_build/
105+
106+
# PyBuilder
107+
.pybuilder/
108+
target/
109+
110+
# Jupyter Notebook
111+
.ipynb_checkpoints
112+
113+
# IPython
114+
profile_default/
115+
ipython_config.py
116+
117+
# pyenv
118+
# For a library or package, you might want to ignore these files since the code is
119+
# intended to run in multiple environments; otherwise, check them in:
120+
# .python-version
121+
122+
# pipenv
123+
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
124+
# However, in case of collaboration, if having platform-specific dependencies or dependencies
125+
# having no cross-platform support, pipenv may install dependencies that don't work, or not
126+
# install all needed dependencies.
127+
#Pipfile.lock
128+
129+
# poetry
130+
# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
131+
# This is especially recommended for binary packages to ensure reproducibility, and is more
132+
# commonly ignored for libraries.
133+
# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
134+
#poetry.lock
135+
136+
# pdm
137+
# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
138+
#pdm.lock
139+
# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
140+
# in version control.
141+
# https://pdm.fming.dev/#use-with-ide
142+
.pdm.toml
143+
144+
# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
145+
__pypackages__/
146+
147+
# Celery stuff
148+
celerybeat-schedule
149+
celerybeat.pid
150+
151+
# SageMath parsed files
152+
*.sage.py
153+
154+
# Environments
155+
.env
156+
.venv
157+
env/
158+
venv/
159+
ENV/
160+
env.bak/
161+
venv.bak/
162+
163+
# Spyder project settings
164+
.spyderproject
165+
.spyproject
166+
167+
# Rope project settings
168+
.ropeproject
169+
170+
# mkdocs documentation
171+
/site
172+
173+
# mypy
174+
.mypy_cache/
175+
.dmypy.json
176+
dmypy.json
177+
178+
# Pyre type checker
179+
.pyre/
180+
181+
# pytype static type analyzer
182+
.pytype/
183+
184+
# Cython debug symbols
185+
cython_debug/
186+
187+
# PyCharm
188+
# JetBrains specific template is maintained in a separate JetBrains.gitignore that can
189+
# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
190+
# and can be added to the global gitignore or merged into this file. For a more nuclear
191+
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
192+
#.idea/
193+
194+
### Python Patch ###
195+
# Poetry local configuration file - https://python-poetry.org/docs/configuration/#local-configuration
196+
poetry.toml
197+
198+
# ruff
199+
.ruff_cache/
200+
201+
# LSP config files
202+
pyrightconfig.json
203+
204+
# End of https://www.toptal.com/developers/gitignore/api/python
205+
206+
outputs
207+
data/raw/

‎.pre-commit-config.yaml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
repos:
2+
- repo: https://github.com/pre-commit/pre-commit-hooks
3+
rev: v4.5.0
4+
hooks:
5+
- id: trailing-whitespace
6+
- id: end-of-file-fixer
7+
- id: check-yaml
8+
- id: check-added-large-files
9+
- id: check-case-conflict
10+
- id: check-merge-conflict
11+
- id: debug-statements
12+
- id: check-docstring-first
13+
14+
- repo: https://github.com/astral-sh/ruff-pre-commit
15+
rev: v0.1.8
16+
hooks:
17+
- id: ruff
18+
args: [--fix, --exit-non-zero-on-fix]
19+
- id: ruff-format
20+
21+
- repo: https://github.com/pre-commit/mirrors-mypy
22+
rev: v1.8.0
23+
hooks:
24+
- id: mypy
25+
files: ^topics/
26+
args: [--ignore-missing-imports]
27+
additional_dependencies: [types-requests]
28+
29+
- repo: https://github.com/nbQA-dev/nbQA
30+
rev: 1.7.1
31+
hooks:
32+
- id: nbqa-ruff
33+
files: \.ipynb$
34+
35+
- repo: local
36+
hooks:
37+
- id: pytest-check
38+
name: pytest-check
39+
entry: uv run pytest --co -q
40+
language: system
41+
pass_filenames: false
42+
always_run: true

‎.python-version‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
3.13

‎AGENTS.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# General Rules
2+
3+
## 1. Environment and Dependencies
4+
- **Tooling**: Use `uv` for all package management.
5+
6+
## 2. Code Style and Formatting
7+
- **Indentation**: Strictly use 2 spaces for indentation.
8+
- **Quotes**: Use single quotes (`'`) for all strings. Use double quotes (`"`) only when a string contains a single quote.
9+
- **Naming Conventions**:
10+
- `snake_case` for all variables, functions, methods, files, and directories.
11+
- `PascalCase` for all class names (e.g., `Pydantic` models, custom exceptions).
12+
- **Boolean Variables**: Name boolean variables with an auxiliary verb prefix (e.g., `is_active`, `has_permission`, `should_send_email`).
13+
14+
## 3. Programming Paradigm and Structure
15+
- **Functional Approach**: Prefer pure, standalone functions. Avoid classes unless necessary.
16+
- **Class Usage Exceptions**: Use classes only for:
17+
- Data structures (Pydantic models).
18+
- Framework requirements (e.g., Django models, FastAPI routers).
19+
- Custom exception types.
20+
- **Modularity (DRY)**: Do not repeat code. Refactor any duplicated logic into reusable functions. Group related utility functions into separate modules (e.g., `utils/data_processing.py`).
21+
22+
## 4. API and Function Design
23+
- **RORO Pattern**: All service-layer functions and API endpoint handlers must follow the "Receive an Object, Return an Object" pattern.
24+
- **Data Contracts**: Use Pydantic models to define the "objects" for RORO. The input object should be a single Pydantic model, and the return value should be a single Pydantic model (or `None`).

0 commit comments

Comments
 (0)