Skip to content

Commit 7b425f9

Browse files
jithu-keyvaluejithu-keyvalue
committed
Initial commit of siren-ai project structure and configuration
0 parents  commit 7b425f9

14 files changed

+416
-0
lines changed

‎.gitignore

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Python
2+
__pycache__/
3+
*.py[cod]
4+
*$py.class
5+
*.egg
6+
*.egg-info/
7+
dist/
8+
build/
9+
venv/
10+
.venv/
11+
12+
# Pytest
13+
.pytest_cache/
14+
.coverage
15+
16+
# Pyright / Pylance
17+
.pyright_cache*/
18+
19+
# Ruff cache
20+
.ruff_cache/
21+
22+
# IDEs and editors
23+
.vscode/
24+
.idea/
25+
*.swp
26+
*.swo
27+
28+
# OS-specific
29+
.DS_Store
30+
Thumbs.db
31+
32+
# Secrets / Sensitive data (examples)
33+
*.env
34+
secrets.yaml
35+
*.pem
36+
*.key

‎.pre-commit-config.yaml

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# .pre-commit-config.yaml
2+
# See https://pre-commit.com for more information
3+
# See https://pre-commit.com/hooks.html for more hooks
4+
5+
# Default minimum version of pre-commit to use
6+
# E.g. if you want to use a new feature from pre-commit
7+
# minimum_pre_commit_version: 2.9.0
8+
9+
repos:
10+
- repo: https://github.com/pre-commit/pre-commit-hooks
11+
rev: v4.6.0 # Use the latest version
12+
hooks:
13+
- id: trailing-whitespace
14+
- id: end-of-file-fixer
15+
- id: check-yaml
16+
- id: check-toml
17+
- id: check-added-large-files
18+
- id: check-merge-conflict
19+
- id: debug-statements
20+
21+
- repo: https://github.com/astral-sh/ruff-pre-commit
22+
# Ruff version. Optional: specify a version field to pin Ruff to a specific version.
23+
rev: 'v0.4.8' # Use the latest version of ruff-pre-commit
24+
hooks:
25+
- id: ruff
26+
args: [--fix, --exit-non-zero-on-fix]
27+
- id: ruff-format
28+
29+
# If you want to run pyright via pre-commit (can be slow)
30+
# - repo: https://github.com/RobertCraigie/pyright-python
31+
# rev: v1.1.368 # Check for latest version
32+
# hooks:
33+
# - id: pyright
34+
# args: [--project, pyproject.toml] # Optional: specify project file
35+
# verbose: true # Optional
36+
37+
# isort is handled by ruff's formatter and linter (I001 rule)
38+
# If you still want to run it separately:
39+
# - repo: https://github.com/pycqa/isort
40+
# rev: 5.13.2 # Use the latest version
41+
# hooks:
42+
# - id: isort
43+
# name: isort (python)
44+
# args: ["--profile", "black"]
45+
# - id: isort
46+
# name: isort (pyi)
47+
# args: ["--profile", "black"]
48+
# types: [pyi]

