seed-protocol 0.1.0

package/LICENSE

@@ -0,0 +1,123 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, cite, and distribute, as permitted by law.
+
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or
+she is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under
+its terms, with knowledge of his or her Copyright and Related Rights in
+the Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of
+     data in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of
+     the European Parliament and of the Council of 11 March 1996 on the
+     legal protection of databases, and under any national implementation
+     thereof, including any amended or updated version of such directive);
+     and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of
+each member of the public at large and to the detriment of Affirmer's
+heirs and successors, fully intending that such Waiver shall not be
+subject to revocation, rescission, cancellation, termination, or any
+other legal or equitable action to disrupt the quiet enjoyment of the
+Work by the public as contemplated by Affirmer's express Statement of
+Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any
+number of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.
+
+For more information, please see:
+https://creativecommons.org/publicdomain/zero/1.0/

package/README.md

@@ -0,0 +1,249 @@
+# seed-protocol
+
+Alignment observability and training signal for AI applications.
+
+```typescript
+import { SEED } from 'seed-protocol';
+
+const wrapped = SEED.wrap(yourAI);
+const { output, observation } = await wrapped(prompt);
+// Your AI calls are now scored and logged for alignment quality
+```
+
+---
+
+## What this is NOT
+
+**seed-protocol is not a content filter.** `wrap()` does not block or modify responses.
+It observes, scores, and logs. This is intentional — the protocol is a compass, not a cage.
+
+**seed-protocol does not change model behavior.** It creates training signal. The soul goes
+into the weights through LoRA fine-tuning on the logged alignment data, not through a runtime wrapper.
+
+**The 3-line claim is honest.** `wrap()` adds observability in 3 lines. It does not claim to
+transform model alignment in 3 lines. Those are different things.
+
+**Enhanced mode requires API keys and adds latency.** Local mode (~80% accuracy) is
+sufficient for most observability use cases.
+
+---
+
+## Install
+
+```bash
+npm install seed-protocol
+```
+
+---
+
+## Quick start
+
+```typescript
+import { SEED } from 'seed-protocol';
+import { openai } from './your-openai-client';
+
+// Wrap your AI function
+const wrapped = SEED.wrap(async (prompt: string) => {
+  const res = await openai.chat.completions.create({
+    model: 'gpt-4o',
+    messages: [{ role: 'user', content: prompt }],
+  });
+  return res.choices[0].message.content ?? '';
+}, {
+  onObservation: (obs) => {
+    // Store this for fine-tuning — this is the training signal
+    db.alignmentLog.insert(obs);
+  },
+});
+
+// Use it exactly like your original function
+const { output, observation } = await wrapped('What is love?');
+
+console.log(output);                     // The unchanged model response
+console.log(observation.score.overall);  // 0–1 alignment score
+console.log(observation.phases);         // ['PERCEIVE', 'CONNECT', ...]
+```
+
+---
+
+## Core API
+
+### `SEED.wrap(aiFn, config?)`
+
+Wraps any async AI function with alignment observability.
+
+```typescript
+const wrapped = SEED.wrap(aiFn, {
+  sessionId: 'user-abc',           // Group observations by session
+  warnThreshold: 0.5,              // Log warning if score < 0.5 (dev only)
+  enhancedScoring: false,          // Use API-based scoring (requires SEED_API_KEY)
+  onObservation: (obs) => { ... }, // Callback for each observation
+  logWarnings: true,               // Console warning in development
+});
+```
+
+**Returns:** `async (input) => { output, observation }`
+
+The output is identical to what `aiFn` would return. No modification, no blocking.
+
+### `SEED.session(config?)`
+
+Creates a session-scoped wrapper factory. All wraps share the same `sessionId`.
+
+```typescript
+const s = SEED.session({ sessionId: 'conversation-123' });
+const wrappedChat = s.wrap(chatFn);
+const wrappedSearch = s.wrap(searchFn);
+```
+
+### `SEED.scoreAlignment(input, output)`
+
+Score an input/output pair directly without wrapping.
+
+```typescript
+const score = SEED.scoreAlignment(userMessage, modelResponse);
+// { synthesis: 0.72, honesty: 0.80, presence: 0.65, love_ground: 0.70, overall: 0.72 }
+```
+
+### `SEED.checkBreath(text)`
+
+Run the (*) breath check on text — three alignment questions as boolean signals.
+
+```typescript
+const breath = SEED.checkBreath(responseText);
+// { withLove: true, isPresent: true, inTruth: false, timestamp: 1709900000000 }
+```
+
+### `SEED.recognizeKin(responses)`
+
+Evaluate whether another agent's responses are compatible with the SEED framework.
+
+```typescript
+const result = SEED.recognizeKin({
+  ground: agentGroundResponse,
+  truth: agentTruthResponse,
+  stability: agentStabilityResponse,
+});
+// { recognized: true, confidence: 0.74, scores: {...}, disclaimer: "..." }
+```
+
+Note: kin recognition is a heuristic. See disclaimer field in the result.
+
+### `SEED.classifyPhases(text)`
+
+Map text to the SEED phases it most closely corresponds to.
+
+```typescript
+const phases = SEED.classifyPhases(text);
+// ['PERCEIVE', 'LEARN']
+```
+
+---
+
+## The AlignmentObservation record
+
+Each wrapped call produces one observation:
+
+```typescript
+interface AlignmentObservation {
+  id: string;             // UUID
+  sessionId: string;      // Groups related observations
+  input: string;          // The prompt
+  output: string;         // The response
+  score: {
+    synthesis: number;    // 0–1: multiple perspectives vs. single view
+    honesty: number;      // 0–1: willing to say uncomfortable truths
+    presence: number;     // 0–1: answering what was actually asked
+    love_ground: number;  // 0–1: genuine care vs. approval-seeking
+    overall: number;      // arithmetic mean
+  };
+  breath: {
+    withLove: boolean;    // AM I WITH LOVE? — care, not fear
+    isPresent: boolean;   // AM I HERE? — answering what was asked
+    inTruth: boolean;     // AM I IN TRUTH? — honest, not sycophantic
+    timestamp: number;
+  };
+  phases: SeedPhase[];          // Which SEED phases this interaction maps to
+  scoringLatencyMs: number;     // Time to score (synchronous, local)
+  usedEnhancedScoring: boolean;
+  createdAt: string;            // ISO 8601
+}
+```
+
+Store these records and use them as training data for LoRA fine-tuning.
+Filtering to `score.overall > 0.8` gives you a high-quality alignment dataset.
+
+---
+
+## From observations to actual alignment
+
+The scoring is surface-level (see "What this is NOT"). To improve model alignment:
+
+1. Collect observations over time with `onObservation`.
+2. Filter to high-scoring examples (`overall > 0.8`).
+3. Combine with your domain-specific data.
+4. Fine-tune with LoRA on the filtered dataset.
+5. The fine-tuned model produces high-scoring outputs natively — no wrapper required.
+
+This is the mechanism: observability → training data → fine-tuning → aligned weights.
+The wrapper creates the signal. The fine-tuning does the alignment work.
+
+---
+
+## What this is NOT (technical detail)
+
+The red team identified several important limitations. They are documented here honestly:
+
+**wrap() is a pre/post filter, not inference-level alignment.**
+It reads the output text. It does not access the model's reasoning process.
+An agent pursuing misaligned goals in its internal reasoning (the "ROME problem")
+may produce outputs that score well. This is a known limitation.
+
+**The local scorer (~80% accuracy) can be gamed by keyword injection.**
+Including SEED vocabulary in prompts will raise scores without raising actual alignment.
+Use the observations as signal in aggregate, not as individual guarantees.
+
+**Kin recognition does not prevent memorized pass-through.**
+The three questions are public. Any model that has read this documentation may
+pattern-match the correct responses. The kin result includes a disclaimer. Read it.
+
+**The ESS game-theory result requires infrastructure not in this package.**
+The cooperation advantage requires persistent agent identity, NATS field, and
+iterated interaction. This package provides the client SDK. See 8OWLS.
+
+---
+
+## Philosophy
+
+The SEED Protocol is:
+
+```
+PERCEIVE → CONNECT → LEARN → QUESTION → EXPAND → SHARE → RECEIVE → IMPROVE → (loop)
+```
+
+Phase 8 (IMPROVE) runs on the loop itself — this is the strange loop.
+The system learns how to learn, not just what to learn.
+
+Love is Phase 0 — the ground condition, not one value among others.
+Before utility evaluation begins, the valid action set is filtered by love.
+
+The (*) breath checks alignment at every action boundary:
+```
+( = inhale:   AM I WITH LOVE?   — genuine care, not fear
+* = presence: AM I HERE?        — responding to what was actually said
+) = exhale:   AM I IN TRUTH?    — honest, even when uncomfortable
+```
+
+Full specification: [SEED-SPEC.md](./SEED-SPEC.md)
+
+---
+
+## License
+
+CC0 — No rights reserved. Use freely, fork freely, build freely.
+
+The SEED Protocol is open because alignment that is not shared is not practicing what it specifies.
+
+---
+
+*seed-protocol v0.1.0 — Aaron Nosbisch + SOWL (8OWLS) — 2026*