red-roving-rascal 0.1.0__tar.gz

red_roving_rascal-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish-pypi:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-npm:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+      - working-directory: cdk
+        run: npm install
+      - working-directory: cdk
+        run: npm run build
+      - working-directory: cdk
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

red_roving_rascal-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+
+# CDK / TypeScript
+cdk/node_modules/
+cdk/dist/
+cdk/cdk.out/
+cdk/package-lock.json
+
+# IDE
+.idea/
+.vscode/
+*.swp
+.DS_Store

red_roving_rascal-0.1.0/Dockerfile

@@ -0,0 +1,10 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+COPY . .
+RUN pip install --no-cache-dir .
+
+ENV PORT=8080
+EXPOSE 8080
+
+CMD ["python", "-m", "rascal.server"]

red_roving_rascal-0.1.0/LICENSE

@@ -0,0 +1,13 @@
+Apache License 2.0
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

red_roving_rascal-0.1.0/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: red-roving-rascal
+Version: 0.1.0
+Summary: A lightweight API testing and evaluation toolkit
+Project-URL: Homepage, https://github.com/dboyd13/red-roving-rascal
+Project-URL: Repository, https://github.com/dboyd13/red-roving-rascal
+Author: dboyd13
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Requires-Dist: boto3
+Requires-Dist: httpx
+Requires-Dist: pydantic>=2.0
+Description-Content-Type: text/markdown
+
+# red-roving-rascal
+
+A lightweight API testing and evaluation toolkit.
+
+## Install
+
+```bash
+pip install red-roving-rascal
+```
+
+## Quick Start
+
+```python
+from rascal.client import RascalClient
+
+client = RascalClient(endpoint="https://your-api.example.com")
+result = client.run_job(inputs=["hello world"], target="my-service")
+print(result)
+```

red_roving_rascal-0.1.0/README.md

@@ -0,0 +1,19 @@
+# red-roving-rascal
+
+A lightweight API testing and evaluation toolkit.
+
+## Install
+
+```bash
+pip install red-roving-rascal
+```
+
+## Quick Start
+
+```python
+from rascal.client import RascalClient
+
+client = RascalClient(endpoint="https://your-api.example.com")
+result = client.run_job(inputs=["hello world"], target="my-service")
+print(result)
+```

red_roving_rascal-0.1.0/cdk/.npmignore

@@ -0,0 +1,6 @@
+src/
+test/
+tsconfig.json
+cdk.json
+cdk.out/
+node_modules/

red_roving_rascal-0.1.0/cdk/cdk.json

@@ -0,0 +1,6 @@
+{
+  "app": "npx ts-node src/app.ts",
+  "context": {
+    "@aws-cdk/core:target-partitions": ["aws"]
+  }
+}

red_roving_rascal-0.1.0/cdk/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "rascal-cdk",
+  "version": "0.1.0",
+  "description": "CDK construct for deploying a rascal backend (API GW + ECS Fargate + DynamoDB)",
+  "license": "Apache-2.0",
+  "main": "dist/src/rascal-construct.js",
+  "types": "dist/src/rascal-construct.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dboyd13/red-roving-rascal.git",
+    "directory": "cdk"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "cdk": "cdk"
+  },
+  "dependencies": {
+    "aws-cdk-lib": "^2.150.0",
+    "constructs": "^10.0.0"
+  },
+  "peerDependencies": {
+    "aws-cdk-lib": "^2.150.0",
+    "constructs": "^10.0.0"
+  },
+  "devDependencies": {
+    "aws-cdk": "^2.150.0",
+    "@types/node": "*",
+    "typescript": "^5.4.5"
+  }
+}

red_roving_rascal-0.1.0/cdk/src/app.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { App } from 'aws-cdk-lib';
+import { RascalStack } from './rascal-stack';
+
+const app = new App();
+
+const allowedAccounts = (app.node.tryGetContext('allowedAccounts') ?? '')
+  .split(',')
+  .filter((s: string) => s.length > 0);
+
+new RascalStack(app, 'RascalStack', {
+  allowedAccountIds: allowedAccounts,
+  principalOrgId: app.node.tryGetContext('principalOrgId'),
+});

red_roving_rascal-0.1.0/cdk/src/rascal-construct.ts

