# cc_transcript

> Typed events for Claude Code transcripts: discovery, a superset JSONL parser (Python + Rust), and ingestion-state tracking.

## Docs

### API Reference

#### Classes
> Core classes

- [TranscriptDiscovery](https://yasyf.github.io/cc-transcript/reference/TranscriptDiscovery.html): Locates Claude Code transcript files on disk
- [TranscriptParser](https://yasyf.github.io/cc-transcript/reference/TranscriptParser.html): The public facade over the active parsing backend
- [FileStateStore](https://yasyf.github.io/cc-transcript/reference/FileStateStore.html): Tracks which transcript files have been ingested, keyed by mtime
- [rust.RustBackend](https://yasyf.github.io/cc-transcript/reference/rust.RustBackend.html)
- [parser.PythonBackend](https://yasyf.github.io/cc-transcript/reference/parser.PythonBackend.html)
- [sentiment.NLP](https://yasyf.github.io/cc-transcript/reference/sentiment.NLP.html)
- [sentiment.ConversationBucketer](https://yasyf.github.io/cc-transcript/reference/sentiment.ConversationBucketer.html)
- [sentiment.Lexicon](https://yasyf.github.io/cc-transcript/reference/sentiment.Lexicon.html)

#### FileStateStore Methods
> Methods for the FileStateStore class

- [FileStateStore.open](https://yasyf.github.io/cc-transcript/reference/FileStateStore.open.html)
- [FileStateStore.close](https://yasyf.github.io/cc-transcript/reference/FileStateStore.close.html)
- [FileStateStore.__aenter__](https://yasyf.github.io/cc-transcript/reference/FileStateStore.__aenter__.html)
- [FileStateStore.__aexit__](https://yasyf.github.io/cc-transcript/reference/FileStateStore.__aexit__.html)
- [FileStateStore.transaction](https://yasyf.github.io/cc-transcript/reference/FileStateStore.transaction.html)
- [FileStateStore.file_mtimes](https://yasyf.github.io/cc-transcript/reference/FileStateStore.file_mtimes.html)
- [FileStateStore.record_file](https://yasyf.github.io/cc-transcript/reference/FileStateStore.record_file.html)
- [FileStateStore.upsert_file](https://yasyf.github.io/cc-transcript/reference/FileStateStore.upsert_file.html)

#### Dataclasses
> Data-holding classes

- [ParsedTranscript](https://yasyf.github.io/cc-transcript/reference/ParsedTranscript.html): The parsed events of a single transcript file
- [FilterConfig](https://yasyf.github.io/cc-transcript/reference/FilterConfig.html): Opt-in, consumer-side filtering of a transcript event stream
- [FilterSpec](https://yasyf.github.io/cc-transcript/reference/FilterSpec.html): An ordered list of :class:`Clause` rules applied to an event stream
- [AssistantEvent](https://yasyf.github.io/cc-transcript/reference/AssistantEvent.html): An assistant turn
- [EntryMeta](https://yasyf.github.io/cc-transcript/reference/EntryMeta.html): Envelope metadata shared by the conversational transcript events
- [ModeEvent](https://yasyf.github.io/cc-transcript/reference/ModeEvent.html): A mode or permission-mode change marker
- [OtherEvent](https://yasyf.github.io/cc-transcript/reference/OtherEvent.html): Any recognized entry without a guaranteed conversational envelope
- [SystemEvent](https://yasyf.github.io/cc-transcript/reference/SystemEvent.html): A system entry, such as a hook summary or notice
- [TextBlock](https://yasyf.github.io/cc-transcript/reference/TextBlock.html): A text content block from a user or assistant message
- [ThinkingBlock](https://yasyf.github.io/cc-transcript/reference/ThinkingBlock.html): An extended-thinking content block emitted by the assistant
- [ToolResultBlock](https://yasyf.github.io/cc-transcript/reference/ToolResultBlock.html): The result of a tool invocation, delivered in a user turn
- [ToolUseBlock](https://yasyf.github.io/cc-transcript/reference/ToolUseBlock.html): An assistant request to invoke a tool
- [UserEvent](https://yasyf.github.io/cc-transcript/reference/UserEvent.html): A user turn
- [filterspec.KindIs](https://yasyf.github.io/cc-transcript/reference/filterspec.KindIs.html)
- [filterspec.MetaFlag](https://yasyf.github.io/cc-transcript/reference/filterspec.MetaFlag.html)
- [filterspec.EntrypointIn](https://yasyf.github.io/cc-transcript/reference/filterspec.EntrypointIn.html)
- [filterspec.ModelIs](https://yasyf.github.io/cc-transcript/reference/filterspec.ModelIs.html)
- [filterspec.TextEmpty](https://yasyf.github.io/cc-transcript/reference/filterspec.TextEmpty.html)
- [filterspec.TextMatchesAny](https://yasyf.github.io/cc-transcript/reference/filterspec.TextMatchesAny.html)
- [filterspec.TextInSet](https://yasyf.github.io/cc-transcript/reference/filterspec.TextInSet.html)
- [filterspec.WordCountAtMost](https://yasyf.github.io/cc-transcript/reference/filterspec.WordCountAtMost.html)
- [filterspec.Clause](https://yasyf.github.io/cc-transcript/reference/filterspec.Clause.html)
- [builders.Clause](https://yasyf.github.io/cc-transcript/reference/builders.Clause.html)
- [builders.EntrypointIn](https://yasyf.github.io/cc-transcript/reference/builders.EntrypointIn.html)
- [builders.KindIs](https://yasyf.github.io/cc-transcript/reference/builders.KindIs.html)
- [builders.MetaFlag](https://yasyf.github.io/cc-transcript/reference/builders.MetaFlag.html)
- [builders.ModelIs](https://yasyf.github.io/cc-transcript/reference/builders.ModelIs.html)
- [builders.TextEmpty](https://yasyf.github.io/cc-transcript/reference/builders.TextEmpty.html)
- [builders.TextInSet](https://yasyf.github.io/cc-transcript/reference/builders.TextInSet.html)
- [builders.TextMatchesAny](https://yasyf.github.io/cc-transcript/reference/builders.TextMatchesAny.html)
- [builders.WordCountAtMost](https://yasyf.github.io/cc-transcript/reference/builders.WordCountAtMost.html)
- [filters.Clause](https://yasyf.github.io/cc-transcript/reference/filters.Clause.html)
- [filters.EntrypointIn](https://yasyf.github.io/cc-transcript/reference/filters.EntrypointIn.html)
- [filters.KindIs](https://yasyf.github.io/cc-transcript/reference/filters.KindIs.html)
- [filters.MetaFlag](https://yasyf.github.io/cc-transcript/reference/filters.MetaFlag.html)
- [filters.ModelIs](https://yasyf.github.io/cc-transcript/reference/filters.ModelIs.html)
- [filters.TextEmpty](https://yasyf.github.io/cc-transcript/reference/filters.TextEmpty.html)
- [filters.TextMatchesAny](https://yasyf.github.io/cc-transcript/reference/filters.TextMatchesAny.html)
- [sentiment.FilteredEngine](https://yasyf.github.io/cc-transcript/reference/sentiment.FilteredEngine.html)
- [sentiment.FrustrationShortCircuit](https://yasyf.github.io/cc-transcript/reference/sentiment.FrustrationShortCircuit.html)
- [sentiment.MildIrritationDemote](https://yasyf.github.io/cc-transcript/reference/sentiment.MildIrritationDemote.html)
- [sentiment.PositiveClamp](https://yasyf.github.io/cc-transcript/reference/sentiment.PositiveClamp.html)
- [sentiment.ResumeClamp](https://yasyf.github.io/cc-transcript/reference/sentiment.ResumeClamp.html)
- [sentiment.ScoreSpec](https://yasyf.github.io/cc-transcript/reference/sentiment.ScoreSpec.html)

#### Protocols
> Structural typing protocols

- [Backend](https://yasyf.github.io/cc-transcript/reference/Backend.html): A transcript-parsing backend
- [sentiment.InferenceEngine](https://yasyf.github.io/cc-transcript/reference/sentiment.InferenceEngine.html)

#### Enumerations
> Enum types

- [filterspec.Action](https://yasyf.github.io/cc-transcript/reference/filterspec.Action.html)

#### Named Tuples
> NamedTuple types

- [AssistantMessage](https://yasyf.github.io/cc-transcript/reference/AssistantMessage.html): An assistant turn distilled for analysis: its text, tool calls, and responding model
- [ToolCall](https://yasyf.github.io/cc-transcript/reference/ToolCall.html): A single tool invocation within a message: the tool ``name`` and optional target file path
- [UserMessage](https://yasyf.github.io/cc-transcript/reference/UserMessage.html): A user turn distilled for analysis: its text, tool calls, and authoring metadata
- [sentiment.BucketKey](https://yasyf.github.io/cc-transcript/reference/sentiment.BucketKey.html)
- [sentiment.ConversationBucket](https://yasyf.github.io/cc-transcript/reference/sentiment.ConversationBucket.html)

#### Functions
> Public functions

- [build_spec](https://yasyf.github.io/cc-transcript/reference/build_spec.html): Flattens ``Clause`` / ``tuple[Clause, ...]`` fragments into a :class:`FilterSpec`
- [drop_compacted](https://yasyf.github.io/cc-transcript/reference/drop_compacted.html): Drops compaction-summary and transcript-only entries
- [drop_empty](https://yasyf.github.io/cc-transcript/reference/drop_empty.html): Drops blank events of one kind
- [drop_entrypoints](https://yasyf.github.io/cc-transcript/reference/drop_entrypoints.html): Drops events whose ``meta.entrypoint`` is in ``entrypoints``
- [drop_junk](https://yasyf.github.io/cc-transcript/reference/drop_junk.html): Drops events matching any group in the named :data:`JUNK_CATEGORIES`
- [drop_meta_flag](https://yasyf.github.io/cc-transcript/reference/drop_meta_flag.html): Drops events whose ``EntryMeta`` boolean ``flag`` is set
- [drop_phrases](https://yasyf.github.io/cc-transcript/reference/drop_phrases.html): Drops events whose normalized text is one of ``phrases``
- [drop_short](https://yasyf.github.io/cc-transcript/reference/drop_short.html): Drops events with at most ``max_words`` whitespace-split words
- [drop_sidechain](https://yasyf.github.io/cc-transcript/reference/drop_sidechain.html): Drops sidechain events; ``except_assistants`` keeps assistant sidechains
- [drop_synthetic](https://yasyf.github.io/cc-transcript/reference/drop_synthetic.html): Drops assistant events with the ``<synthetic>`` model
- [keep_only](https://yasyf.github.io/cc-transcript/reference/keep_only.html): Drops every event whose kind is not in ``kinds``
- [apply_filters](https://yasyf.github.io/cc-transcript/reference/apply_filters.html): Yields the events that survive ``config``
- [annotate_spec](https://yasyf.github.io/cc-transcript/reference/annotate_spec.html): Yields ``(event, labels)`` for events surviving ``spec``, with TAG labels
- [apply_spec](https://yasyf.github.io/cc-transcript/reference/apply_spec.html): Yields the events that survive every ``DROP`` clause of ``spec``
- [keep](https://yasyf.github.io/cc-transcript/reference/keep.html): Returns whether ``event`` survives every ``DROP`` clause of ``spec``
- [labels_for](https://yasyf.github.io/cc-transcript/reference/labels_for.html): Returns the TAG labels ``spec`` records for ``event``, in clause order
- [parse_event](https://yasyf.github.io/cc-transcript/reference/parse_event.html)
- [parse_events_from_bytes](https://yasyf.github.io/cc-transcript/reference/parse_events_from_bytes.html)
- [rust.is_portable](https://yasyf.github.io/cc-transcript/reference/rust.is_portable.html)
- [rust.spec_to_json](https://yasyf.github.io/cc-transcript/reference/rust.spec_to_json.html)
- [parser.parse_meta](https://yasyf.github.io/cc-transcript/reference/parser.parse_meta.html)
- [parser.flatten_result_content](https://yasyf.github.io/cc-transcript/reference/parser.flatten_result_content.html)
- [parser.parse_user_blocks](https://yasyf.github.io/cc-transcript/reference/parser.parse_user_blocks.html)
- [parser.parse_assistant_blocks](https://yasyf.github.io/cc-transcript/reference/parser.parse_assistant_blocks.html)
- [parser.parse_assistant_block](https://yasyf.github.io/cc-transcript/reference/parser.parse_assistant_block.html)
- [parser.decode_line](https://yasyf.github.io/cc-transcript/reference/parser.decode_line.html)
- [parser.parse_one](https://yasyf.github.io/cc-transcript/reference/parser.parse_one.html)
- [parser.parse_one_filtered](https://yasyf.github.io/cc-transcript/reference/parser.parse_one_filtered.html)
- [parser.load_rust_backend](https://yasyf.github.io/cc-transcript/reference/parser.load_rust_backend.html)
- [filterspec.compile_groups](https://yasyf.github.io/cc-transcript/reference/filterspec.compile_groups.html)
- [filterspec.event_kind](https://yasyf.github.io/cc-transcript/reference/filterspec.event_kind.html)
- [filterspec.event_text](https://yasyf.github.io/cc-transcript/reference/filterspec.event_text.html)
- [filterspec.event_meta](https://yasyf.github.io/cc-transcript/reference/filterspec.event_meta.html)
- [filterspec.normalize_bare](https://yasyf.github.io/cc-transcript/reference/filterspec.normalize_bare.html)
- [filterspec.predicate_matches](https://yasyf.github.io/cc-transcript/reference/filterspec.predicate_matches.html)
- [filterspec.meta_flag](https://yasyf.github.io/cc-transcript/reference/filterspec.meta_flag.html)
- [filterspec.clause_matches](https://yasyf.github.io/cc-transcript/reference/filterspec.clause_matches.html)
- [filterspec.is_portable](https://yasyf.github.io/cc-transcript/reference/filterspec.is_portable.html)
- [filterspec.clause_portable](https://yasyf.github.io/cc-transcript/reference/filterspec.clause_portable.html)
- [filterspec.spec_to_json](https://yasyf.github.io/cc-transcript/reference/filterspec.spec_to_json.html)
- [filterspec.clause_to_dict](https://yasyf.github.io/cc-transcript/reference/filterspec.clause_to_dict.html)
- [filterspec.predicate_to_dict](https://yasyf.github.io/cc-transcript/reference/filterspec.predicate_to_dict.html)
- [filters.compile_groups](https://yasyf.github.io/cc-transcript/reference/filters.compile_groups.html)
- [sentiment.NOOP_PROGRESS](https://yasyf.github.io/cc-transcript/reference/sentiment.NOOP_PROGRESS.html)
- [sentiment.build_score_spec](https://yasyf.github.io/cc-transcript/reference/sentiment.build_score_spec.html)
- [sentiment.clamp_positive](https://yasyf.github.io/cc-transcript/reference/sentiment.clamp_positive.html)
- [sentiment.clamp_resume](https://yasyf.github.io/cc-transcript/reference/sentiment.clamp_resume.html)
- [sentiment.demote_mild_irritation](https://yasyf.github.io/cc-transcript/reference/sentiment.demote_mild_irritation.html)
- [sentiment.extract_bucket_keys](https://yasyf.github.io/cc-transcript/reference/sentiment.extract_bucket_keys.html)
- [sentiment.flag_frustration](https://yasyf.github.io/cc-transcript/reference/sentiment.flag_frustration.html)

#### Async Functions
> Asynchronous functions

- [parse_events_async](https://yasyf.github.io/cc-transcript/reference/parse_events_async.html)

#### Constants
> Module-level constants and data

- [CcVersion](https://yasyf.github.io/cc-transcript/reference/CcVersion.html): NewType creates simple unique types with almost zero runtime overhead
- [EntryUuid](https://yasyf.github.io/cc-transcript/reference/EntryUuid.html): NewType creates simple unique types with almost zero runtime overhead
- [SessionId](https://yasyf.github.io/cc-transcript/reference/SessionId.html): NewType creates simple unique types with almost zero runtime overhead
- [ToolUseId](https://yasyf.github.io/cc-transcript/reference/ToolUseId.html): NewType creates simple unique types with almost zero runtime overhead
- [parser.ContentBlock](https://yasyf.github.io/cc-transcript/reference/parser.ContentBlock.html)
- [parser.TranscriptEvent](https://yasyf.github.io/cc-transcript/reference/parser.TranscriptEvent.html)
- [parser.INTERRUPT_MARKER](https://yasyf.github.io/cc-transcript/reference/parser.INTERRUPT_MARKER.html)
- [parser.build_event](https://yasyf.github.io/cc-transcript/reference/parser.build_event.html)
- [models.ContentBlock](https://yasyf.github.io/cc-transcript/reference/models.ContentBlock.html)
- [models.TranscriptEvent](https://yasyf.github.io/cc-transcript/reference/models.TranscriptEvent.html)
- [filterspec.TranscriptEvent](https://yasyf.github.io/cc-transcript/reference/filterspec.TranscriptEvent.html)
- [filterspec.EventKind](https://yasyf.github.io/cc-transcript/reference/filterspec.EventKind.html)
- [filterspec.MetaFlagName](https://yasyf.github.io/cc-transcript/reference/filterspec.MetaFlagName.html)
- [filterspec.TRAILING_PUNCT](https://yasyf.github.io/cc-transcript/reference/filterspec.TRAILING_PUNCT.html)
- [filterspec.STRUCTURAL_TAG_GROUP](https://yasyf.github.io/cc-transcript/reference/filterspec.STRUCTURAL_TAG_GROUP.html)
- [filterspec.STRUCTURAL_GROUPS](https://yasyf.github.io/cc-transcript/reference/filterspec.STRUCTURAL_GROUPS.html)
- [filterspec.AGENT_INJECTION_GROUPS](https://yasyf.github.io/cc-transcript/reference/filterspec.AGENT_INJECTION_GROUPS.html)
- [filterspec.INTERRUPT_MARKER_GROUPS](https://yasyf.github.io/cc-transcript/reference/filterspec.INTERRUPT_MARKER_GROUPS.html)
- [filterspec.STOP_HOOK_GROUPS](https://yasyf.github.io/cc-transcript/reference/filterspec.STOP_HOOK_GROUPS.html)
- [filterspec.CONTINUATION_GROUPS](https://yasyf.github.io/cc-transcript/reference/filterspec.CONTINUATION_GROUPS.html)
- [filterspec.COMMAND_ECHO_GROUPS](https://yasyf.github.io/cc-transcript/reference/filterspec.COMMAND_ECHO_GROUPS.html)
- [filterspec.JUNK_CATEGORIES](https://yasyf.github.io/cc-transcript/reference/filterspec.JUNK_CATEGORIES.html)
- [filterspec.STRUCTURAL_NOISE_GROUPS](https://yasyf.github.io/cc-transcript/reference/filterspec.STRUCTURAL_NOISE_GROUPS.html)
- [filterspec.SENTIMENT_JUNK_GROUPS](https://yasyf.github.io/cc-transcript/reference/filterspec.SENTIMENT_JUNK_GROUPS.html)
- [filterspec.FRUSTRATION_GROUPS](https://yasyf.github.io/cc-transcript/reference/filterspec.FRUSTRATION_GROUPS.html)
- [filterspec.MILD_IMPATIENCE_GROUPS](https://yasyf.github.io/cc-transcript/reference/filterspec.MILD_IMPATIENCE_GROUPS.html)
- [filterspec.PORTABLE_GROUP_NAMES](https://yasyf.github.io/cc-transcript/reference/filterspec.PORTABLE_GROUP_NAMES.html)
- [filterspec.RESUME_PHRASE_SET](https://yasyf.github.io/cc-transcript/reference/filterspec.RESUME_PHRASE_SET.html)
- [filterspec.TRIVIAL_ACK_SET](https://yasyf.github.io/cc-transcript/reference/filterspec.TRIVIAL_ACK_SET.html)
- [filterspec.SHORT_MESSAGE_MAX_WORDS](https://yasyf.github.io/cc-transcript/reference/filterspec.SHORT_MESSAGE_MAX_WORDS.html)
- [filterspec.CONVERSATIONAL](https://yasyf.github.io/cc-transcript/reference/filterspec.CONVERSATIONAL.html)
- [filterspec.USERS](https://yasyf.github.io/cc-transcript/reference/filterspec.USERS.html)
- [filterspec.ASSISTANTS](https://yasyf.github.io/cc-transcript/reference/filterspec.ASSISTANTS.html)
- [filterspec.Predicate](https://yasyf.github.io/cc-transcript/reference/filterspec.Predicate.html)
- [filterspec.STRUCTURAL_NOISE_RE](https://yasyf.github.io/cc-transcript/reference/filterspec.STRUCTURAL_NOISE_RE.html)
- [filterspec.INTERRUPT_MARKER_RE](https://yasyf.github.io/cc-transcript/reference/filterspec.INTERRUPT_MARKER_RE.html)
- [filterspec.STOP_HOOK_RE](https://yasyf.github.io/cc-transcript/reference/filterspec.STOP_HOOK_RE.html)
- [backend.TranscriptEvent](https://yasyf.github.io/cc-transcript/reference/backend.TranscriptEvent.html)
- [builders.ASSISTANTS](https://yasyf.github.io/cc-transcript/reference/builders.ASSISTANTS.html)
- [builders.JUNK_CATEGORIES](https://yasyf.github.io/cc-transcript/reference/builders.JUNK_CATEGORIES.html)
- [builders.USERS](https://yasyf.github.io/cc-transcript/reference/builders.USERS.html)
- [builders.EventKind](https://yasyf.github.io/cc-transcript/reference/builders.EventKind.html)
- [builders.MetaFlagName](https://yasyf.github.io/cc-transcript/reference/builders.MetaFlagName.html)
- [builders.NOISE_SPEC](https://yasyf.github.io/cc-transcript/reference/builders.NOISE_SPEC.html)
- [store.FILE_SCHEMA](https://yasyf.github.io/cc-transcript/reference/store.FILE_SCHEMA.html)
- [discovery.CLAUDE_PROJECTS_DIR](https://yasyf.github.io/cc-transcript/reference/discovery.CLAUDE_PROJECTS_DIR.html)
- [filters.ASSISTANTS](https://yasyf.github.io/cc-transcript/reference/filters.ASSISTANTS.html)
- [filters.SENTIMENT_JUNK_GROUPS](https://yasyf.github.io/cc-transcript/reference/filters.SENTIMENT_JUNK_GROUPS.html)
- [filters.USERS](https://yasyf.github.io/cc-transcript/reference/filters.USERS.html)
- [filters.EventKind](https://yasyf.github.io/cc-transcript/reference/filters.EventKind.html)
- [filters.TranscriptEvent](https://yasyf.github.io/cc-transcript/reference/filters.TranscriptEvent.html)
- [filters.JUNK_USER_MESSAGE_RE](https://yasyf.github.io/cc-transcript/reference/filters.JUNK_USER_MESSAGE_RE.html)
- [filters.KIND_BY_TYPE](https://yasyf.github.io/cc-transcript/reference/filters.KIND_BY_TYPE.html)
- [messages.BaseMessage](https://yasyf.github.io/cc-transcript/reference/messages.BaseMessage.html)
- [messages.TranscriptMessage](https://yasyf.github.io/cc-transcript/reference/messages.TranscriptMessage.html)
- [sentiment.BUCKET_MINUTES](https://yasyf.github.io/cc-transcript/reference/sentiment.BUCKET_MINUTES.html)
- [sentiment.MIN_USER_CHARS](https://yasyf.github.io/cc-transcript/reference/sentiment.MIN_USER_CHARS.html)
- [sentiment.MIN_USER_TURNS_PER_SESSION](https://yasyf.github.io/cc-transcript/reference/sentiment.MIN_USER_TURNS_PER_SESSION.html)
- [sentiment.BaseMessage](https://yasyf.github.io/cc-transcript/reference/sentiment.BaseMessage.html)
- [sentiment.BucketIndex](https://yasyf.github.io/cc-transcript/reference/sentiment.BucketIndex.html)
- [sentiment.ScoreStage](https://yasyf.github.io/cc-transcript/reference/sentiment.ScoreStage.html)
- [sentiment.SentimentScore](https://yasyf.github.io/cc-transcript/reference/sentiment.SentimentScore.html)
- [sentiment.TranscriptMessage](https://yasyf.github.io/cc-transcript/reference/sentiment.TranscriptMessage.html)

#### Other
> Additional exports

- [domains](https://yasyf.github.io/cc-transcript/reference/domains.html)