@swapai/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SwapAI contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# SwapAI
+
+SwapAI learns from an existing classifier, trains a local Needle 2 classifier,
+and only uses it after it has passed a held-out test.
+
+```sh
+npm install @swapai/core
+```
+
+## Use it
+
+```ts
+import { init } from "@swapai/core";
+
+const relevance = init({
+  name: "accountant-relevance",
+  result: { type: "number", min: 0, max: 1 },
+  retrainOnCount: 50,
+  acceptableError: "10%",
+  retestInterval: 100,
+  retestRevertOn: 3,
+  model: "needle2",
+  maxTrainingSet: 10000,
+});
+
+const score = await relevance.classify(input, async (value) => {
+  const result = await callExistingClassifier(value);
+  return result.score;
+});
+```
+
+Before the local classifier is trained, `classify` calls the supplied reference
+classifier and records its answer. Once the local classifier passes its
+held-out test, it takes over. SwapAI periodically calls both classifiers to
+check that the local result remains within the allowed error.
+
+`input` must be the complete input sent to the reference classifier, including
+the instruction that defines the classification task. Do not log only the raw
+text being classified: Needle needs the same task and context the reference saw.
+
+## Manual control
+
+The callback is optional. You can keep control of the switch yourself:
+
+```ts
+if (relevance.isTrained()) {
+  return relevance.classify(input);
+}
+
+const score = await callExistingClassifier(input);
+relevance.logClassification(input, score);
+return score;
+```
+
+`isTrained()` and `logClassification()` are synchronous. Logging validates the
+result immediately and queues storage work. Use `await relevance.flush()` when
+you need to know all accepted examples are durable, such as during shutdown.
+
+## Result types
+
+SwapAI supports bounded numbers, booleans, and a closed list of strings:
+
+```ts
+init({
+  // other options
+  result: { type: "boolean" },
+});
+
+init({
+  // other options
+  result: { type: "string", values: ["rabbit", "fish", "pig"] },
+});
+```
+
+The string result is inferred as `"rabbit" | "fish" | "pig"`.
+
+## Effect
+
+Effect is optional and lives in a separate import:
+
+```ts
+import { classifyWithReference } from "@swapai/core/effect";
+
+const program = classifyWithReference(relevance, input, callReferenceEffect);
+```
+
+## Runtime
+
+Needle runs locally. On first use SwapAI creates its private runtime under
+`.swapai`, installs the pinned training package, and downloads Needle's model
+files. No Python setup is part of the TypeScript API. Set `dataDirectory` to
+store this state elsewhere.
+
+Full documentation: [stuartmccamley.com/swapai](https://stuartmccamley.com/swapai)

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,6 @@
+# Third-party notices
+
+SwapAI installs and runs [Cactus Needle](https://github.com/cactus-compute/needle),
+which is licensed under the Apache License 2.0. Needle is downloaded into the
+configured SwapAI data directory on first use; it is not bundled in this npm
+package.

package/dist/chunk-SXECHZ3L.js

@@ -0,0 +1,15 @@
+// src/errors.ts
+var SwapAIError = class extends Error {
+  _tag = "SwapAIError";
+  code;
+  constructor(code, message, options) {
+    super(message, options);
+    this.name = "SwapAIError";
+    this.code = code;
+  }
+};
+
+export {
+  SwapAIError
+};
+//# sourceMappingURL=chunk-SXECHZ3L.js.map

package/dist/chunk-SXECHZ3L.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts"],"sourcesContent":["export type SwapAIErrorCode =\n  | \"invalid_configuration\"\n  | \"invalid_result\"\n  | \"not_trained\"\n  | \"service_unavailable\"\n  | \"classification_failed\"\n  | \"storage_failed\";\n\nexport class SwapAIError extends Error {\n  readonly _tag = \"SwapAIError\" as const;\n  readonly code: SwapAIErrorCode;\n\n  constructor(\n    code: SwapAIErrorCode,\n    message: string,\n    options?: ErrorOptions,\n  ) {\n    super(message, options);\n    this.name = \"SwapAIError\";\n    this.code = code;\n  }\n}\n"],"mappings":";AAQO,IAAM,cAAN,cAA0B,MAAM;AAAA,EAC5B,OAAO;AAAA,EACP;AAAA,EAET,YACE,MACA,SACA,SACA;AACA,UAAM,SAAS,OAAO;AACtB,SAAK,OAAO;AACZ,SAAK,OAAO;AAAA,EACd;AACF;","names":[]}