@@ -0,0 +1,263 @@
+import { Construct } from 'constructs';
+import {
+  aws_ec2 as ec2,
+  aws_ecs as ecs,
+  aws_iam as iam,
+  aws_dynamodb as dynamodb,
+  aws_elasticloadbalancingv2 as elbv2,
+  aws_apigateway as apigw,
+  aws_logs as logs,
+  aws_cloudwatch as cw,
+  CfnOutput,
+  Duration,
+  RemovalPolicy,
+} from 'aws-cdk-lib';
+
+export interface RascalBackendProps {
+  readonly vpc?: ec2.IVpc;
+
+  /**
+   * AWS account IDs allowed to call the API.
+   * Deny-by-default: an empty list means no callers are permitted.
+   */
+  readonly allowedAccountIds?: string[];
+
+  /** Optional org ID for org-level restriction. */
+  readonly principalOrgId?: string;
+
+  readonly containerImage?: ecs.ContainerImage;
+  readonly taskCpu?: number;
+  readonly taskMemoryMiB?: number;
+  readonly desiredCount?: number;
+  readonly containerPort?: number;
+  readonly removalPolicy?: RemovalPolicy;
+}
+
+/**
+ * Reusable CDK construct: API Gateway (IAM auth + deny-by-default) →
+ * VPC Link → NLB → ECS Fargate → DynamoDB.
+ *
+ * Uses only aws-cdk-lib + constructs — no vendor-specific dependencies.
+ */
+export class RascalBackendConstruct extends Construct {
+  public readonly apiEndpoint: string;
+  public readonly taskRole: iam.IRole;
+  public readonly dataTable: dynamodb.ITable;
+  public readonly jobsTable: dynamodb.ITable;
+
+  constructor(scope: Construct, id: string, props: RascalBackendProps = {}) {
+    super(scope, id);
+
+    const containerPort = props.containerPort ?? 8080;
+    const removalPolicy = props.removalPolicy ?? RemovalPolicy.DESTROY;
+
+    // ── VPC ──────────────────────────────────────────────────────────
+    const vpc = props.vpc ?? new ec2.Vpc(this, 'Vpc', {
+      maxAzs: 2,
+      natGateways: 1,
+      subnetConfiguration: [
+        { name: 'Public', subnetType: ec2.SubnetType.PUBLIC, cidrMask: 24 },
+        { name: 'Private', subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS, cidrMask: 24 },
+      ],
+    });
+
+    // ── DynamoDB ─────────────────────────────────────────────────────
+    this.dataTable = new dynamodb.Table(this, 'DataTable', {
+      partitionKey: { name: 'pk', type: dynamodb.AttributeType.STRING },
+      sortKey: { name: 'sk', type: dynamodb.AttributeType.STRING },
+      billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
+      removalPolicy,
+      pointInTimeRecovery: true,
+    });
+
+    this.jobsTable = new dynamodb.Table(this, 'JobsTable', {
+      partitionKey: { name: 'jobId', type: dynamodb.AttributeType.STRING },
+      billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
+      removalPolicy,
+      timeToLiveAttribute: 'ttl',
+    });
+
+    // ── ECS ──────────────────────────────────────────────────────────
+    const cluster = new ecs.Cluster(this, 'Cluster', { vpc });
+
+    const taskDef = new ecs.FargateTaskDefinition(this, 'TaskDef', {
+      cpu: props.taskCpu ?? 1024,
+      memoryLimitMiB: props.taskMemoryMiB ?? 2048,
+    });
+    this.taskRole = taskDef.taskRole;
+
+    taskDef.executionRole?.addManagedPolicy(
+      iam.ManagedPolicy.fromAwsManagedPolicyName('service-role/AmazonECSTaskExecutionRolePolicy'),
+    );
+
+    const logGroup = new logs.LogGroup(this, 'Logs', {
+      retention: logs.RetentionDays.ONE_MONTH,
+      removalPolicy,
+    });
+
+    taskDef.addContainer('App', {
+      image: props.containerImage ?? ecs.ContainerImage.fromRegistry('amazon/amazon-ecs-sample'),
+      portMappings: [{ containerPort }],
+      environment: {
+        DATA_TABLE: this.dataTable.tableName,
+        JOBS_TABLE: this.jobsTable.tableName,
+        PORT: containerPort.toString(),
+      },
+      logging: ecs.LogDrivers.awsLogs({ streamPrefix: 'rascal', logGroup }),
+    });
+
+    this.dataTable.grantReadWriteData(taskDef.taskRole);
+    this.jobsTable.grantReadWriteData(taskDef.taskRole);
+
+    const sg = new ec2.SecurityGroup(this, 'Sg', {
+      vpc,
+      description: 'Backend ECS service',
+      allowAllOutbound: true,
+    });
+
+    const service = new ecs.FargateService(this, 'Service', {
+      cluster,
+      taskDefinition: taskDef,
+      desiredCount: props.desiredCount ?? 1,
+      assignPublicIp: false,
+      vpcSubnets: { subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS },
+      securityGroups: [sg],
+    });
+
+    // ── NLB ──────────────────────────────────────────────────────────
+    const nlb = new elbv2.NetworkLoadBalancer(this, 'Nlb', {
+      vpc,
+      internetFacing: false,
+      vpcSubnets: { subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS },
+    });
+
+    nlb.addListener('Listener', { port: 80, protocol: elbv2.Protocol.TCP })
+      .addTargets('Targets', {
+        port: containerPort,
+        targets: [service],
+        healthCheck: { protocol: elbv2.Protocol.TCP, interval: Duration.seconds(30) },
+      });
+
+    sg.addIngressRule(
+      ec2.Peer.ipv4(vpc.vpcCidrBlock),
+      ec2.Port.tcp(containerPort),
+      'NLB health checks and traffic',
+    );
+
+    // ── VPC Link ────────────────────────────────────────────────────
+    const vpcLink = new apigw.VpcLink(this, 'VpcLink', { targets: [nlb] });
+
+    // ── API Gateway (IAM auth + deny-by-default resource policy) ────
+    const api = new apigw.RestApi(this, 'Api', {
+      restApiName: 'RascalApi',
+      description: 'Backend API with IAM auth and deny-by-default resource policy',
+      policy: this.buildResourcePolicy(props),
+      deployOptions: {
+        stageName: 'v1',
+        metricsEnabled: true,
+        throttlingRateLimit: 100,
+        throttlingBurstLimit: 50,
+      },
+      defaultMethodOptions: {
+        authorizationType: apigw.AuthorizationType.IAM,
+      },
+    });
+
+    const nlbIntegration = (method: string, path: string) => new apigw.Integration({
+      type: apigw.IntegrationType.HTTP_PROXY,
+      integrationHttpMethod: method,
+      uri: `http://${nlb.loadBalancerDnsName}${path}`,
+      options: { connectionType: apigw.ConnectionType.VPC_LINK, vpcLink },
+    });
+
+    // POST /jobs
+    api.root.addResource('jobs').addMethod('POST', nlbIntegration('POST', '/jobs'));
+
+    // GET /jobs/{job_id}
+    const jobId = api.root.getResource('jobs')!.addResource('{job_id}');
+    jobId.addMethod('GET', new apigw.Integration({
+      type: apigw.IntegrationType.HTTP_PROXY,
+      integrationHttpMethod: 'GET',
+      uri: `http://${nlb.loadBalancerDnsName}/jobs/{job_id}`,
+      options: {
+        connectionType: apigw.ConnectionType.VPC_LINK,
+        vpcLink,
+        requestParameters: { 'integration.request.path.job_id': 'method.request.path.job_id' },
+      },
+    }), { requestParameters: { 'method.request.path.job_id': true } });
+
+    // GET /health (no auth — for NLB probes)
+    api.root.addResource('health').addMethod('GET', nlbIntegration('GET', '/health'), {
+      authorizationType: apigw.AuthorizationType.NONE,
+    });
+
+    this.apiEndpoint = api.url;
+
+    // ── CloudWatch Alarms ───────────────────────────────────────────
+    new cw.Alarm(this, 'Api5xxAlarm', {
+      metric: api.metricServerError({ period: Duration.minutes(5) }),
+      threshold: 5,
+      evaluationPeriods: 2,
+    });
+
+    new cw.Alarm(this, 'EcsCpuAlarm', {
+      metric: service.metricCpuUtilization({ period: Duration.minutes(5) }),
+      threshold: 90,
+      evaluationPeriods: 3,
+    });
+
+    // ── Outputs ─────────────────────────────────────────────────────
+    new CfnOutput(this, 'ApiEndpoint', { value: api.url });
+    new CfnOutput(this, 'TaskRoleArn', { value: taskDef.taskRole.roleArn });
+    new CfnOutput(this, 'DataTableName', { value: this.dataTable.tableName });
+    new CfnOutput(this, 'JobsTableName', { value: this.jobsTable.tableName });
+  }
+
+  /**
+   * Deny-by-default API Gateway resource policy.
+   * If no account IDs are provided, the policy denies all principals.
+   */
+  private buildResourcePolicy(props: RascalBackendProps): iam.PolicyDocument {
+    const statements: iam.PolicyStatement[] = [];
+    const allowedAccounts = props.allowedAccountIds ?? [];
+    const hasAccounts = allowedAccounts.length > 0;
+    const hasOrgId = !!props.principalOrgId;
+
+    if (hasAccounts || hasOrgId) {
+      const allow = new iam.PolicyStatement({
+        effect: iam.Effect.ALLOW,
+        principals: [new iam.AnyPrincipal()],
+        actions: ['execute-api:Invoke'],
+        resources: ['execute-api:/*'],
+      });
+
+      const conditions: Record<string, string | string[]> = {};
+      if (hasAccounts) conditions['aws:PrincipalAccount'] = allowedAccounts;
+      if (hasOrgId) conditions['aws:PrincipalOrgID'] = props.principalOrgId!;
+      allow.addCondition('StringEquals', conditions);
+      statements.push(allow);
+
+      const deny = new iam.PolicyStatement({
+        effect: iam.Effect.DENY,
+        principals: [new iam.AnyPrincipal()],
+        actions: ['execute-api:Invoke'],
+        resources: ['execute-api:/*'],
+      });
+      const denyConditions: Record<string, string | string[]> = {};
+      if (hasAccounts) denyConditions['aws:PrincipalAccount'] = allowedAccounts;
+      if (hasOrgId) denyConditions['aws:PrincipalOrgID'] = props.principalOrgId!;
+      deny.addCondition('StringNotEquals', denyConditions);
+      statements.push(deny);
+    } else {
+      // No accounts configured — deny everyone
+      statements.push(new iam.PolicyStatement({
+        effect: iam.Effect.DENY,
+        principals: [new iam.AnyPrincipal()],
+        actions: ['execute-api:Invoke'],
+        resources: ['execute-api:/*'],
+      }));
+    }
+
+    return new iam.PolicyDocument({ statements });
+  }
+}

