topiclayers 0.2.0__tar.gz → 0.2.1__tar.gz

{topiclayers-0.2.0 → topiclayers-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: topiclayers
-Version: 0.2.0
+Version: 0.2.1
 Summary: From any collection of posts to topical multilayer networks — hardened and social-scientist-friendly
 License: MIT
 License-File: LICENSE
@@ -43,6 +43,10 @@ Description-Content-Type: text/markdown
 ```bash
 # Requires Python 3.12
 pip install topiclayers
+
+# copy runnable examples (configs + toy data) into ./examples/
+topiclayers init
+
 topiclayers run examples/generic.yml
 ```
 
@@ -161,7 +165,8 @@ CSV optional columns: `created_at`, `lang`, `interaction_type` (`original`/`repo
 | Symptom | Likely cause | Fix |
 |---------|-------------|-----|
 | "All topics are -1" / "no topics found" | `min_topic_size` too high or dataset too small | Halve `min_topic_size` in config, or use a larger dataset (>100 posts) |
-| "Module not found" | topiclayers not installed | `pip install -e .` |
+| "Module not found" | topiclayers not installed | `pip install topiclayers` |
+| `topiclayers: command not found` | installed in a venv that isn't active | Activate the venv (`source .venv/bin/activate`) or use `python -m topiclayers.cli`; on install with `--user` add `~/.local/bin` to PATH |
 | "OpenAI API key not set" | Using OpenAI embedder without key | Switch `embedder` to `all-MiniLM-L6-v2` (default, works offline) |
 | "Qdrant connection refused" | Qdrant vector DB not running | Ignore — Qdrant is optional. Set `QDRANT_URL` in `.env` to enable |
 | "Cannot create multilayer network" | All posts are outliers | Reduce `min_topic_size` or provide more data |

{topiclayers-0.2.0 → topiclayers-0.2.1}/README.md

@@ -7,6 +7,10 @@
 ```bash
 # Requires Python 3.12
 pip install topiclayers
+
+# copy runnable examples (configs + toy data) into ./examples/
+topiclayers init
+
 topiclayers run examples/generic.yml
 ```
 
@@ -125,7 +129,8 @@ CSV optional columns: `created_at`, `lang`, `interaction_type` (`original`/`repo
 | Symptom | Likely cause | Fix |
 |---------|-------------|-----|
 | "All topics are -1" / "no topics found" | `min_topic_size` too high or dataset too small | Halve `min_topic_size` in config, or use a larger dataset (>100 posts) |
-| "Module not found" | topiclayers not installed | `pip install -e .` |
+| "Module not found" | topiclayers not installed | `pip install topiclayers` |
+| `topiclayers: command not found` | installed in a venv that isn't active | Activate the venv (`source .venv/bin/activate`) or use `python -m topiclayers.cli`; on install with `--user` add `~/.local/bin` to PATH |
 | "OpenAI API key not set" | Using OpenAI embedder without key | Switch `embedder` to `all-MiniLM-L6-v2` (default, works offline) |
 | "Qdrant connection refused" | Qdrant vector DB not running | Ignore — Qdrant is optional. Set `QDRANT_URL` in `.env` to enable |
 | "Cannot create multilayer network" | All posts are outliers | Reduce `min_topic_size` or provide more data |

{topiclayers-0.2.0 → topiclayers-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "topiclayers"
-version = "0.2.0"
+version = "0.2.1"
 description = "From any collection of posts to topical multilayer networks — hardened and social-scientist-friendly"
 authors = ["alessiogandelli <alessiogandelli99@gmail.com>"]
 readme = "README.md"

{topiclayers-0.2.0 → topiclayers-0.2.1}/src/topiclayers/__init__.py

@@ -1,3 +1,3 @@
 """topiclayers — from posts to topical multilayer networks."""
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"

{topiclayers-0.2.0 → topiclayers-0.2.1}/src/topiclayers/cli.py

@@ -168,12 +168,37 @@ def _run_pipeline_stages(config: RunConfig, input_path: Path, status) -> None:
     print(f"  Run manifest: {config.output_dir / 'run_manifest.json'}")
 
 
+def _cmd_init(dest: Path) -> None:
+    import shutil
+    from importlib.resources import as_file, files
+
+    if dest.exists():
+        print(f"Directory '{dest}' already exists — remove it or pass another path.",
+              file=sys.stderr)
+        sys.exit(1)
+
+    with as_file(files("topiclayers") / "examples") as bundled:
+        shutil.copytree(bundled, dest)
+
+    print(f"Examples copied to {dest.resolve()}")
+    print("Try it:")
+    print(f"  topiclayers run {dest / 'generic.yml'}")
+
+
 def main() -> None:
-    if len(sys.argv) < 3 or sys.argv[1] not in ("run", "status"):
+    if len(sys.argv) < 2 or (
+        sys.argv[1] not in ("run", "status", "init")
+        or (sys.argv[1] != "init" and len(sys.argv) < 3)
+    ):
         print("Usage: topiclayers run <config.yaml>", file=sys.stderr)
         print("       topiclayers status <output_dir>", file=sys.stderr)
+        print("       topiclayers init [dest=./examples]", file=sys.stderr)
         sys.exit(1)
 
+    if sys.argv[1] == "init":
+        _cmd_init(Path(sys.argv[2]) if len(sys.argv) > 2 else Path("examples"))
+        return
+
     if sys.argv[1] == "status":
         from topiclayers.status import print_status
 

topiclayers-0.2.1/src/topiclayers/examples/generic/posts.csv

@@ -0,0 +1,8 @@
+post_id,user_id,text,created_at,lang,interaction_type,target_post_id
+t1,a,tweet1,2022-01-01,en,original,
+t2,b,tweet2,2022-01-02,en,repost,t1
+t3,c,tweet3,2022-01-03,en,repost,t2
+t4,c,tweet4,2022-01-04,en,original,
+t5,a,tweet5,2022-01-05,en,repost,t7
+t6,d,tweet6,2022-01-06,en,repost,t7
+t7,d,tweet7,2022-01-07,en,original,

topiclayers-0.2.1/src/topiclayers/examples/generic.yml

@@ -0,0 +1,15 @@
+input:
+  format: csv_posts
+  # paths are resolved relative to this config file's directory
+  posts: generic/posts.csv
+
+name: generic_toy
+
+topic_model:
+  embedder: all-MiniLM-L6-v2
+  min_topic_size: 2
+
+network:
+  type: multilayer_repost
+
+output_dir: ./out/generic_toy

topiclayers-0.2.1/src/topiclayers/examples/template_csv.yml

@@ -0,0 +1,44 @@
+# ============================================================
+# TEMPLATE — Generic CSV/Parquet posts (any platform)
+# Copy this file, rename it, adjust the values below.
+# Run:  topiclayers run examples/<your_config>.yml
+# Paths in `input` are resolved relative to THIS file's directory.
+# ============================================================
+
+input:
+  format: csv_posts              # or parquet_posts
+  posts: generic/posts.csv       # required columns: post_id, user_id, text
+                                 # optional columns: created_at, lang,
+                                 # interaction_type ("original"|"repost"|"quote"|"reply"),
+                                 # target_post_id, mentions (semicolon-separated),
+                                 # any extra_* column is carried through as metadata
+  # users: path/to/users.csv     # optional user metadata file
+
+name: my_dataset                 # prefixes outputs and cache keys; changing it starts
+                                 # a fresh cache
+
+topic_model:
+  embedder: all-MiniLM-L6-v2     # sentence-transformers model, or OpenAI
+                                 # "text-embedding-3-small"/"-large" (needs
+                                 # OPENAI_API_KEY in .env)
+  min_topic_size: 10             # small datasets need small values; start low and raise
+                                 # until topics look coherent
+  nr_topics: auto                # "auto", or an int to force reduction after fit
+  random_state: 42
+  umap_n_neighbors: 15
+  umap_n_components: 5
+  exact_probabilities: false     # true = full membership matrix (slow on big corpora)
+  repro_mode: fast               # "fast" = parallel, non-reproducible;
+                                 # "strict" = seeded single-threaded, bit-reproducible
+  umap_init: pca                 # default; ~20x faster than spectral, deterministic
+                                 # when seeded (docs/UMAP_INIT_BENCHMARK.md)
+  label_model: ollama/qwen2.5:7b # optional LLM topic labeling (LiteLLM string);
+                                 # "" disables. See template_twitter.yml for setup
+
+network:
+  type: retweet                  # for CSV data usually "retweet" (or "multilayer_repost"
+                                 # / "ttn" / "all"); requires target_post_id +
+                                 # interaction_type=repost rows to build edges
+  project_ttn: true
+
+output_dir: ./out/my_dataset

topiclayers-0.2.1/src/topiclayers/examples/template_twitter.yml

@@ -0,0 +1,84 @@
+# ============================================================
+# TEMPLATE — Twitter/X JSONL input (Academic API dump)
+# Copy this file, rename it, adjust the values below.
+# Run:  topiclayers run examples/<your_config>.yml
+# Status from another terminal while running:
+#       topiclayers status <output_dir>
+# Paths in `input` are resolved relative to THIS file's directory.
+# ============================================================
+
+input:
+  format: twitter_jsonl          # one JSON tweet per line (Twitter API v2 fields:
+                                 # id, author_id, text, referenced_tweets, entities...)
+  posts: twitter/toy.json        # required — path to the .json/.jsonl tweet file
+  # users: path/to/users.dat     # optional — JSONL of user objects
+                                 # ({id, username, public_metrics}); used to map
+                                 # author ids -> usernames in outputs.
+                                 # Delete the line if you don't have it.
+
+name: cop22                      # dataset name: prefixes output files and cache keys.
+                                 # Changing it starts a fresh cache.
+
+topic_model:
+  embedder: all-MiniLM-L6-v2     # any sentence-transformers model, or an OpenAI
+                                 # embedding model ("text-embedding-3-small" /
+                                 # "text-embedding-3-large"; requires OPENAI_API_KEY
+                                 # in .env)
+  min_topic_size: 50             # smallest cluster HDBSCAN will accept (= BERTopic's
+                                 # granularity knob). Too high -> everything is outlier
+                                 # -1; too low -> thousands of micro-topics.
+                                 # Rule of thumb: ~1/2000 of originals for large sets.
+  nr_topics: auto                # "auto", or an int to force topic reduction after fit
+  random_state: 42               # seed; keep fixed for reproducibility
+  umap_n_neighbors: 15           # UMAP locality (kept for reference; pipeline uses
+                                 # adaptive values for small datasets)
+  umap_n_components: 5           # UMAP output dims (same note as above)
+  exact_probabilities: false     # true = full membership matrix (much slower on big
+                                 # corpora); topics are identical either way
+  repro_mode: fast               # "fast" = parallel UMAP+HDBSCAN (~20 min saved on
+                                 #   180k docs), results vary between runs;
+                                 # "strict" = seeded single-threaded UMAP,
+                                 #   bit-reproducible, slower
+  umap_init: pca                 # default; deterministic when seeded and ~20x faster
+                                 # than spectral (see docs/UMAP_INIT_BENCHMARK.md).
+                                 # Pass "spectral" only if you specifically need it.
+  label_model: ollama/qwen2.5:7b # LLM that writes a short human-readable label per
+                                 # topic (any LiteLLM model string). Local & free
+                                 # via Ollama (https://ollama.com):
+                                 #   ollama serve && ollama pull qwen2.5:7b
+                                 # Cloud examples: "gpt-4o-mini",
+                                 # "anthropic/claude-3-haiku-20240307".
+                                 # Custom OpenAI-compatible server (Unsloth,
+                                 # llama.cpp, vLLM...): prefix with "openai/" and
+                                 # set label_api_base, e.g.
+                                 #   label_model: openai/unsloth/Qwen3.8-27B-GGUF
+                                 #   label_api_base: http://localhost:8888/v1
+                                 # Requires the labeling extra:
+                                 #   pip install 'topiclayers[labeling]'
+                                 # API key from LABEL_API_KEY / OPENAI_LIKE_API_KEY
+                                 # / OPENAI_API_KEY in .env. Set label_model to ""
+                                 # to disable; non-fatal if unreachable.
+  # label_context: ""            # optional context sentence ("all documents are ...");
+                                 # by default derived from `name` for cop* datasets.
+                                 # Helps the LLM label the specific SUBTOPIC instead
+                                 # of the general domain. Topics are labeled in
+                                 # batches (~40 per call); use a strong model for
+                                 # publishable labels (e.g. gpt-4o-mini, <1 min and
+                                 # cents for a full dataset)
+  label_api_base: ""             # base URL of a custom OpenAI-compatible endpoint;
+                                 # leave "" for Ollama/OpenAI. Can also be set via
+                                 # LABEL_API_BASE in .env
+
+network:
+  type: multilayer_repost        # one of:
+                                 #   multilayer_repost -> retweet graph + multilayer
+                                 #                        network by topic (uunet)
+                                 #   retweet           -> retweet graph only (.gml)
+                                 #   ttn               -> topic-targeted network
+                                 #   all               -> all of the above
+  project_ttn: true              # ttn only: also export the projected monopartite
+                                 # version
+
+output_dir: ./out/cop22          # everything lands here: networks/, cache/
+                                 # (embeddings, model, labeled df), run_manifest.json,
+                                 # run_status.json

topiclayers-0.2.1/src/topiclayers/examples/twitter/toy.json

@@ -0,0 +1 @@
+{"lang": "en", "possibly_sensitive": false, "public_metrics": {"retweet_count": 8, "reply_count": 0, "like_count": 0, "quote_count": 0, "impression_count": 0}, "conversation_id": "815345170468208642", "entities": {"mentions": [{"start": 3, "end": 14, "username": "pablorodas", "id": "52119056"}], "hashtags": [{"start": 16, "end": 30, "tag": "CLIMATEchange"}, {"start": 31, "end": 34, "tag": "p2"}, {"start": 112, "end": 118, "tag": "COP22"}, {"start": 119, "end": 124, "tag": "tcot"}, {"start": 125, "end": 128, "tag": "2A"}], "urls": [{"start": 88, "end": 111, "url": "https://t.co/f5lY9m4sE2", "expanded_url": "http://dlvr.it/N0sp69", "display_url": "dlvr.it/N0sp69"}], "annotations": [{"start": 113, "end": 117, "probability": 0.775, "type": "Other", "normalized_text": "COP22"}]}, "referenced_tweets": [{"type": "retweeted", "id": "815344316495237120"}], "text": "RT @pablorodas: #CLIMATEchange #p2 RT Our best environment stories from this past\u00a0year. https://t.co/f5lY9m4sE2 #COP22 #tcot #2A https://t.\u2026", "id": "815345170468208642", "created_at": "2016-12-31T23:53:31.000Z", "author_id": "17227307", "context_annotations": [{"domain": {"id": "25", "name": "Events", "description": ""}, "entity": {"id": "10040144401", "name": "Extreme Weather + Climate Change"}}, {"domain": {"id": "25", "name": "Events", "description": ""}, "entity": {"id": "10040529339", "name": "Discovery VCN - Earth"}}], "edit_history_tweet_ids": ["815345170468208642"]}