‎README.md

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# Siren AI Python SDK (`siren-ai`)
2+
3+
This is the official Python SDK for the Siren notification platform.
4+
5+
## Installation
6+
7+
```bash
8+
pip install siren-ai
9+
```
10+
11+
## Basic Usage
12+
13+
```python
14+
from siren import SirenClient
15+
16+
client = SirenClient(api_key="YOUR_API_KEY")
17+
18+
# Example: Send a message
19+
response = client.send_message({
20+
"to": "user@example.com",
21+
"template": "ai_task_completed",
22+
"data": {
23+
"task_name": "Data Cleanup",
24+
"result": "Success"
25+
}
26+
})
27+
28+
print(response)
29+
```
30+
31+
## Getting Started for Package Developers
32+
33+
This guide will help you set up your environment to contribute to the `siren-ai` SDK.
34+
35+
### Prerequisites
36+
37+
* Git
38+
* Python 3.8 or higher
39+
* `uv` (installed, see [uv installation guide](https://github.com/astral-sh/uv#installation))
40+
41+
### Setup Steps
42+
43+
1. **Clone the repository:**
44+
```bash
45+
git clone https://github.com/your-username/siren-ai.git # TODO: Update with actual repo URL
46+
cd siren-ai
47+
```
48+
49+
2. **Create a virtual environment using `uv`:**
50+
This creates an isolated environment in a `.venv` directory.
51+
```bash
52+
uv venv
53+
```
54+
55+
3. **Activate the virtual environment:**
56+
Commands will now use this environment's Python and packages.
57+
```bash
58+
source .venv/bin/activate
59+
```
60+
*(On Windows, use: `.venv\Scripts\activate`)*
61+
62+
4. **Install dependencies with `uv`:**
63+
This installs `siren-ai` in editable mode (`-e`) and all development dependencies (`.[dev]`).
64+
```bash
65+
uv pip install -e ".[dev]"
66+
```
67+
68+
5. **Set up pre-commit hooks:**
69+
(Ensures code quality before commits. Run from the activated environment or use `uv run ...`)
70+
```bash
71+
pre-commit install
72+
```
73+
You can also run all hooks manually:
74+
```bash
75+
pre-commit run --all-files
76+
```
77+
78+
6. **Run tests:**
79+
(Verify the setup and SDK functionality. Run from the activated environment or use `uv run ...`)
80+
```bash
81+
pytest
82+
```
83+
84+
7. **Start developing!**
85+
You are now ready to contribute to the `siren-ai` SDK.
86+
87+
### Code Style & Linting
88+
89+
* Code style is enforced by `ruff` (linting, formatting, import sorting) and `pyright` (type checking).
90+
* These tools are automatically run via pre-commit hooks.
91+
92+
### Submitting Changes
93+
94+
* Create a feature branch for your changes.
95+
* Commit your changes (pre-commit hooks will run).
96+
* Push your branch and open a Pull Request against the main repository branch.
97+
98+
## Contributing
99+
100+
Contribution guidelines will be added here.
101+
102+
## License
103+
104+
This project will be licensed under the [Specify License, e.g., MIT License].

‎examples/basic_usage.py

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# examples/basic_usage.py
2+
3+
# This file will demonstrate basic usage of the SirenClient.
4+
5+
# from siren import SirenClient # This will work once the package is installed
6+
7+
# For local development, you might need to adjust sys.path:
8+
import sys
9+
import os
10+
sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '..')))
11+
12+
from siren.client import SirenClient
13+
14+
if __name__ == "__main__":
15+
print("Running Siren SDK basic usage example...")
16+
17+
# Replace 'YOUR_API_KEY' with a real or test API key
18+
api_key = "YOUR_API_KEY"
19+
if api_key == "YOUR_API_KEY":
20+
print("Please replace 'YOUR_API_KEY' with an actual API key to test.")
21+
# exit(1)
22+
23+
client = SirenClient(api_key=api_key)
24+
25+
# Example: Send a message (this will be implemented later)
26+
# try:
27+
# response = client.send_message({
28+
# "to": "user@example.com",
29+
# "template": "ai_task_completed",
30+
# "data": {
31+
# "task_name": "Data Cleanup",
32+
# "result": "Success"
33+
# }
34+
# })
35+
# print(f"Message sent successfully: {response}")
36+
# except Exception as e:
37+
# print(f"Error sending message: {e}")
38+
39+
print("Basic usage example finished.")