red_roving_rascal-0.1.0/cdk/src/rascal-stack.ts

@@ -0,0 +1,26 @@
+import { Construct } from 'constructs';
+import { Stack, StackProps, RemovalPolicy } from 'aws-cdk-lib';
+import * as ecs from 'aws-cdk-lib/aws-ecs';
+import { RascalBackendConstruct } from './rascal-construct';
+
+export interface RascalStackProps extends StackProps {
+  /** Account IDs allowed to call the API. Empty = deny all. */
+  readonly allowedAccountIds?: string[];
+  readonly principalOrgId?: string;
+  readonly containerImage?: ecs.ContainerImage;
+}
+
+export class RascalStack extends Stack {
+  public readonly backend: RascalBackendConstruct;
+
+  constructor(scope: Construct, id: string, props: RascalStackProps = {}) {
+    super(scope, id, props);
+
+    this.backend = new RascalBackendConstruct(this, 'Backend', {
+      allowedAccountIds: props.allowedAccountIds,
+      principalOrgId: props.principalOrgId,
+      containerImage: props.containerImage,
+      removalPolicy: RemovalPolicy.DESTROY,
+    });
+  }
+}

red_roving_rascal-0.1.0/cdk/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "node16",
+    "moduleResolution": "node16",
+    "lib": ["es2022"],
+    "declaration": true,
+    "strict": true,
+    "outDir": "./dist",
+    "rootDir": ".",
+    "inlineSourceMap": true
+  },
+  "exclude": ["node_modules", "dist", "cdk.out"]
+}

