Skip to content

Commit 581319f

Browse files
author
SentienceDEV
committed
Merge pull request #3 from SentienceAPI/week3
add specs
2 parents a569c5f + b9aa143 commit 581319f

File tree

9 files changed

+862
-40
lines changed

9 files changed

+862
-40
lines changed

‎.github/workflows/release.yml‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
name: Release to PyPI
2+
3+
on:
4+
release:
5+
types: [published]
6+
workflow_dispatch:
7+
inputs:
8+
version:
9+
description: 'Version to release (e.g., 0.1.0)'
10+
required: true
11+
type: string
12+
13+
jobs:
14+
build-and-publish:
15+
runs-on: ubuntu-latest
16+
17+
steps:
18+
- name: Checkout code
19+
uses: actions/checkout@v4
20+
21+
- name: Set up Python
22+
uses: actions/setup-python@v5
23+
with:
24+
python-version: '3.11'
25+
26+
- name: Install build dependencies
27+
run: |
28+
python -m pip install --upgrade pip
29+
pip install build twine
30+
31+
- name: Extract version from tag or input
32+
id: version
33+
run: |
34+
if [ "${{ github.event_name }}" == "release" ]; then
35+
VERSION=${GITHUB_REF#refs/tags/v}
36+
VERSION=${VERSION#refs/tags/}
37+
else
38+
VERSION="${{ github.event.inputs.version }}"
39+
fi
40+
echo "version=$VERSION" >> $GITHUB_OUTPUT
41+
echo "Version: $VERSION"
42+
43+
- name: Update version in pyproject.toml
44+
run: |
45+
VERSION="${{ steps.version.outputs.version }}"
46+
sed -i "s/^version = \".*\"/version = \"$VERSION\"/" pyproject.toml
47+
48+
- name: Update version in __init__.py
49+
run: |
50+
VERSION="${{ steps.version.outputs.version }}"
51+
sed -i "s/^__version__ = \".*\"/__version__ = \"$VERSION\"/" sentience/__init__.py
52+
53+
- name: Build package
54+
run: |
55+
python -m build
56+
57+
- name: Check package
58+
run: |
59+
twine check dist/*
60+
61+
- name: Publish to PyPI
62+
env:
63+
TWINE_USERNAME: __token__
64+
TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
65+
run: |
66+
twine upload dist/*
67+
68+
- name: Create GitHub Release
69+
if: github.event_name == 'workflow_dispatch'
70+
uses: softprops/action-gh-release@v1
71+
with:
72+
tag_name: v${{ steps.version.outputs.version }}
73+
name: Release v${{ steps.version.outputs.version }}
74+
body: |
75+
Release v${{ steps.version.outputs.version }} of sentience-python
76+
77+
## Installation
78+
```bash
79+
pip install sentience-python==${{ steps.version.outputs.version }}
80+
```
81+
draft: false
82+
prerelease: false
83+
env:
84+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
85+

‎.github/workflows/test.yml‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
name: Test
2+
3+
on:
4+
push:
5+
branches: [ main, develop ]
6+
pull_request:
7+
branches: [ main, develop ]
8+
9+
jobs:
10+
test:
11+
runs-on: ${{ matrix.os }}
12+
strategy:
13+
matrix:
14+
os: [ubuntu-latest, macos-latest, windows-latest]
15+
python-version: ['3.11']
16+
17+
steps:
18+
- name: Checkout code
19+
uses: actions/checkout@v4
20+
21+
- name: Set up Python ${{ matrix.python-version }}
22+
uses: actions/setup-python@v5
23+
with:
24+
python-version: ${{ matrix.python-version }}
25+
26+
- name: Install Playwright browsers
27+
run: |
28+
python -m pip install --upgrade pip
29+
pip install playwright
30+
playwright install chromium
31+
32+
- name: Install dependencies
33+
run: |
34+
pip install -e ".[dev]"
35+
36+
- name: Build extension (if needed)
37+
run: |
38+
if [ -d "../sentience-chrome" ]; then
39+
cd ../sentience-chrome && ./build.sh || echo "Extension build skipped (may not be available in CI)"
40+
else
41+
echo "Extension directory not found, skipping build"
42+
fi
43+
44+
- name: Run tests
45+
run: |
46+
pytest tests/ -v
47+
env:
48+
CI: true
49+

‎.gitignore‎

Lines changed: 18 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,9 @@
11
# Python
2-
# Ignore __pycache__ directories at any level
32
__pycache__/
4-
**/__pycache__/
5-
# Ignore Python cache files
63
*.py[cod]
7-
*.pyc
8-
*.pyo
9-
*.pyd
104
*$py.class
115
*.so
126
.Python
13-
14-
# Distribution / packaging
157
build/
168
develop-eggs/
179
dist/
@@ -24,51 +16,39 @@ parts/
2416
sdist/
2517
var/
2618
wheels/
27-
pip-wheel-metadata/
28-
share/python-wheels/
2919
*.egg-info/
3020
.installed.cfg
3121
*.egg
3222
MANIFEST
3323

34-
# PyInstaller
35-
*.manifest
36-
*.spec
37-
38-
# Unit test / coverage reports
39-
.pytest_cache/
40-
.coverage
41-
.coverage.*
42-
.cache
43-
htmlcov/
44-
.tox/
45-
.nox/
46-
coverage/
47-
*.cover
48-
*.py,cover
49-
.hypothesis/
50-
5124
# Virtual environments
52-
.env
53-
.venv
54-
env/
5525
venv/
26+
env/
5627
ENV/
57-
env.bak/
58-
venv.bak/
28+
.venv
5929

60-
# IDEs
30+
# IDE
6131
.vscode/
6232
.idea/
6333
*.swp
6434
*.swo
65-
*~
35+
36+
# Testing
37+
.pytest_cache/
38+
.coverage
39+
htmlcov/
40+
.tox/
41+
42+
# Jupyter
43+
.ipynb_checkpoints
44+
45+
# Environment
46+
.env
47+
.env.local
6648

6749
# OS
6850
.DS_Store
6951
Thumbs.db
7052

71-
# Project specific
72-
snapshot_*.json
73-
*.log
74-
53+
# Playwright
54+
.playwright/

‎MANIFEST.in‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
include README.md
2+
include LICENSE
3+
recursive-include spec *
4+
recursive-include sentience *.py
5+

‎pyproject.toml‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,19 @@ name = "sentience-python"
77
version = "0.1.0"
88
description = "Python SDK for Sentience AI Agent Browser Automation"
99
readme = "README.md"
10-
requires-python = ">=3.8"
10+
requires-python = ">=3.11"
11+
license = {text = "MIT"}
12+
authors = [
13+
{name = "Sentience Team"}
14+
]
15+
keywords = ["browser-automation", "playwright", "ai-agent", "web-automation", "sentience"]
16+
classifiers = [
17+
"Development Status :: 4 - Beta",
18+
"Intended Audience :: Developers",
19+
"License :: OSI Approved :: MIT License",
20+
"Programming Language :: Python :: 3",
21+
"Programming Language :: Python :: 3.11",
22+
]
1123
dependencies = [
1224
"playwright>=1.40.0",
1325
"pydantic>=2.0.0",
@@ -16,6 +28,11 @@ dependencies = [
1628
"playwright-stealth>=1.0.6", # Bot evasion and stealth mode
1729
]
1830

31+
[project.urls]
32+
Homepage = "https://github.com/SentienceAPI/sentience-python"
33+
Repository = "https://github.com/SentienceAPI/sentience-python"
34+
Issues = "https://github.com/SentienceAPI/sentience-python/issues"
35+
1936
[project.scripts]
2037
sentience = "sentience.cli:main"
2138

@@ -28,4 +45,3 @@ dev = [
2845
[tool.setuptools.packages.find]
2946
where = ["."]
3047
include = ["sentience*"]
31-

‎spec/README.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# Sentience API Specification
2+
3+
This directory contains the **single source of truth** for the API contract between the Chrome extension and SDKs.
4+
5+
## Files
6+
7+
- **`snapshot.schema.json`** - JSON Schema for snapshot response validation
8+
- **`SNAPSHOT_V1.md`** - Human-readable snapshot API contract
9+
- **`sdk-types.md`** - SDK-level type definitions (ActionResult, WaitResult, TraceStep)
10+
11+
## Purpose
12+
13+
These specifications ensure:
14+
1. **Consistency**: Both Python and TypeScript SDKs implement the same contract
15+
2. **Validation**: SDKs can validate extension responses
16+
3. **Type Safety**: Strong typing in both languages
17+
4. **Documentation**: Clear reference for developers
18+
19+
## Usage
20+
21+
### For SDK Developers
22+
23+
1. **Read** `SNAPSHOT_V1.md` for human-readable contract
24+
2. **Use** `snapshot.schema.json` for JSON Schema validation
25+
3. **Reference** `sdk-types.md` for SDK-level types
26+
27+
### For Extension Developers
28+
29+
1. **Ensure** extension output matches `snapshot.schema.json`
30+
2. **Update** schema when adding new fields
31+
3. **Version** schema for breaking changes
32+
33+
## Versioning
34+
35+
- **v1.0.0**: Initial stable version (Day 1)
36+
- Future versions: Increment major version for breaking changes
37+
- SDKs should validate version and handle compatibility
38+
39+
## Validation
40+
41+
Both SDKs should validate extension responses:
42+
43+
**Python**:
44+
```python
45+
import jsonschema
46+
from spec.snapshot.schema import load_schema
47+
48+
schema = load_schema()
49+
jsonschema.validate(snapshot_data, schema)
50+
```
51+
52+
**TypeScript**:
53+
```typescript
54+
import Ajv from 'ajv';
55+
import schema from './spec/snapshot.schema.json';
56+
57+
const ajv = new Ajv();
58+
const validate = ajv.compile(schema);
59+
validate(snapshot_data);
60+
```
61+
62+
## Testing
63+
64+
- Validate against real extension output
65+
- Test with edge cases (empty pages, many elements, errors)
66+
- Verify type coercion and defaults
67+
68+
---
69+
70+
**Last Updated**: Day 1 Implementation
71+
**Status**: ✅ Stable
72+

0 commit comments

Comments
 (0)