senecaAIby Vindica
메뉴
제품개발자파일럿신뢰회사 소개투자자파일럿 신청EN
Seneca 스타터 키트쉬운 설명기술 문서

키트 버전 0.1.0

기술 문서

제품 A(예: 평가 앱)가 학습자 이벤트를 기록합니다. Seneca SDK가 제품 A 안에서 이를 변환하고, 허용 목록에 있는 가명 처리된 근거만 Seneca로 전송됩니다. 제품 B(예: 튜터링 앱)는 학습자의 권한 부여에 따라 한 가지 목적으로 Seneca에 맥락을 요청하고, 그것으로 무엇을 할지는 스스로 정합니다. 제품 A와 제품 B는 서로 연결되지 않습니다.

이 키트는 그 흐름을 가상 데이터로 보여 줍니다. 예시 네 가지(그중 하나는 글쓰기), 이 페이지와 Node에서 도는 참조 변환기, JSON Schema 세 개, 제품 B 예시가 들어 있습니다. 파일, 코드, 필드 이름은 영어로 제공됩니다.

샌드박스 평가 전용입니다. 가상 데이터만 사용하고, 운영 환경에서 쓰거나 재배포할 수 없습니다. 전체 조건: LICENSE.md(영문). 키트는 자체 교육용 형식을 씁니다. Seneca의 실제 연동 형식은 파일럿 계약에 따라 샌드박스에서 제공됩니다.

1. 빠른 시작

Node 18 이상. 설치, 의존성, 네트워크 호출이 없습니다.

README.md (영문)

zip은 8절의 파일로 브라우저에서 만들어집니다.

cd seneca-starter-kit
node kit/cli.mjs --check                                    # 모든 예시 실행, 모든 스키마 검사
node kit/cli.mjs examples/app-to-app/product-a-export.csv   # 파일 하나 변환
node kit/product-b-start.mjs                                # 맥락 파일로 첫 세션 계획
python python/product_b_start.py                            # 같은 예시, Python
node kit/cli.mjs --suggest your-export.csv > mapping.json   # 열 이름이 다른 CSV 매핑

2. 흐름

Product A ── raw events ──> SDK transform ── evidence ──> Seneca record
             (stays in A)   (runs inside A)   (sent)              │
                                                                   │ learner authorizes
                                                                   │ one recipient, one purpose
Product B <──────────────── context (summary + limits) ───────────┘

Product A x Product B: no connection, no shared learner IDs, no item-level rows.

3. 예시


3.1 제품 A 입력

취소선이 그어진 필드는 제품 A에 남습니다.

다운로드

3.2 근거 (이 페이지에서 계산)

위 입력에 kit/transform.mjs를 적용한 결과입니다. 남겨 둔 필드:

evidence.json다운로드

3.3 Seneca 기록 (예시)

형태를 보여 주려고 직접 작성한 예시입니다. Seneca가 해석과 확신도를 어떻게 정하는지는 다루지 않습니다.

seneca-record.json다운로드

3.4 제품 B의 요청과 맥락 (예시)

공개 엔드포인트는 없습니다. 맥락 읽기는 파일럿에서 연동마다 설정합니다. learner_ref가 기록의 것과 다르다는 점을 보십시오. 받는 곳마다 별도의 참조를 받습니다.

product-b-request.json
product-b-context.json다운로드

4. 입력 형식

형식판별 기준키트가 읽는 것
JSON 내보내기responses[]가 있는 객체export, student.id, session, skill_labels, skill_report[], 응답마다 question_id, skill_tag, outcome, points, max_points, seconds, attempt, hint_used 또는 assistance, answered_at
JSON 내보내기(글쓰기)submissions[]가 있는 객체export, student.id, assignments(label, genre, setting), criteria(label), 제출물마다 submission_id, assignment_id, draft, revises, submitted_at, word_count, ai_assistance, scores[](criterion, score, max, rater.role, scored_at)
JSON 행 배열평평한 객체의 배열CSV 행처럼 읽습니다. 키가 열이 됩니다(키트 이름과 다르면 열 매핑 사용). 중첩 객체를 담은 키는 남겨 둡니다.
CSV쉼표가 있는 머리글 행필수 learner_id, item_id, occurred_at; 선택 session_id, skill_tag, skill_label, aligned_to, item_type, outcome, points, max_points, seconds, attempt, assistance, setting, timed, self_rating
xAPI 2.0.0 / 1.0.3actor, verb, object가 있는 문(statement)account actor; ADL answered 또는 completed; result.success, result.score(raw/min/max), result.duration; 첫 category 활동을 기술로; registration을 세션으로
Caliper 1.2sensor와 data[]가 있는 봉투(envelope)AssessmentItemEvent(Completed), GradeEvent(Graded, Score 포함)

