Skip to content

feat(classify): classify an asset or a text with the decision model - #494

Merged
adeelahmad merged 1 commit into
mainfrom
claude/project-thread-26l27n
Oct 17, 2026
Merged

adeelahmad merged 1 commit into
mainfrom
claude/project-thread-26l27n

Conversation

@adeelahmad

Copy link
Copy Markdown
Owner

Requested by Adeel · project thread

Description

Before: the decision model (decide.choose: Jev, Laya or the LLM) picked a namespace and a few other routine things inside Lens, but an agent couldn't ask it anything. To label an asset ("which desk does this go to?", "what content type is this?", "which topic is it about?"), an agent had to write its own prompt.

After: one core classify service, used by the API (POST /api/v1/classify), the MCP server (classify) and the assistant (classify). It says which of some labels fits an asset or a piece of text, how sure it is, and ranks every label. The labels can be:

  • labels you give: a list (["science", "sport: games and teams"], with an optional meaning after : ) or {label: meaning}, 2 to 60 of them;
  • Lens's content types of the asset's base type (vocabulary: content_type);
  • the namespace's topics, with their definitions and other labels (vocabulary: topic), the most used first.

The decision model answers when it's set up, else the language model. by says which one answered, and every call is in the activity ledger, counted for the asset and its namespace. With apply (editors only), a sure answer acts:

  • it sets the content type;
  • or suggests the topic, which waits for someone to accept it;
  • or adds the label as a tag.

"Sure" means decisions.act_above, 0.8 by default. An answer that isn't sure changes nothing, and neither does a topic the asset already has. Applying is audited (recording.classify). MCP and the assistant only read.

Motivation and Context

Adeel asked for core services that agents and workflows can use: classify, plus find by face, voice, entity, type, content type, date and other attributes. Find merged in #398. This PR is classify. A Classify node for workflows follows in its own PR.

How: domain/classify.py builds the options from the given labels or a vocabulary (content_types.all_types, topics). It describes the asset with its title, file, kind, length, language, tags, accepted topics, summary, most-mentioned entities and the start of its text. The archive's words are wrapped with untrusted.wrap, so instructions in them are read as data. It then calls decide.choose inside activity.scope and acts through the existing content_types.choose, topics.propose and library.retag.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change; ! in the title)

Checklist:

  • The title is a Conventional Commit.
  • My code follows the code style of this project (make hooks checks it on commit).
  • I added or updated tests.
  • My change requires documentation updates, and I have updated docs/ accordingly.
  • Users need more than the title to understand it, so I wrote it under ## Unreleased in CHANGELOG.md.

Done questions (AGENTS.md)

  • Goal: classify by given labels, content types or topics. It merges on green CI. The workflow node is the next PR.
  • Agents: POST /classify, MCP classify and assistant classify.
  • Zero setup: it uses the decision model if one is set, else the configured LLM. With neither, it returns a 409 that says so.
  • Fewest clicks and keystrokes: vocabularies need no labels typed, and labels take an optional meaning inline.
  • Configurable: n/a, no new settings. It reuses decisions.act_above (Settings → AI assistant).
  • Light: no new dependency. Decision models are the cheap path.
  • Private and secure: viewer ACL to classify and editor ACL to apply. The archive's text is marked untrusted. New surface is a read endpoint plus an apply path that reuses existing editor actions, so no new threat-model entry.
  • Cost: decision model first, LLM only as fallback. Every call goes in the activity ledger with the asset's and namespace's refs.
  • User decides: nothing changes without apply, and only on a sure answer. Topics are only suggested. Defaults are unchanged.
  • Upgrades: n/a, nothing new is stored.
  • Honest: the reply says who answered (by) and how sure it is. Docs label the planned parts.
  • Tests, docs and generated files updated: tests/api/test_classify.py, docs/processing.md#classifying, docs/api.md, docs/mcp.md, docs/assistant.md, make openapi.
  • Open standards; dependencies keep Lens MIT (none added).
  • Result reported with evidence. Refine later: classifying many assets at once from the API, and labels with examples.
  • Reuse: decide.choose/decide.sure, activity.scope, untrusted.wrap, content_types.choose, topics.propose, library.retag.

Local checks: ruff check, ruff format --check, mypy, classify/find/MCP tests, mkdocs build --strict. Before this rebase, the full backend suite passed: 1095 passed, 20 skipped.


Generated by Claude Code

POST /classify, the MCP tool classify and the assistant's classify say which
of some labels fits an asset or a text, how sure, and every label ranked:
labels given, Lens's content types or a namespace's topics. The decision model
answers, else the language model; with apply, an editor's sure answer sets the
content type, suggests the topic or adds the tag.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GKv2oVRvFRdiSf4USLsM1N
@adeelahmad adeelahmad self-assigned this Oct 17, 2026
@adeelahmad
adeelahmad merged commit dfaca83 into main Oct 17, 2026
10 checks passed
@adeelahmad
adeelahmad deleted the claude/project-thread-26l27n branch October 17, 2026 03:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants