diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..166d1b3 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 Cyril Decostanzi + +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. diff --git a/README.md b/README.md index 11b0d6e..33292e6 100644 --- a/README.md +++ b/README.md @@ -67,6 +67,7 @@ poetry install This will automatically install all dependencies declared in `pyproject.toml`, including **transformers** and **torch**. To run the CLI inside the Poetry environment: + ```bash poetry run python src/main.py ``` @@ -118,12 +119,14 @@ Available commands: ### Example Sessions #### 🔹 Sentiment Analysis + ```text 💬 Enter text: I absolutely love this project! → Sentiment: POSITIVE (score: 0.998) ``` #### 🔹 Fill‑Mask + ```text 💬 Enter text: The capital of France is [MASK]. → Predictions: @@ -133,12 +136,14 @@ Available commands: ``` #### 🔹 Text Generation + ```text 💬 Prompt: Once upon a time → Output: Once upon a time there was a young AI learning to code... ``` #### 🔹 NER (Named Entity Recognition) + ```text 💬 Enter text: Elon Musk founded SpaceX in California. → Entities: @@ -148,6 +153,7 @@ Available commands: ``` #### 🔹 Moderation + ```text 💬 Enter text: I hate everything! → Result: FLAGGED (toxic content detected) @@ -186,13 +192,13 @@ The internal structure follows a clean **Command ↔ Pipeline ↔ Display** patt ### Key Concepts -| Layer | Description | -|-------|--------------| -| **CLI** | Manages user input/output, help menus, and navigation between commands. | -| **Command** | Encapsulates a single user-facing operation (e.g., run sentiment). | -| **Pipeline** | Wraps Hugging Face’s `transformers.pipeline()` to perform inference. | -| **Display** | Handles clean console rendering (colored output, tables, JSON formatting). | -| **Config** | Centralizes model names, limits, and global constants. | +| Layer | Description | +| ------------ | -------------------------------------------------------------------------- | +| **CLI** | Manages user input/output, help menus, and navigation between commands. | +| **Command** | Encapsulates a single user-facing operation (e.g., run sentiment). | +| **Pipeline** | Wraps Hugging Face’s `transformers.pipeline()` to perform inference. | +| **Display** | Handles clean console rendering (colored output, tables, JSON formatting). | +| **Config** | Centralizes model names, limits, and global constants. | --- @@ -261,54 +267,36 @@ tests/ ## 🧰 Troubleshooting -| Issue | Cause / Solution | -|-------|------------------| -| **`transformers` not found** | Check virtual environment activation. | -| **Torch fails to install** | Install CPU-only version from PyTorch index. | -| **Models download slowly** | Hugging Face caches them after first run. | -| **Unicode / accents broken** | Ensure terminal encoding is UTF‑8. | +| Issue | Cause / Solution | +| ---------------------------- | -------------------------------------------- | +| **`transformers` not found** | Check virtual environment activation. | +| **Torch fails to install** | Install CPU-only version from PyTorch index. | +| **Models download slowly** | Hugging Face caches them after first run. | +| **Unicode / accents broken** | Ensure terminal encoding is UTF‑8. | --- ## 🧭 Development Guidelines -- Keep **Command** classes lightweight — no ML logic inside them. -- Reuse the **Pipeline Template** for new experiments. -- Format outputs consistently via the `DisplayFormatter`. -- Document all new models or commands in `README.md` and `settings.py`. +- Keep **Command** classes lightweight — no ML logic inside them. +- Reuse the **Pipeline Template** for new experiments. +- Format outputs consistently via the `DisplayFormatter`. +- Document all new models or commands in `README.md` and `settings.py`. --- ## 🧱 Roadmap -- [ ] Add non-interactive CLI flags (`--text`, `--task`) -- [ ] Add multilingual model options -- [ ] Add automatic test coverage -- [ ] Add logging and profiling utilities -- [ ] Add export to JSON/CSV results +- [ ] Add non-interactive CLI flags (`--text`, `--task`) +- [ ] Add multilingual model options +- [ ] Add automatic test coverage +- [ ] Add logging and profiling utilities +- [ ] Add export to JSON/CSV results --- -## 🪪 License +## 📜 License -You can include a standard open-source license such as **MIT** or **Apache 2.0** depending on your use case. +This project is licensed under the [MIT License](./LICENSE) — feel free to use it, modify it, and share it! --- - -## 🤝 Contributing - -This repository is meant as an **educational sandbox** for experimenting with Transformers. -Pull requests are welcome for new models, better CLI UX, or educational improvements. - ---- - -### ✨ Key Takeaways - -- Modular and pedagogical design for training environments -- Clean separation between **I/O**, **ML logic**, and **UX** -- Easily extensible architecture for adding custom pipelines -- Perfect sandbox for students, researchers, and developers to learn modern NLP tools - ---- - -> 🧩 Built for experimentation. Learn, break, and rebuild.