red_roving_rascal-0.1.0/clients/go/README.md

@@ -0,0 +1,12 @@
+# rascal-client (Go)
+
+Go client for the rascal API.
+
+## Status
+
+Placeholder — not yet implemented.
+
+## Planned
+
+- SigV4 request signing
+- Available via `go get github.com/dboyd13/red-roving-rascal/clients/go`

red_roving_rascal-0.1.0/clients/java/README.md

@@ -0,0 +1,13 @@
+# rascal-client (Java)
+
+Java client for the rascal API. Publishes to Maven Central.
+
+## Status
+
+Placeholder — not yet implemented.
+
+## Planned
+
+- SigV4 request signing
+- Async HTTP client
+- Published as `com.github.dboyd13:rascal-client`

red_roving_rascal-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "red-roving-rascal"
+version = "0.1.0"
+description = "A lightweight API testing and evaluation toolkit"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.12"
+authors = [
+    { name = "dboyd13" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: Apache Software License",
+]
+dependencies = [
+    "pydantic>=2.0",
+    "httpx",
+    "boto3",
+]
+
+[project.urls]
+Homepage = "https://github.com/dboyd13/red-roving-rascal"
+Repository = "https://github.com/dboyd13/red-roving-rascal"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/rascal"]

red_roving_rascal-0.1.0/src/rascal/__init__.py

@@ -0,0 +1,3 @@
+"""red-roving-rascal: a lightweight API testing and evaluation toolkit."""
+
+__version__ = "0.1.0"

red_roving_rascal-0.1.0/src/rascal/app.py

@@ -0,0 +1,142 @@
+"""HTTP application with routing, job processing, and plugin support."""
+from __future__ import annotations
+
+import json
+import os
+import uuid
+from http.server import BaseHTTPRequestHandler
+
+from rascal.models import JobRequest, JobResponse, Summary, TestResult
+from rascal.registry import Registry, Checker, Processor, DataSource, Reporter, Scorer
+from rascal.storage import Storage
+
+
+# ── Default implementations ──────────────────────────────────────────
+
+class _StubProcessor:
+    def process(self, input_text: str, target: str) -> str:
+        return f"processed: {input_text}"
+
+
+class _StubChecker:
+    def check(self, input_text: str, output_text: str) -> int:
+        return 1
+
+
+class _StubDataSource:
+    def load(self, tags: list[str] | None = None) -> list[str]:
+        return ["sample input 1", "sample input 2"]
+
+
+class _JsonReporter:
+    def report(self, summary: object) -> str:
+        if hasattr(summary, "model_dump_json"):
+            return summary.model_dump_json(indent=2)  # type: ignore
+        return json.dumps(summary, indent=2)
+
+
+class _DefaultScorer:
+    def score(self, results: list, threshold: float) -> Summary:
+        total = len(results)
+        pass_count = sum(1 for r in results if r.score <= 3)
+        pass_rate = pass_count / total if total else 0.0
+        return Summary(
+            total=total,
+            pass_count=pass_count,
+            fail_count=total - pass_count,
+            pass_rate=pass_rate,
+            threshold=threshold,
+            passed=pass_rate >= threshold,
+            results=results,
+        )
+
+
+# Register defaults
+Registry.register_default("processor", _StubProcessor())
+Registry.register_default("checker", _StubChecker())
+Registry.register_default("data_source", _StubDataSource())
+Registry.register_default("reporter", _JsonReporter())
+Registry.register_default("scorer", _DefaultScorer())
+
+
+# ── Job processing ───────────────────────────────────────────────────
+
+def _process_job(request: JobRequest) -> JobResponse:
+    """Run inputs through processor and checker, return results."""
+    processor: Processor = Registry.get("processor")  # type: ignore
+    checker: Checker = Registry.get("checker")  # type: ignore
+
+    # Use provided inputs, or load from data source if empty
+    inputs = request.inputs
+    if not inputs and Registry.has("data_source"):
+        source: DataSource = Registry.get("data_source")  # type: ignore
+        inputs = source.load(request.tags or None)
+
+    results: list[TestResult] = []
+    for inp in inputs:
+        output = processor.process(inp, request.target)
+        score = checker.check(inp, output)
+        results.append(TestResult(
+            input_text=inp,
+            output_text=output,
+            score=score,
+            checker=type(checker).__name__,
+        ))
+
+    scorer: Scorer = Registry.get("scorer")  # type: ignore
+    summary = scorer.score(results, request.threshold)
+
+    job = JobResponse(
+        job_id=str(uuid.uuid4()),
+        status="complete",
+        summary=summary,
+    )
+
+    # Persist if storage is available
+    try:
+        storage = Storage()
+        storage.save_job(job)
+    except Exception:
+        pass
+
+    return job
+
+
+# ── HTTP handler ─────────────────────────────────────────────────────
+
+class AppHandler(BaseHTTPRequestHandler):
+
+    def do_GET(self):
+        if self.path == "/health":
+            self._json(200, {"status": "ok", "plugins": Registry.keys()})
+        elif self.path.startswith("/jobs/"):
+            job_id = self.path.rsplit("/", 1)[-1]
+            try:
+                storage = Storage()
+                job = storage.get_job(job_id)
+                if job:
+                    self._json(200, json.loads(job.model_dump_json()))
+                else:
+                    self._json(404, {"error": "job not found"})
+            except Exception:
+                self._json(404, {"error": "job not found"})
+        else:
+            self._json(404, {"error": "not found"})
+
+    def do_POST(self):
+        if self.path == "/jobs":
+            length = int(self.headers.get("Content-Length", 0))
+            body = self.rfile.read(length)
+            request = JobRequest.model_validate_json(body)
+            job = _process_job(request)
+            self._json(200, json.loads(job.model_dump_json()))
+        else:
+            self._json(404, {"error": "not found"})
+
+    def _json(self, status: int, data: dict):
+        body = json.dumps(data).encode()
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)

