spec-agents-text 0.2.1__py3-none-any.whl

spec_agents_text-0.2.1.dist-info/METADATA

@@ -0,0 +1,55 @@
+Metadata-Version: 2.5
+Name: spec-agents-text
+Version: 0.2.1
+Summary: Text domain pack for agent-fabric (text_stats, keywords, document_digest); proves the core is domain-agnostic
+Project-URL: Homepage, https://github.com/marcionicolau/spec-agents
+Project-URL: Repository, https://github.com/marcionicolau/spec-agents
+Project-URL: Issues, https://github.com/marcionicolau/spec-agents/issues
+Project-URL: Changelog, https://github.com/marcionicolau/spec-agents/blob/main/packages/text-pack/CHANGELOG.md
+Project-URL: Documentation, https://github.com/marcionicolau/spec-agents/tree/main/docs
+Author: Marcio Nicolau
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,nlp,text
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: spec-agents-core<1,>=0.0.1
+Description-Content-Type: text/markdown
+
+# spec-agents-text (`text_pack`)
+
+Small text domain pack for [agent-fabric](../agent-fabric/README.md): components `text_stats` and `keywords`, pipeline `document_digest`.
+It needs no pandas and no other pack, which makes it the proof that the core is domain-agnostic, and a minimal template for new packs.
+
+> **Status:** pre-release. Until the first PyPI release, install a wheel from the
+> [GitHub Releases](https://github.com/marcionicolau/spec-agents/releases) or use `uv sync --all-packages` in a checkout;
+> the `pip install` lines below are the PyPI names.
+
+## Names
+
+| | |
+| --- | --- |
+| PyPI distribution | `spec-agents-text` |
+| Import name | `text_pack` |
+| Directory in the monorepo | `packages/text-pack` |
+| Release tag / PR scope | `text-pack-vX.Y.Z` / `text-pack` |
+
+The distribution is named `spec-agents-text` because the shorter names are taken on PyPI; the import name and the entry point do not change.
+
+## Install
+```bash
+pip install spec-agents-text
+```
+```python
+from agent_fabric import build_registry
+from text_pack import register
+
+registry = build_registry([register])
+```
+Start a new pack from this one: a `register(registry)` function, `skills/<name>/SKILL.md` contracts and an `agent_fabric.domains` entry point.

spec_agents_text-0.2.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+text_pack/__init__.py,sha256=Z_K5VIkZv8hhhO7_qxu5EKwd8tdS1mxx5NuV-2yde4Q,4959
+text_pack/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+text_pack/skills/document_digest/SKILL.md,sha256=sDLOPiHKS-dRyrE9sNjaBKpq44HhAXY2LnBMGYtEVCA,589
+text_pack/skills/keywords/SKILL.md,sha256=SzxCi7fQ0CT-ttOue4dIiVYPFE-ER-QFYoy-YH6eOmo,1014
+text_pack/skills/text_stats/SKILL.md,sha256=k9OKAgDpsmSnJyx0uzEO8E84PMYVJEXeGJJO9NLLGL0,739
+spec_agents_text-0.2.1.dist-info/METADATA,sha256=9MC0GQFt-5Px96y32NNkZjW0Mg5xZ5-Jjabc8cN_Jog,2365
+spec_agents_text-0.2.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+spec_agents_text-0.2.1.dist-info/entry_points.txt,sha256=iEAYvK5UIC-Rt5l5nrrBDCSiU91QusF_OAe8eU3rveM,49
+spec_agents_text-0.2.1.dist-info/licenses/LICENSE,sha256=PDXl-Nq_KQ-fBkmdUynB87KFuoDraUCnx6GOpXcXAAw,1071
+spec_agents_text-0.2.1.dist-info/RECORD,,

spec_agents_text-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

spec_agents_text-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[agent_fabric.domains]
+text = text_pack:register

spec_agents_text-0.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcio Nicolau
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

text_pack/__init__.py

@@ -0,0 +1,166 @@
+"""Text domain pack - proves the fabric is domain-agnostic (no pandas involved).
+
+Components: text_stats, keywords.  Pipeline: document_digest.
+Load with ``build_registry([text_pack.register])`` or entry point ``agent_fabric.domains``.
+"""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from agent_fabric.compat import requires_api
+from agent_fabric.component import Component, ComponentParams, ComponentResult, Num, StepContext
+from agent_fabric.errors import ErrorDetail
+from agent_fabric.registry import Registry, component
+
+SPEC_DIR = Path(__file__).parent / "skills"
+_WORD = re.compile(r"[A-Za-zÀ-ÿ]+(?:-[A-Za-zÀ-ÿ]+)*")
+STOPWORDS = {
+    "the",
+    "a",
+    "an",
+    "and",
+    "or",
+    "of",
+    "to",
+    "in",
+    "on",
+    "for",
+    "is",
+    "are",
+    "was",
+    "were",
+    "with",
+    "by",
+    "de",
+    "da",
+    "do",
+    "das",
+    "dos",
+    "e",
+    "o",
+    "os",
+    "as",
+    "em",
+    "no",
+    "na",
+    "para",
+    "com",
+    "que",
+    "um",
+    "uma",
+}
+
+
+class TextStatsParams(ComponentParams):
+    lowercase: bool = True
+
+
+class TextStatsResult(ComponentResult):
+    n_words: int
+    n_sentences: int
+    avg_word_length: Num
+    lexical_diversity: Num
+
+
+@component("text_stats")
+class TextStats(Component[TextStatsParams, TextStatsResult]):
+    Params = TextStatsParams
+    Result = TextStatsResult
+
+    def compute(self, inputs: dict, params: TextStatsParams, ctx: StepContext) -> TextStatsResult:
+        """Count words and sentences and compute the average word length and lexical diversity (distinct words over all words).
+
+        Warns when the text has fewer than 50 words, where the statistics are unstable.
+        """
+        text = inputs["text"]
+        words = [w.lower() if params.lowercase else w for w in _WORD.findall(text)]
+        sentences = [s for s in re.split(r"[.!?]+\s", text) if s.strip()]
+        warns = ["very short text; statistics are unstable"] if len(words) < 50 else []
+        return TextStatsResult(
+            n_words=len(words),
+            n_sentences=len(sentences),
+            avg_word_length=sum(map(len, words)) / len(words) if words else None,
+            lexical_diversity=len(set(words)) / len(words) if words else None,
+            warnings=warns,
+        )
+
+    def summarize(self, r: dict) -> tuple[str, list[str]]:
+        return (
+            f"{r['n_words']} words in {r['n_sentences']} sentences.",
+            [f"lexical diversity {r['lexical_diversity']:.2f}", f"average word length {r['avg_word_length']:.2f}"],
+        )
+
+
+class KeywordsParams(ComponentParams):
+    top_k: int = Field(10, ge=1, le=50)
+    min_length: int = Field(4, ge=1)
+    extra_stopwords: list[str] = Field(default_factory=list)
+
+
+class Keyword(BaseModel):
+    term: str
+    count: int
+
+
+class KeywordsResult(ComponentResult):
+    keywords: list[Keyword]
+
+
+@component("keywords")
+class Keywords(Component[KeywordsParams, KeywordsResult]):
+    Params = KeywordsParams
+    Result = KeywordsResult
+
+    def extra_checks(self, inputs: dict, params: KeywordsParams) -> list[ErrorDetail]:
+        n = len([w for w in _WORD.findall(inputs["text"]) if len(w) >= params.min_length])
+        if n == 0:
+            return [
+                ErrorDetail(
+                    loc=("params", "min_length"),
+                    type="no_candidates",
+                    msg=f"no words with >= {params.min_length} letters",
+                    hint="lower min_length",
+                )
+            ]
+        return []
+
+    def compute(self, inputs: dict, params: KeywordsParams, ctx: StepContext) -> KeywordsResult:
+        """Most frequent content words: lowercased words of at least ``min_length`` letters minus stop words and ``extra_stopwords``.
+
+        Emits the ranked ``terms`` list; the result carries each term with its count.
+        """
+        stop = STOPWORDS | {w.lower() for w in params.extra_stopwords}
+        words = [
+            w.lower() for w in _WORD.findall(inputs["text"]) if len(w) >= params.min_length and w.lower() not in stop
+        ]
+        top = Counter(words).most_common(params.top_k)
+        ctx.emit("terms", [t for t, _ in top])
+        return KeywordsResult(keywords=[Keyword(term=t, count=c) for t, c in top])
+
+    def summarize(self, r: dict) -> tuple[str, list[str]]:
+        kws = r["keywords"]
+        return f"Top terms: {', '.join(k['term'] for k in kws[:5])}.", [f"{k['term']}: {k['count']}" for k in kws[:6]]
+
+
+@requires_api(1)
+def register(registry: Registry) -> list[str]:
+    """Register the text domain (``text_stats``, ``keywords`` and the ``document_digest`` pipeline); returns the names registered."""
+    return registry.load_domain(SPEC_DIR, [TextStats, Keywords])
+
+
+__all__ = [
+    "SPEC_DIR",
+    "Keyword",
+    "Keywords",
+    "KeywordsParams",
+    "KeywordsResult",
+    "TextStats",
+    "TextStatsParams",
+    "TextStatsResult",
+    "register",
+]

text_pack/skills/document_digest/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: document_digest
+kind: pipeline
+version: 1.0.0
+domain: text
+description: Text statistics plus top keywords of a document.
+params:
+  top_k: {description: number of keywords, default: 8}
+inputs:
+  text: {type: text, description: document to digest}
+steps:
+- {id: stats, component: text_stats}
+- id: kw
+  component: keywords
+  params: {top_k: $params.top_k}
+outputs: {terms: kw.terms}
+---
+# Document digest
+
+## When to use
+A quick overview of a report, abstract or field note.
+
+## Procedure
+1. `text_stats`: size and vocabulary.
+2. `keywords`: top `top_k` terms, exposed as `terms`.

text_pack/skills/keywords/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: keywords
+version: 1.0.0
+domain: text
+category: extraction
+description: Most frequent content words after stop-word removal.
+runtime: code
+params:
+  top_k: {description: how many terms to return, example: 10}
+  min_length: {description: minimum word length, example: 4}
+  extra_stopwords:
+    description: additional words to ignore
+    example: [wheat]
+inputs:
+  text:
+    type: text
+    description: document text
+    constraints: {min_chars: 20}
+outputs:
+  terms: {type: json, description: list of top terms}
+---
+# Keyword extraction
+
+## When to use
+Find what a document is about: the most frequent content words after stop-word removal.
+
+## Interpreting
+Counts are raw frequencies. With short texts, ties are common, so do not over-read the ranking.
+Use `extra_stopwords` to remove words that are frequent but uninformative in the domain
+(e.g. "plot", "field").
+
+## Common mistakes
+- Setting `min_length` so high that no words qualify.
+- Expecting multi-word phrases: only single words are extracted.

text_pack/skills/text_stats/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: text_stats
+version: 1.0.0
+domain: text
+category: descriptive
+description: Word and sentence counts, average word length and lexical diversity.
+runtime: code
+params:
+  lowercase: {description: lower-case words before counting, example: true}
+inputs:
+  text:
+    type: text
+    description: document text
+    constraints: {min_chars: 1}
+---
+# Text statistics
+
+## When to use
+Describe the size and vocabulary richness of a document before summarising or comparing it.
+
+## Interpreting
+- `lexical_diversity` is the share of distinct words. Values near 1 are typical of short texts; long
+  technical reports usually fall between 0.3 and 0.5.
+- Statistics for texts under ~50 words are unstable. The component warns when that happens.