package/dist/effect.d.ts

@@ -0,0 +1,7 @@
+import { Effect } from 'effect';
+import { R as ResultValue, C as Classifier, S as SwapAIError } from './types-DTbU1MEi.js';
+
+declare function classify<Result extends ResultValue>(classifier: Classifier<Result>, input: string): Effect.Effect<Result, SwapAIError>;
+declare function classifyWithReference<Result extends ResultValue, ReferenceError, Requirements>(classifier: Classifier<Result>, input: string, reference: (input: string) => Effect.Effect<Result, ReferenceError, Requirements>): Effect.Effect<Result, SwapAIError | ReferenceError, Requirements>;
+
+export { classify, classifyWithReference };

package/dist/effect.js

@@ -0,0 +1,55 @@
+import {
+  SwapAIError
+} from "./chunk-SXECHZ3L.js";
+
+// src/effect.ts
+import { Effect, Either, Runtime } from "effect";
+var ReferenceEffectFailure = class {
+  error;
+  constructor(error) {
+    this.error = error;
+  }
+};
+function classificationFailure(error) {
+  if (error instanceof SwapAIError) {
+    return error;
+  }
+  return new SwapAIError("classification_failed", "Classification failed", {
+    cause: error
+  });
+}
+function classify(classifier, input) {
+  return Effect.tryPromise({
+    try: () => classifier.classify(input),
+    catch: classificationFailure
+  });
+}
+function classifyWithReference(classifier, input, reference) {
+  return Effect.runtime().pipe(
+    Effect.flatMap(
+      (runtime) => Effect.tryPromise({
+        try: (signal) => classifier.classify(input, async (referenceInput) => {
+          const result = await Runtime.runPromise(runtime)(
+            Effect.either(reference(referenceInput)),
+            { signal }
+          );
+          if (Either.isLeft(result)) {
+            throw new ReferenceEffectFailure(result.left);
+          }
+          return result.right;
+        }),
+        catch: (error) => {
+          if (error instanceof ReferenceEffectFailure) {
+            return error.error;
+          }
+          return classificationFailure(error);
+        }
+      })
+    )
+  );
+}
+export {
+  classify,
+  classifyWithReference
+};
+//# sourceMappingURL=effect.js.map