5. 변환 규칙

  1. 허용 목록만 읽습니다. 변환기가 읽지 않는 필드는 제품 A에 남고, 이유와 함께 이름으로 보고됩니다(identity, content, not needed for this purpose, not in the kit allowlist).
  2. 학습자·세션·문항 ID는 가명(lrn_, ses_, itm_)이 됩니다. 키트는 키 없는 데모 해시를 쓰며, 실제 참조는 키가 있고 받는 곳마다 다릅니다.
  3. 이메일 주소, 전화번호, 주민등록번호처럼 보이는 값이 있으면 아무것도 읽기 전에 거부합니다.
  4. 글쓰기: 글 자체는 나가지 않습니다. 에세이, 과제 문항, 코멘트는 남겨 둡니다. 모든 점수는 채점자(teacher, ai_grader, peer, self)의 판단으로 기록되며, 채점자 역할이 없는 점수는 거부합니다. 수정본은 같은 페이로드 안의 이전 초안을 가리켜야 합니다.
  5. 열 이름이 다른 CSV나 평평한 행 배열 JSON은 열 매핑(seneca-starter-mapping@0.1, 스키마)으로 읽을 수 있습니다. 어떤 열이 어떤 키트 필드인지, 값 표기를 어떻게 바꿀지(예: Right → correct), 시간대가 없는 시각에 어떤 시간대를 붙일지를 정합니다. 매핑하지 않은 열은 남습니다. 7절에서 해 보시거나 node kit/cli.mjs --suggest your-export.csv를 실행하십시오.
  6. 페이로드 하나에 학습자 한 명. 이벤트 2,000개, 1 MiB까지(Caliper 봉투는 이벤트 500개까지).
  7. 추측하지 않습니다. 정오 없는 점수는 not_reported, 자기 평가는 self_reported, 완료만 알린 이벤트는 completion_only, 보고되지 않은 도움 여부는 unknown으로 남습니다.
  8. 지원하지 않는 형태는 코드와 함께 실패합니다: UNSUPPORTED_VERB, UNSUPPORTED_ACTOR, UNSUPPORTED_EVENT, UNSUPPORTED_VERSION, MULTIPLE_LEARNERS, INVALID_FIELD, INVALID_TIME, INVALID_MAPPING, PERSONAL_DATA.

6. 출력 형식

형식만드는 곳스키마
seneca-starter-evidence@0.1변환기 (3.2)starter-evidence.schema.json
seneca-starter-record@0.1예시 (3.3)starter-record.schema.json
seneca-starter-context@0.1예시 (3.4)starter-context.schema.json
seneca-starter-mapping@0.1직접 작성 (7절 또는 --suggest)starter-mapping.schema.json
seneca-starter-context-preview@0.1previewContext(): 건수와 한계만없음

교육용 형식입니다. Seneca의 실제 연동 규약이 아닙니다.

7. 브라우저에서 돌려 보기

다섯 가지 형식 중 하나로 만든 가상 페이로드를 붙여 넣거나, 열 이름이 다른 CSV(또는 행 배열 JSON)를 붙여 넣고 열 매핑하기를 누르십시오. 변환은 이 탭 안에서 실행됩니다. 붙여 넣은 내용은 업로드되거나 저장되지 않습니다. 페이지가 보내는 것은 테스트 도구가 사용되었다는 익명 횟수뿐이며, 붙여 넣은 내용은 보내지 않습니다.

샘플을 불러오거나 페이로드를 붙여 넣은 뒤 "로컬에서 변환"을 누르십시오.

8. 파일

9. 현재 제공 범위

항목상태
Seneca 파트너 이벤트 형식파일럿. 승인된 파일럿 파트너에게 제공됩니다. 문서와 샌드박스 접근은 파일럿 계약과 함께 제공됩니다.
CSV 내보내기파일럿. 파일럿 기간에 파트너 이벤트 형식으로 매핑합니다.
xAPI 2.0.0, 1.0.3SDK 전용. 정해진 부분 집합(answered, completed 문)용 어댑터가 있습니다. 호스팅 수신은 아직 열려 있지 않습니다.
1EdTech Caliper 1.2SDK 전용. AssessmentItemEvent(Completed)와 GradeEvent(Graded)용 어댑터가 있습니다. 호스팅 수신은 아직 열려 있지 않습니다. 인증을 주장하지 않습니다.
제품 B의 맥락 읽기파일럿. 연동마다 설정합니다. 공개 엔드포인트는 없습니다.
MCP 기반 AI 어시스턴트운영 중. https://vindicaseneca.com/mcp에서 학습자가 승인한 범위로 본인의 Seneca 기록을 읽습니다. 개발자 페이지 참고.
이 키트의 형식교육용. 실제 연동 규약이 아닙니다.

10. 파일럿 전에 준비할 것

첫 통화 전에 아래를 준비해 주십시오. 실제 학생 데이터는 필요하지 않습니다.

  1. 시작할 이벤트 한 종류(예: 진단 테스트의 응답 문항)와, 실제 형식으로 만든 가상의 내보내기 파일. CSV라면 7절의 mapping.json도 함께 첨부해 주십시오.
  2. 학습자를 식별하는 방법(이름이나 이메일이 아닌 계정 ID)과, 귀사 앱의 어디에서 학습자가 Seneca를 연결하게 될지.
  3. 방향: 근거를 보내는지, 첫 세션을 위해 맥락을 읽는지, 둘 다인지. 읽는 경우라면 요청할 목적 하나.
  4. 학습자는 누구인지: 연령대와 거주 국가. 동의 규칙은 연령과 국가에 따라 다릅니다.
  5. 귀사 쪽 담당자와 파일럿을 시작하고 싶은 시기.

11. 문의

연동 검토, 매핑용 가상 예시 전달, 샌드박스 접근이 포함된 유료 파일럿 상담은 kevinchoi@vindicaseneca.com으로 연락 주십시오. 가상 데이터만 보내 주십시오.

방문과 도구 사용 횟수만 익명으로 셉니다. 쿠키나 식별자를 쓰지 않고, 입력하거나 붙여 넣은 내용은 절대 보내지 않습니다. Global Privacy Control이나 Do Not Track을 보내는 브라우저는 세지 않습니다.