--- name: cc-transcript description: > Typed events for Claude Code transcripts: discovery, a superset JSONL parser (Python + Rust), and ingestion-state tracking. Use when writing Python code that uses the cc_transcript package. license: PolyForm-Noncommercial-1.0.0 compatibility: Requires Python >=3.13. --- # cc-transcript Typed events for Claude Code transcripts: discovery, a superset JSONL parser (Python + Rust), and ingestion-state tracking. ## Installation ```bash pip install cc-transcript ``` ## API overview ### Classes Core classes - `TranscriptDiscovery`: Locates Claude Code transcript files on disk - `TranscriptParser`: The public facade over the active parsing backend - `FileStateStore`: Tracks which transcript files have been ingested, keyed by mtime - `rust.RustBackend` - `parser.PythonBackend` - `sentiment.NLP` - `sentiment.ConversationBucketer` - `sentiment.Lexicon` ### FileStateStore Methods Methods for the FileStateStore class - `FileStateStore.open` - `FileStateStore.close` - `FileStateStore.__aenter__` - `FileStateStore.__aexit__` - `FileStateStore.transaction` - `FileStateStore.file_mtimes` - `FileStateStore.record_file` - `FileStateStore.upsert_file` ### Dataclasses Data-holding classes - `ParsedTranscript`: The parsed events of a single transcript file - `FilterConfig`: Opt-in, consumer-side filtering of a transcript event stream - `FilterSpec`: An ordered list of :class:`Clause` rules applied to an event stream - `AssistantEvent`: An assistant turn - `EntryMeta`: Envelope metadata shared by the conversational transcript events - `ModeEvent`: A mode or permission-mode change marker - `OtherEvent`: Any recognized entry without a guaranteed conversational envelope - `SystemEvent`: A system entry, such as a hook summary or notice - `TextBlock`: A text content block from a user or assistant message - `ThinkingBlock`: An extended-thinking content block emitted by the assistant - `ToolResultBlock`: The result of a tool invocation, delivered in a user turn - `ToolUseBlock`: An assistant request to invoke a tool - `UserEvent`: A user turn - `filters.Clause` - `filters.EntrypointIn` - `filters.KindIs` - `filters.MetaFlag` - `filters.ModelIs` - `filters.TextEmpty` - `filters.TextMatchesAny` - `builders.Clause` - `builders.EntrypointIn` - `builders.KindIs` - `builders.MetaFlag` - `builders.ModelIs` - `builders.TextEmpty` - `builders.TextInSet` - `builders.TextMatchesAny` - `builders.WordCountAtMost` - `filterspec.KindIs` - `filterspec.MetaFlag` - `filterspec.EntrypointIn` - `filterspec.ModelIs` - `filterspec.TextEmpty` - `filterspec.TextMatchesAny` - `filterspec.TextInSet` - `filterspec.WordCountAtMost` - `filterspec.Clause` - `sentiment.FilteredEngine` - `sentiment.FrustrationShortCircuit` - `sentiment.MildIrritationDemote` - `sentiment.PositiveClamp` - `sentiment.ResumeClamp` - `sentiment.ScoreSpec` ### Protocols Structural typing protocols - `Backend`: A transcript-parsing backend - `sentiment.InferenceEngine` ### Enumerations Enum types - `filterspec.Action` ### Named Tuples NamedTuple types - `AssistantMessage`: An assistant turn distilled for analysis: its text, tool calls, and responding model - `ToolCall`: A single tool invocation within a message: the tool ``name`` and optional target file path - `UserMessage`: A user turn distilled for analysis: its text, tool calls, and authoring metadata - `sentiment.BucketKey` - `sentiment.ConversationBucket` ### Functions Public functions - `build_spec`: Flattens ``Clause`` / ``tuple[Clause, ...]`` fragments into a :class:`FilterSpec` - `drop_compacted`: Drops compaction-summary and transcript-only entries - `drop_empty`: Drops blank events of one kind - `drop_entrypoints`: Drops events whose ``meta.entrypoint`` is in ``entrypoints`` - `drop_junk`: Drops events matching any group in the named :data:`JUNK_CATEGORIES` - `drop_meta_flag`: Drops events whose ``EntryMeta`` boolean ``flag`` is set - `drop_phrases`: Drops events whose normalized text is one of ``phrases`` - `drop_short`: Drops events with at most ``max_words`` whitespace-split words - `drop_sidechain`: Drops sidechain events; ``except_assistants`` keeps assistant sidechains - `drop_synthetic`: Drops assistant events with the ```` model - `keep_only`: Drops every event whose kind is not in ``kinds`` - `apply_filters`: Yields the events that survive ``config`` - `annotate_spec`: Yields ``(event, labels)`` for events surviving ``spec``, with TAG labels - `apply_spec`: Yields the events that survive every ``DROP`` clause of ``spec`` - `keep`: Returns whether ``event`` survives every ``DROP`` clause of ``spec`` - `labels_for`: Returns the TAG labels ``spec`` records for ``event``, in clause order - `parse_event` - `parse_events_from_bytes` - `rust.is_portable` - `rust.spec_to_json` - `filters.compile_groups` - `parser.parse_meta` - `parser.flatten_result_content` - `parser.parse_user_blocks` - `parser.parse_assistant_blocks` - `parser.parse_assistant_block` - `parser.decode_line` - `parser.parse_one` - `parser.parse_one_filtered` - `parser.load_rust_backend` - `filterspec.compile_groups` - `filterspec.event_kind` - `filterspec.event_text` - `filterspec.event_meta` - `filterspec.normalize_bare` - `filterspec.predicate_matches` - `filterspec.meta_flag` - `filterspec.clause_matches` - `filterspec.is_portable` - `filterspec.clause_portable` - `filterspec.spec_to_json` - `filterspec.clause_to_dict` - `filterspec.predicate_to_dict` - `sentiment.NOOP_PROGRESS` - `sentiment.build_score_spec` - `sentiment.clamp_positive` - `sentiment.clamp_resume` - `sentiment.demote_mild_irritation` - `sentiment.extract_bucket_keys` - `sentiment.flag_frustration` ### Async Functions Asynchronous functions - `parse_events_async` ### Constants Module-level constants and data - `CcVersion`: NewType creates simple unique types with almost zero runtime overhead - `EntryUuid`: NewType creates simple unique types with almost zero runtime overhead - `SessionId`: NewType creates simple unique types with almost zero runtime overhead - `ToolUseId`: NewType creates simple unique types with almost zero runtime overhead - `store.FILE_SCHEMA` - `discovery.CLAUDE_PROJECTS_DIR` - `models.ContentBlock` - `models.TranscriptEvent` - `messages.BaseMessage` - `messages.TranscriptMessage` - `filters.ASSISTANTS` - `filters.SENTIMENT_JUNK_GROUPS` - `filters.USERS` - `filters.EventKind` - `filters.TranscriptEvent` - `filters.JUNK_USER_MESSAGE_RE` - `filters.KIND_BY_TYPE` - `builders.ASSISTANTS` - `builders.JUNK_CATEGORIES` - `builders.USERS` - `builders.EventKind` - `builders.MetaFlagName` - `builders.NOISE_SPEC` - `parser.ContentBlock` - `parser.TranscriptEvent` - `parser.INTERRUPT_MARKER` - `parser.build_event` - `backend.TranscriptEvent` - `filterspec.TranscriptEvent` - `filterspec.EventKind` - `filterspec.MetaFlagName` - `filterspec.TRAILING_PUNCT` - `filterspec.STRUCTURAL_TAG_GROUP` - `filterspec.STRUCTURAL_GROUPS` - `filterspec.AGENT_INJECTION_GROUPS` - `filterspec.INTERRUPT_MARKER_GROUPS` - `filterspec.STOP_HOOK_GROUPS` - `filterspec.CONTINUATION_GROUPS` - `filterspec.COMMAND_ECHO_GROUPS` - `filterspec.JUNK_CATEGORIES` - `filterspec.STRUCTURAL_NOISE_GROUPS` - `filterspec.SENTIMENT_JUNK_GROUPS` - `filterspec.FRUSTRATION_GROUPS` - `filterspec.MILD_IMPATIENCE_GROUPS` - `filterspec.PORTABLE_GROUP_NAMES` - `filterspec.RESUME_PHRASE_SET` - `filterspec.TRIVIAL_ACK_SET` - `filterspec.SHORT_MESSAGE_MAX_WORDS` - `filterspec.CONVERSATIONAL` - `filterspec.USERS` - `filterspec.ASSISTANTS` - `filterspec.Predicate` - `filterspec.STRUCTURAL_NOISE_RE` - `filterspec.INTERRUPT_MARKER_RE` - `filterspec.STOP_HOOK_RE` - `sentiment.BUCKET_MINUTES` - `sentiment.MIN_USER_CHARS` - `sentiment.MIN_USER_TURNS_PER_SESSION` - `sentiment.BaseMessage` - `sentiment.BucketIndex` - `sentiment.ScoreStage` - `sentiment.SentimentScore` - `sentiment.TranscriptMessage` ### Other Additional exports - `domains` ## Resources - [Full documentation](https://yasyf.github.io/cc-transcript/) - [llms.txt](llms.txt) — Indexed API reference for LLMs - [llms-full.txt](llms-full.txt) — Comprehensive documentation for LLMs - [Source code](https://github.com/yasyf/cc-transcript)