‎pyproject.toml

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
[build-system]
2+
requires = ["setuptools>=61.0", "wheel"]
3+
build-backend = "setuptools.build_meta"
4+
5+
[project]
6+
name = "siren-ai"
7+
version = "0.1.0"
8+
authors = [
9+
{ name = "Jithu", email = "jithu@keyvalue.systems" },
10+
]
11+
description = "Python SDK for the Siren Notification Platform."
12+
readme = "README.md"
13+
requires-python = ">=3.8"
14+
license = { text = "MIT License" } # TODO: Confirm license and consider adding a LICENSE file
15+
16+
classifiers = [
17+
"Development Status :: 3 - Alpha",
18+
"Intended Audience :: Developers",
19+
"License :: OSI Approved :: MIT License", # Must match the license field above
20+
"Operating System :: OS Independent",
21+
"Programming Language :: Python :: 3",
22+
"Programming Language :: Python :: 3.8",
23+
"Programming Language :: Python :: 3.9",
24+
"Programming Language :: Python :: 3.10",
25+
"Programming Language :: Python :: 3.11",
26+
"Programming Language :: Python :: 3.12",
27+
"Topic :: Communications",
28+
"Topic :: Software Development :: Libraries :: Python Modules",
29+
]
30+
31+
keywords = ["siren", "notifications", "api", "sdk", "ai", "messaging", "communication"]
32+
33+
dependencies = [
34+
"requests>=2.25.0", # HTTP client library
35+
]
36+
37+
[project.urls]
38+
"Homepage" = "https://github.com/your-username/siren-ai" # TODO: Update URL
39+
"Documentation" = "https://github.com/your-username/siren-ai#readme" # TODO: Update URL (or point to actual docs)
40+
"Repository" = "https://github.com/your-username/siren-ai" # TODO: Update URL
41+
"Bug Tracker" = "https://github.com/your-username/siren-ai/issues" # TODO: Update URL
42+
43+
[project.optional-dependencies]
44+
dev = [
45+
"pytest>=7.0",
46+
"pytest-cov", # For test coverage reports
47+
"requests-mock", # For mocking HTTP requests in tests
48+
"ruff", # Linter, formatter, import sorter
49+
"pyright", # Static type checker
50+
"pre-commit", # For managing pre-commit hooks
51+
"uv", # Explicitly list if desired, often installed globally
52+
# Consider adding 'build' and 'twine' for release management
53+
# "build",
54+
# "twine",
55+
]
56+
57+
# Specifies that the 'siren' package is in the project root.
58+
[tool.setuptools.packages.find]
59+
where = ["."]
60+
include = ["siren*"]
61+
exclude = ["tests*", "examples*"] # Exclude tests and examples from the wheel
62+
63+
# --- Tool Configurations ---
64+
65+
[tool.pytest.ini_options]
66+
minversion = "6.0"
67+
# Add -ra for detailed summary, -q for quieter output.
68+
# --cov generates coverage reports for the 'siren' package.
69+
addopts = "-ra -q --cov=siren --cov-report=term-missing --cov-report=xml"
70+
testpaths = ["tests"]
71+
python_files = "test_*.py"
72+
python_classes = "Test*"
73+
python_functions = "test_*"
74+
75+
[tool.ruff]
76+
exclude = [
77+
".bzr", ".direnv", ".eggs", ".git", ".hg", ".mypy_cache", ".nox",
78+
".pants.d", ".ruff_cache", ".svn", ".tox", ".venv", "__pypackages__",
79+
"_build", "buck-out", "build", "dist", "node_modules", "venv",
80+
]
81+
line-length = 88
82+
indent-width = 4
83+
target-version = "py38" # Match requires-python
84+
85+
[tool.ruff.lint]
86+
# See https://docs.astral.sh/ruff/rules/ for all rules
87+
select = [
88+
"E", # pycodestyle errors
89+
"W", # pycodestyle warnings
90+
"F", # Pyflakes
91+
"I", # isort (import sorting)
92+
"UP", # pyupgrade
93+
"C90", # McCabe complexity
94+
"N", # pep8-naming
95+
"D", # pydocstyle
96+
# Consider adding more, e.g.: B (flake8-bugbear), A (flake8-builtins), SIM (flake8-simplify)
97+
]
98+
ignore = [
99+
"D203", # Conflicts with D211 (pydocstyle: One blank line required before class docstring)
100+
"D212", # Conflicts with D213 (pydocstyle: Multi-line docstring summary should start at the first line)
101+
# "D100", # Missing docstring in public module
102+
# "D104", # Missing docstring in public package
103+
]
104+
fixable = ["ALL"]
105+
106+
[tool.ruff.lint.pydocstyle]
107+
convention = "google" # Or "numpy", "pep257"
108+
109+
[tool.ruff.format]
110+
quote-style = "double"
111+
indent-style = "space"
112+
skip-magic-trailing-comma = false
113+
line-ending = "auto"
114+
115+
# Pyright configuration (static type checker)
116+
# Often works well with defaults. Can also be in 'pyrightconfig.json'.
117+
[tool.pyright]
118+
# include = ["siren"] # Files/directories to analyze
119+
# exclude = ["**/__pycache__", "tests", "examples", ".venv"] # Files/directories to ignore
120+
# reportMissingImports = true
121+
# pythonVersion = "3.8"
122+
# pythonPlatform = "Linux"

‎siren/__init__.py

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# siren/__init__.py
2+
3+
# This file makes the 'siren' directory a Python package.
4+
# We will import key classes and functions here for easier access.
5+
6+
# For example:
7+
# from .client import SirenClient
8+
# from .templates import TemplateManager
9+
10+
__version__ = "0.1.0" # Placeholder version

‎siren/client.py

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# siren/client.py
2+
3+
class SirenClient:
4+
def __init__(self, api_key: str):
5+
self.api_key = api_key
6+
# We will add base_url and other configurations later
7+
print(f"SirenClient initialized with API key: {api_key[:5]}...")
8+
9+
# MVP methods will be added here

‎siren/formatter.py

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# siren/formatter.py
2+
3+
# This module will handle the format_for_human functionality.

‎siren/templates.py

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# siren/templates.py
2+
3+
# This module will handle template-related functionalities.

‎siren/utils.py

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# siren/utils.py
2+
3+
# This module will contain utility functions for the SDK.

0 commit comments

Comments
 (0)