package/dist/effect.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/effect.ts"],"sourcesContent":["import { Effect, Either, Runtime } from \"effect\";\n\nimport { SwapAIError } from \"./errors.js\";\nimport type { Classifier, ResultValue } from \"./types.js\";\n\nclass ReferenceEffectFailure<ReferenceError> {\n  readonly error: ReferenceError;\n\n  constructor(error: ReferenceError) {\n    this.error = error;\n  }\n}\n\nfunction classificationFailure(error: unknown): SwapAIError {\n  if (error instanceof SwapAIError) {\n    return error;\n  }\n\n  return new SwapAIError(\"classification_failed\", \"Classification failed\", {\n    cause: error,\n  });\n}\n\nexport function classify<Result extends ResultValue>(\n  classifier: Classifier<Result>,\n  input: string,\n): Effect.Effect<Result, SwapAIError> {\n  return Effect.tryPromise({\n    try: () => classifier.classify(input),\n    catch: classificationFailure,\n  });\n}\n\nexport function classifyWithReference<\n  Result extends ResultValue,\n  ReferenceError,\n  Requirements,\n>(\n  classifier: Classifier<Result>,\n  input: string,\n  reference: (\n    input: string,\n  ) => Effect.Effect<Result, ReferenceError, Requirements>,\n): Effect.Effect<Result, SwapAIError | ReferenceError, Requirements> {\n  return Effect.runtime<Requirements>().pipe(\n    Effect.flatMap((runtime) =>\n      Effect.tryPromise({\n        try: (signal) =>\n          classifier.classify(input, async (referenceInput) => {\n            const result = await Runtime.runPromise(runtime)(\n              Effect.either(reference(referenceInput)),\n              { signal },\n            );\n\n            if (Either.isLeft(result)) {\n              throw new ReferenceEffectFailure(result.left);\n            }\n\n            return result.right;\n          }),\n        catch: (error): SwapAIError | ReferenceError => {\n          if (error instanceof ReferenceEffectFailure) {\n            return error.error as ReferenceError;\n          }\n\n          return classificationFailure(error);\n        },\n      }),\n    ),\n  );\n}\n"],"mappings":";;;;;AAAA,SAAS,QAAQ,QAAQ,eAAe;AAKxC,IAAM,yBAAN,MAA6C;AAAA,EAClC;AAAA,EAET,YAAY,OAAuB;AACjC,SAAK,QAAQ;AAAA,EACf;AACF;AAEA,SAAS,sBAAsB,OAA6B;AAC1D,MAAI,iBAAiB,aAAa;AAChC,WAAO;AAAA,EACT;AAEA,SAAO,IAAI,YAAY,yBAAyB,yBAAyB;AAAA,IACvE,OAAO;AAAA,EACT,CAAC;AACH;AAEO,SAAS,SACd,YACA,OACoC;AACpC,SAAO,OAAO,WAAW;AAAA,IACvB,KAAK,MAAM,WAAW,SAAS,KAAK;AAAA,IACpC,OAAO;AAAA,EACT,CAAC;AACH;AAEO,SAAS,sBAKd,YACA,OACA,WAGmE;AACnE,SAAO,OAAO,QAAsB,EAAE;AAAA,IACpC,OAAO;AAAA,MAAQ,CAAC,YACd,OAAO,WAAW;AAAA,QAChB,KAAK,CAAC,WACJ,WAAW,SAAS,OAAO,OAAO,mBAAmB;AACnD,gBAAM,SAAS,MAAM,QAAQ,WAAW,OAAO;AAAA,YAC7C,OAAO,OAAO,UAAU,cAAc,CAAC;AAAA,YACvC,EAAE,OAAO;AAAA,UACX;AAEA,cAAI,OAAO,OAAO,MAAM,GAAG;AACzB,kBAAM,IAAI,uBAAuB,OAAO,IAAI;AAAA,UAC9C;AAEA,iBAAO,OAAO;AAAA,QAChB,CAAC;AAAA,QACH,OAAO,CAAC,UAAwC;AAC9C,cAAI,iBAAiB,wBAAwB;AAC3C,mBAAO,MAAM;AAAA,UACf;AAEA,iBAAO,sBAAsB,KAAK;AAAA,QACpC;AAAA,MACF,CAAC;AAAA,IACH;AAAA,EACF;AACF;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { a as ResultConfig, I as InitConfig, C as Classifier, b as ResultFor } from './types-DTbU1MEi.js';
+export { B as BooleanResultConfig, N as NormalizedInitConfig, c as NumberResultConfig, d as ReferenceClassifier, e as ResultComparison, R as ResultValue, f as StringResultConfig, S as SwapAIError } from './types-DTbU1MEi.js';
+
+declare function init<const Config extends ResultConfig>(inputConfig: InitConfig<Config>): Classifier<ResultFor<Config>>;
+
+export { Classifier, InitConfig, ResultConfig, ResultFor, init };