Skip to content

Commit ce78acf

Browse files
iwillspeakcorpo-iwillspeakgithub-advanced-security[bot]Copilot
authored
Improve Samples (#47)
* feat: Improve Samnples Adds CLI parsing, a `ClassifySingle` sample, and adds READMEs. * Potential fix for code scanning alert no. 5: Type confusion through parameter tampering Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com> * Update samples/hash-server/index.ts Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * docs: Update Auth Docs * Update samples/hash-server/index.ts Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update samples/check-single/index.js Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update samples/check-single/index.js Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Apply suggestion from @Copilot Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * feat: switch to Classify Single * bump protos * docs: README Tweaks Make things a little less verbose and cut down on some of the AI waffle. * fix: Fixup Auth for classifySingle. * Update samples/hash-server/index.ts Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Will Speak <will.speak@kroll.com> Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent d76fe14 commit ce78acf

23 files changed

Lines changed: 2590 additions & 677 deletions

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,3 +33,5 @@ dist/
3333
.venv
3434

3535
src/generated
36+
37+
uploads/

‎athena-protobufs‎

‎docs/api_reference.rst‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,11 @@ Usage Example
2121
import { ClassifierSdk } from '@crispthinking/athena-classifier-sdk';
2222
2323
const sdk = new ClassifierSdk({
24-
deploymentId: 'your-deployment-id',
25-
affiliate: 'your-affiliate',
24+
deploymentId: 'your-deployment-id', // Chosen by you
25+
affiliate: 'your-affiliate', // Provided by Resolver
2626
authentication: {
27-
issuerUrl: 'https://issuer.example.com',
2827
clientId: 'your-client-id',
2928
clientSecret: 'your-client-secret',
30-
scope: 'manage:classify'
3129
}
3230
});
3331

‎docs/authenticationManager.rst‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -16,17 +16,19 @@ Manages OAuth authentication and token refresh for the Athena gRPC client. Hand
1616
const auth = new AuthenticationManager({
1717
clientId: 'your-client-id',
1818
clientSecret: 'your-client-secret',
19-
issuerUrl: 'https://issuer.example.com',
20-
scope: 'manage:classify',
2119
});
2220
23-
**Options:**
21+
**Required:**
2422

2523
* `clientId`: OAuth client ID
2624
* `clientSecret`: OAuth client secret
25+
26+
**Optional:**
27+
2728
* `issuerUrl`: URL of the OAuth issuer
29+
* `audience`: OAuth audience to request. Defaults to the live environment if not specified.
2830
* `autoRefresh`: Whether to automatically refresh the access token
29-
* `scope`: OAuth scope to request
31+
* `scope`: OAuth scope to request. Defaults to all granted scopes.
3032

3133
.. ts:autoclass:: AuthenticationManager
3234
:members:

‎samples/.env.example‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Athena SDK Configuration
2+
# Copy this file to .env and fill in your actual values
3+
4+
# Required: OAuth credentials
5+
ATHENA_CLIENT_ID=your-client-id
6+
ATHENA_CLIENT_SECRET=your-client-secret
7+
8+
# Required: Service configuration
9+
ATHENA_AFFILIATE=your-affiliate-name
10+
11+
# Optional: Service endpoints (defaults provided)
12+
# ATHENA_ISSUER_URL=https://crispthinking.auth0.com/ # Default: Crisp Auth0
13+
# ATHENA_GRPC_ADDRESS=trust.messages.crispthinking.com:443 # Default: production
14+
# ATHENA_AUDIENCE=crisp-athena-live # Default: live audience
15+
16+
# Development: Uncomment for debugging
17+
# NODE_ENV=development
18+
19+
# Usage:
20+
# 1. Copy this file: cp .env.example .env
21+
# 2. Edit .env with your actual values
22+
# 3. Source with auto-export: set -a; source .env; set +a
23+
# OR: export $(cat .env | grep -v '^#' | xargs)

‎samples/README.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Athena SDK Samples
2+
3+
This directory contains example applications demonstrating various use cases of the Athena Classifier SDK.
4+
5+
## Configuration
6+
7+
All samples use a shared configuration system. Create a `.env` file in this directory by copying from the `.env.example` and filling in the required configuration.
8+
9+
### Required
10+
- `ATHENA_CLIENT_ID` - Your OAuth client ID
11+
- `ATHENA_CLIENT_SECRET` - Your OAuth client secret
12+
- `ATHENA_AFFILIATE` - Your affiliate identifier
13+
14+
### Optional
15+
- `ATHENA_ISSUER_URL` - OAuth issuer/authorization server URL (default: https://crispthinking.auth0.com/)
16+
- `ATHENA_GRPC_ADDRESS` - gRPC service endpoint (default: trust.messages.crispthinking.com:443)
17+
- `ATHENA_AUDIENCE` - OAuth audience parameter (default: crisp-athena-live)
18+
19+
## Available Samples
20+
21+
### [Check Single](./check-single/)
22+
**Single Image Classification CLI Tool**
23+
24+
A command-line interface for classifying individual images. Features argument parsing, error handling, and formatted output.
25+
26+
- **Use Case**: Single image classification with CLI interface
27+
- **Features**: Multiple image formats, verbose mode, affiliate override
28+
29+
### [Hash Server](./hash-server/)
30+
**Continuous Image Classification Server**
31+
32+
A TypeScript server for continuous image classification with hash computation. Processes images in batches with real-time output.
33+
34+
- **Use Case**: Long-running classification service with hash computation
35+
- **Features**: Continuous processing, MD5/SHA1 hashes, graceful shutdown

‎samples/check-single/.gitignore‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Dependencies
2+
node_modules/
3+
4+
# Environment variables
5+
.env
6+
.env.local
7+
.env.*.local
8+
9+
# Logs
10+
*.log
11+
npm-debug.log*
12+
13+
# Runtime data
14+
pids
15+
*.pid
16+
*.seed
17+
*.pid.lock
18+
19+
# Coverage directory used by tools like istanbul
20+
coverage/
21+
22+
# Test images (user provided)
23+
*.jpg
24+
*.jpeg
25+
*.png
26+
*.gif
27+
*.bmp
28+
*.webp
29+
test-*
30+
sample-*
31+
32+
# OS generated files
33+
.DS_Store
34+
.DS_Store?
35+
._*
36+
.Spotlight-V100
37+
.Trashes
38+
ehthumbs.db
39+
Thumbs.db

‎samples/check-single/README.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# Athena Check Single - Image Classification CLI
2+
3+
A command-line tool for classifying individual images using the Athena Classifier SDK. This sample demonstrates how to build a more comprehensive CLI application with the SDK.
4+
5+
## Features
6+
7+
- ✅ **Single image classification** with detailed results
8+
- 🖼️ **Multiple image format support** (JPEG, PNG, GIF, BMP, WebP)
9+
- 🔧 **Command-line argument parsing** with validation
10+
- 📊 **Formatted output** with verbose mode
11+
- ⚙️ **Environment-based configuration**
12+
- 🚨 **Comprehensive error handling**
13+
- 📋 **Deployment verification**
14+
- ⏱️ **Timeout protection**
15+
16+
## Installation
17+
18+
```bash
19+
# Install dependencies
20+
npm install
21+
22+
# Or install from parent directory
23+
npm install ../../
24+
```
25+
26+
## Configuration
27+
28+
29+
Create a `.env` file in the samples directory with your Athena credentials as described in [the samples overview](../README.md).
30+
31+
Then source the environment:
32+
```bash
33+
set -a && source ../.env
34+
```
35+
36+
## Usage
37+
38+
### Basic Usage
39+
40+
```bash
41+
# Classify a single image
42+
node index.js ./my-image.jpg
43+
44+
# Using npm script
45+
npm start ./my-image.jpg
46+
```
47+
48+
### Advanced Usage
49+
```bash
50+
# Verbose output with detailed information
51+
node index.js ./image.png --verbose
52+
53+
# Force image format (useful for files without extensions)
54+
node index.js ./image --format jpeg
55+
56+
# Override affiliate
57+
node index.js ./image.jpg --affiliate different-affiliate
58+
```
59+
60+
### Command Line Options
61+
62+
| Option | Description |
63+
|--------|-------------|
64+
| `-h, --help` | Show help message |
65+
| `-v, --verbose` | Enable verbose output with detailed logs |
66+
| `-f, --format <format>` | Force image format (jpeg\|png\|gif\|bmp\|webp) |
67+
| `-a, --affiliate <name>` | Override affiliate name |
68+
69+
## Supported Image Formats
70+
71+
The tool automatically detects image format from file extensions:
72+
73+
- **JPEG**: `.jpg`, `.jpeg`
74+
- **PNG**: `.png`
75+
- **GIF**: `.gif`
76+
- **BMP**: `.bmp`
77+
- **WebP**: `.webp`
78+
79+
Use `--format` to override automatic detection.
80+
81+
## Error Handling
82+
83+
The tool provides error messages for common issues:
84+
85+
- **Missing arguments**: Image path is required
86+
- **File not found**: Image file validation
87+
- **Invalid format**: Unsupported image formats
88+
- **Missing credentials**: Environment variable validation
89+
- **Network issues**: Connection and authentication errors
90+
- **Service errors**: Classification failures with correlation IDs
91+
92+
## Architecture
93+
94+
The CLI demonstrates several SDK integration patterns:
95+
96+
1. **Configuration Management**: Environment-based configuration with validation
97+
2. **Error Handling**: Comprehensive error catching and user-friendly messages
98+
3. **Stream Processing**: Using streams for efficient image handling
99+
4. **Event-Driven Results**: Handling asynchronous classification results
100+
5. **Resource Management**: Proper connection lifecycle management
101+
102+
This sample serves as a template for building CLI tools with the Athena SDK.

0 commit comments

Comments
 (0)