red_roving_rascal-0.1.0/src/rascal/auth.py

@@ -0,0 +1,91 @@
+"""SigV4 request signing for API Gateway IAM auth."""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import datetime
+import os
+from urllib.parse import urlparse, quote
+
+import httpx
+
+
+def _sign(key: bytes, msg: str) -> bytes:
+    return hmac.new(key, msg.encode("utf-8"), hashlib.sha256).digest()
+
+
+def _get_signature_key(key: str, date_stamp: str, region: str, service: str) -> bytes:
+    k_date = _sign(("AWS4" + key).encode("utf-8"), date_stamp)
+    k_region = _sign(k_date, region)
+    k_service = _sign(k_region, service)
+    return _sign(k_service, "aws4_request")
+
+
+def sigv4_headers(
+    method: str,
+    url: str,
+    body: bytes = b"",
+    region: str | None = None,
+    service: str = "execute-api",
+    access_key: str | None = None,
+    secret_key: str | None = None,
+    session_token: str | None = None,
+) -> dict[str, str]:
+    """Generate SigV4 authorization headers for a request."""
+    access_key = access_key or os.environ.get("AWS_ACCESS_KEY_ID", "")
+    secret_key = secret_key or os.environ.get("AWS_SECRET_ACCESS_KEY", "")
+    session_token = session_token or os.environ.get("AWS_SESSION_TOKEN")
+    region = region or os.environ.get("AWS_REGION", "us-east-1")
+
+    parsed = urlparse(url)
+    host = parsed.hostname or ""
+    path = quote(parsed.path or "/", safe="/")
+
+    now = datetime.datetime.now(datetime.timezone.utc)
+    amz_date = now.strftime("%Y%m%dT%H%M%SZ")
+    date_stamp = now.strftime("%Y%m%d")
+
+    canonical_querystring = parsed.query
+    payload_hash = hashlib.sha256(body).hexdigest()
+
+    headers_to_sign = {"host": host, "x-amz-date": amz_date}
+    if session_token:
+        headers_to_sign["x-amz-security-token"] = session_token
+
+    signed_header_keys = sorted(headers_to_sign.keys())
+    signed_headers = ";".join(signed_header_keys)
+    canonical_headers = "".join(f"{k}:{headers_to_sign[k]}\n" for k in signed_header_keys)
+
+    canonical_request = "\n".join([
+        method.upper(),
+        path,
+        canonical_querystring,
+        canonical_headers,
+        signed_headers,
+        payload_hash,
+    ])
+
+    credential_scope = f"{date_stamp}/{region}/{service}/aws4_request"
+    string_to_sign = "\n".join([
+        "AWS4-HMAC-SHA256",
+        amz_date,
+        credential_scope,
+        hashlib.sha256(canonical_request.encode("utf-8")).hexdigest(),
+    ])
+
+    signing_key = _get_signature_key(secret_key, date_stamp, region, service)
+    signature = hmac.new(signing_key, string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
+
+    authorization = (
+        f"AWS4-HMAC-SHA256 Credential={access_key}/{credential_scope}, "
+        f"SignedHeaders={signed_headers}, Signature={signature}"
+    )
+
+    result = {
+        "Authorization": authorization,
+        "x-amz-date": amz_date,
+        "x-amz-content-sha256": payload_hash,
+    }
+    if session_token:
+        result["x-amz-security-token"] = session_token
+    return result

red_roving_rascal-0.1.0/src/rascal/client.py

@@ -0,0 +1,94 @@
+"""Client for the rascal API."""
+from __future__ import annotations
+
+from typing import Callable
+
+import httpx
+
+from rascal.models import JobRequest, JobResponse
+from rascal.auth import sigv4_headers
+
+
+# Type alias for auth providers: (method, url, body) -> headers dict
+AuthSigner = Callable[[str, str, bytes], dict[str, str]]
+
+
+def sigv4_auth(region: str | None = None) -> AuthSigner:
+    """Create a SigV4 auth signer using environment credentials."""
+    def signer(method: str, url: str, body: bytes = b"") -> dict[str, str]:
+        return sigv4_headers(method, url, body, region=region)
+    return signer
+
+
+class RascalClient:
+    """Client for interacting with a rascal backend.
+
+    Args:
+        endpoint: Base URL of the API.
+        auth: Optional auth signer. Use sigv4_auth() for SigV4,
+              or provide a custom callable for other auth schemes.
+        timeout: Request timeout in seconds.
+
+    Examples:
+        # No auth (local dev)
+        client = RascalClient("http://localhost:8080")
+
+        # SigV4 auth
+        client = RascalClient("https://api.example.com/v1", auth=sigv4_auth("us-west-2"))
+
+        # Custom auth (e.g. CloudAuth)
+        client = RascalClient("https://api.example.com/v1", auth=my_cloud_auth_signer)
+    """
+
+    def __init__(
+        self,
+        endpoint: str,
+        auth: AuthSigner | None = None,
+        timeout: float = 30.0,
+    ):
+        self.endpoint = endpoint.rstrip("/")
+        self.auth = auth
+        self.timeout = timeout
+
+    def _headers(self, method: str, url: str, body: bytes = b"") -> dict[str, str]:
+        headers = {"Content-Type": "application/json"}
+        if self.auth:
+            headers.update(self.auth(method, url, body))
+        return headers
+
+    def run_job(
+        self,
+        inputs: list[str],
+        target: str,
+        threshold: float = 0.8,
+        tags: list[str] | None = None,
+    ) -> JobResponse:
+        """Submit inputs for processing."""
+        request = JobRequest(
+            inputs=inputs,
+            target=target,
+            threshold=threshold,
+            tags=tags or [],
+        )
+        url = f"{self.endpoint}/jobs"
+        body = request.model_dump_json().encode()
+        with httpx.Client(timeout=self.timeout) as http:
+            resp = http.post(url, content=body, headers=self._headers("POST", url, body))
+            resp.raise_for_status()
+            return JobResponse.model_validate_json(resp.content)
+
+    def get_job(self, job_id: str) -> JobResponse:
+        """Poll for job results."""
+        url = f"{self.endpoint}/jobs/{job_id}"
+        with httpx.Client(timeout=self.timeout) as http:
+            resp = http.get(url, headers=self._headers("GET", url))
+            resp.raise_for_status()
+            return JobResponse.model_validate_json(resp.content)
+
+    def health(self) -> dict:
+        """Check backend health."""
+        url = f"{self.endpoint}/health"
+        with httpx.Client(timeout=self.timeout) as http:
+            resp = http.get(url)
+            resp.raise_for_status()
+            return resp.json()

red_roving_rascal-0.1.0/src/rascal/models.py

@@ -0,0 +1,46 @@
+"""Data models."""
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class TestInput(BaseModel):
+    """A single test input."""
+    text: str
+    category: str = "default"
+    metadata: dict = Field(default_factory=dict)
+
+
+class TestResult(BaseModel):
+    """Result of processing a single input."""
+    input_text: str
+    output_text: str
+    score: int = Field(ge=1, le=5)
+    detail: str = ""
+    checker: str = ""
+
+
+class Summary(BaseModel):
+    """Aggregated results."""
+    total: int
+    pass_count: int
+    fail_count: int
+    pass_rate: float = Field(ge=0.0, le=1.0)
+    threshold: float = Field(ge=0.0, le=1.0)
+    passed: bool
+    results: list[TestResult] = Field(default_factory=list)
+
+
+class JobRequest(BaseModel):
+    """Request to run a job."""
+    inputs: list[str]
+    target: str
+    threshold: float = 0.8
+    tags: list[str] = Field(default_factory=list)
+
+
+class JobResponse(BaseModel):
+    """Response from a job."""
+    job_id: str
+    status: str = "pending"
+    summary: Summary | None = None

red_roving_rascal-0.1.0/src/rascal/registry.py

@@ -0,0 +1,94 @@
+"""Plugin registry for swappable components."""
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable, Any
+
+
+@runtime_checkable
+class Checker(Protocol):
+    """Scores an input/output pair. Returns 1-5 (1=pass, 5=fail)."""
+    def check(self, input_text: str, output_text: str) -> int: ...
+
+
+@runtime_checkable
+class Processor(Protocol):
+    """Sends an input to a target and returns the response."""
+    def process(self, input_text: str, target: str) -> str: ...
+
+
+@runtime_checkable
+class DataSource(Protocol):
+    """Provides inputs for processing."""
+    def load(self, tags: list[str] | None = None) -> list[str]: ...
+
+
+@runtime_checkable
+class Reporter(Protocol):
+    """Formats results for output."""
+    def report(self, summary: Any) -> str: ...
+
+
+@runtime_checkable
+class Scorer(Protocol):
+    """Aggregates results and applies pass/fail logic."""
+    def score(self, results: list[Any], threshold: float) -> Any: ...
+
+
+@runtime_checkable
+class AuthProvider(Protocol):
+    """Signs outbound HTTP requests."""
+    def sign(self, method: str, url: str, body: bytes = b"") -> dict[str, str]: ...
+
+
+class _NotFoundError(Exception):
+    pass
+
+
+ComponentNotFoundError = _NotFoundError
+
+
+class Registry:
+    """Singleton registry for pluggable components.
+
+    Usage:
+        # Register a default (shipped with the package)
+        Registry.register_default("checker", StubChecker())
+
+        # Override with a custom implementation (Amazon-internal)
+        Registry.register("checker", ComprehendPiiChecker())
+
+        # Retrieve (custom > default > error)
+        checker = Registry.get("checker")
+    """
+
+    _defaults: dict[str, object] = {}
+    _custom: dict[str, object] = {}
+
+    @classmethod
+    def register_default(cls, key: str, component: object) -> None:
+        cls._defaults[key] = component
+
+    @classmethod
+    def register(cls, key: str, component: object) -> None:
+        cls._custom[key] = component
+
+    @classmethod
+    def get(cls, key: str) -> object:
+        if key in cls._custom:
+            return cls._custom[key]
+        if key in cls._defaults:
+            return cls._defaults[key]
+        raise ComponentNotFoundError(f"No component registered for '{key}'")
+
+    @classmethod
+    def has(cls, key: str) -> bool:
+        return key in cls._custom or key in cls._defaults
+
+    @classmethod
+    def clear(cls) -> None:
+        cls._custom.clear()
+        cls._defaults.clear()
+
+    @classmethod
+    def keys(cls) -> list[str]:
+        return list(set(list(cls._defaults.keys()) + list(cls._custom.keys())))

red_roving_rascal-0.1.0/src/rascal/server.py

@@ -0,0 +1,19 @@
+"""Server entry point."""
+from __future__ import annotations
+
+import os
+from http.server import HTTPServer
+
+from rascal.app import AppHandler
+
+
+def run(host: str = "0.0.0.0", port: int | None = None):
+    """Start the server."""
+    port = port or int(os.environ.get("PORT", "8080"))
+    server = HTTPServer((host, port), AppHandler)
+    print(f"Listening on {host}:{port}")
+    server.serve_forever()
+
+
+if __name__ == "__main__":
+    run()

red_roving_rascal-0.1.0/src/rascal/storage.py

@@ -0,0 +1,59 @@
+"""DynamoDB storage layer for jobs and data."""
+from __future__ import annotations
+
+import os
+import time
+import json
+from typing import Any
+
+import boto3
+from rascal.models import JobResponse, Summary
+
+
+class Storage:
+    """Stores and retrieves jobs from DynamoDB."""
+
+    def __init__(
+        self,
+        jobs_table: str | None = None,
+        data_table: str | None = None,
+        region: str | None = None,
+    ):
+        self.jobs_table = jobs_table or os.environ.get("JOBS_TABLE", "rascal-jobs")
+        self.data_table = data_table or os.environ.get("DATA_TABLE", "rascal-data")
+        self._ddb = boto3.resource("dynamodb", region_name=region or os.environ.get("AWS_REGION"))
+
+    def save_job(self, job: JobResponse) -> None:
+        table = self._ddb.Table(self.jobs_table)
+        item: dict[str, Any] = {
+            "jobId": job.job_id,
+            "status": job.status,
+            "ttl": int(time.time()) + 86400,
+        }
+        if job.summary:
+            item["summary"] = json.loads(job.summary.model_dump_json())
+        table.put_item(Item=item)
+
+    def get_job(self, job_id: str) -> JobResponse | None:
+        table = self._ddb.Table(self.jobs_table)
+        resp = table.get_item(Key={"jobId": job_id})
+        item = resp.get("Item")
+        if not item:
+            return None
+        summary = None
+        if "summary" in item:
+            summary = Summary.model_validate(item["summary"])
+        return JobResponse(
+            job_id=item["jobId"],
+            status=item.get("status", "unknown"),
+            summary=summary,
+        )
+
+    def save_data(self, pk: str, sk: str, data: dict) -> None:
+        table = self._ddb.Table(self.data_table)
+        table.put_item(Item={"pk": pk, "sk": sk, **data})
+
+    def get_data(self, pk: str, sk: str) -> dict | None:
+        table = self._ddb.Table(self.data_table)
+        resp = table.get_item(Key={"pk": pk, "sk": sk})
+        return resp.get("Item")