From 77fa24c99f30dbe87e079c2c7f9f25eedf08253c Mon Sep 17 00:00:00 2001
From: Mohamed Jadla <jadlamed444@gmail.com>
Date: Thu, 9 Apr 2026 18:55:26 +0100
Subject: [PATCH 01/12] docs: small README improvements

Clean up wording, formatting, and fix minor typos in README.
---
 README.md | 806 ++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 746 insertions(+), 60 deletions(-)

diff --git a/README.md b/README.md
index a3df039..1e36ae8 100644
--- a/README.md
+++ b/README.md
@@ -11,9 +11,84 @@
 | **Package** | [![PyPI](https://img.shields.io/pypi/v/oris-ai)](https://pypi.org/project/oris-ai/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/oris-ai?logo=python&logoColor=gold)](https://pypi.org/project/oris-ai/) [![License](https://img.shields.io/github/license/DevStrikerTech/oris)](https://github.com/DevStrikerTech/oris/blob/prod/LICENSE) |
 | **Meta** | [![Issues](https://img.shields.io/github/issues/DevStrikerTech/oris)](https://github.com/DevStrikerTech/oris/issues) [![GitHub](https://img.shields.io/badge/GitHub-DevStrikerTech%2Foris-181717?logo=github)](https://github.com/DevStrikerTech/oris) |
 
-[Oris](https://devstrikertech.github.io/oris/) is an open-source **Responsible AI** runtime for Python. Describe **pipelines** in YAML (or build them in code), run them through one **executor**, and get **input/output policy checks** and **run- and step-level traces** by default.
+[Oris](https://devstrikertech.github.io/oris/) 
+Oris
+ is an open-source Responsible AI runtime for Python. Define pipelines in YAML (or build them in code), run them through one executor, and get input/output policy checks and run- and step-level traces by default.
+
+Oris is framework-agnostic: anything you can invoke like run(dict) can use the same boundaries—including external LLM stacks wrapped with SafeRunner—so you can experiment locally and ship with clearer safety and observability defaults.
+Table of Contents
+Installation
+Documentation
+Features
+Quick Start
+CLI
+Output Format
+SafeRunner
+Project Layout
+Examples and Notebooks
+Contributing
+License
+Installation
 
-Oris stays **framework-agnostic**: anything you can invoke like `run(dict)` can use the same boundaries—including external LLM stacks wrapped with **SafeRunner**—so you can experiment locally and ship with clearer safety and observability defaults.
+The simplest way to get Oris is via pip:
+pip install oris-ai
+Verify the CLI:
+oris --help
+From source (library, CLI, and tests):
+git clone https://github.com/DevStrikerTech/oris.git
+cd oris
+python -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e .
+Developers (lint, types, tests, notebook execution):
+pip install -e ".[dev]"
+Oris requires Python 3.10+. Runtime dependencies are minimal (PyYAML only). For a fuller walkthrough, see the Installation
+ page in the docs.
+
+Documentation
+Start with the Introduction
+, then follow Installation
+ and Quickstart
+. The Concepts
+ section explains pipelines, components, providers, RAI, and traces; Guides
+ cover CLI usage, SafeRunner, and run summaries.
+
+Site: devstrikertech.github.io/oris
+ (MkDocs Material, similar to Haystack
+).
+
+Preview locally:
+pip install -e ".[docs]"
+mkdocs serve
+The Docs workflow publishes to GitHub Pages on pushes to prod (.github/workflows/docs.yml
+). In Settings → Pages, choose GitHub Actions as the source if needed.
+
+Features
+YAML-first pipelines: define steps, optional providers, and settings (tracing, etc.). Configuration is validated before execution.
+
+Guards and policy: default PolicyEnforcer applies input/output checks, including blocked keys, injection heuristics, and PII-shaped patterns. SafeRunner uses the same policy.
+
+Hello
+
+Hello! 😄 How’s your day going?
+
+
+<p align="center">
+  <a href="https://devstrikertech.github.io/oris/">
+    <img src="docs/images/oris_logo.png" width="180" alt="Oris — Responsible AI pipeline runtime for Python" />
+  </a>
+</p>
+
+|         |     |
+| ------- | --- |
+| **CI** | [![CI](https://github.com/DevStrikerTech/oris/actions/workflows/ci.yml/badge.svg?branch=dev)](https://github.com/DevStrikerTech/oris/actions/workflows/ci.yml) [![types - Mypy](https://img.shields.io/badge/types-Mypy-blue.svg)](https://github.com/python/mypy) [![Coverage](https://img.shields.io/badge/coverage-%E2%89%A584%25-brightgreen.svg)](CONTRIBUTING.md#quality-gates) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) |
+| **Docs** | [![Website](https://img.shields.io/website?label=documentation&up_message=online&url=https%3A%2F%2Fdevstrikertech.github.io%2Foris%2F)](https://devstrikertech.github.io/oris/) [![Docs](https://github.com/DevStrikerTech/oris/actions/workflows/docs.yml/badge.svg?branch=prod)](https://github.com/DevStrikerTech/oris/actions/workflows/docs.yml) |
+| **Package** | [![PyPI](https://img.shields.io/pypi/v/oris-ai)](https://pypi.org/project/oris-ai/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/oris-ai?logo=python&logoColor=gold)](https://pypi.org/project/oris-ai/) [![License](https://img.shields.io/github/license/DevStrikerTech/oris)](https://github.com/DevStrikerTech/oris/blob/prod/LICENSE) |
+| **Meta** | [![Issues](https://img.shields.io/github/issues/DevStrikerTech/oris)](https://github.com/DevStrikerTech/oris/issues) [![GitHub](https://img.shields.io/badge/GitHub-DevStrikerTech%2Foris-181717?logo=github)](https://github.com/DevStrikerTech/oris) |
+
+[Oris](https://devstrikertech.github.io /oris/) is an open-source **Responsible AI** runtime for Python. Describe **pipelines** in YAML (or build them in code), run them through one **executor**, and get **input/output policy checks** and **run- and step-level traces** by default.
+
+Oris stays **framework-agnostic**: anything you can invoke like run(dict) can use the same boundaries—including external LLM stacks wrapped with **SafeRunner**—so you can experiment locally and ship with clearer safety and observability defaults.
 
 ## Table of contents
 
@@ -33,31 +108,31 @@ Oris stays **framework-agnostic**: anything you can invoke like `run(dict)` can
 
 The simplest way to get Oris is via pip:
 
-```bash
+bash
 pip install oris-ai
-```
+
 
 Verify the CLI:
 
-```bash
+bash
 oris --help
-```
+
 
 **From source** (library, CLI, and tests):
 
-```bash
+bash
 git clone https://github.com/DevStrikerTech/oris.git
 cd oris
 python -m venv .venv
 source .venv/bin/activate   # Windows: .venv\Scripts\activate
 pip install -e .
-```
+
 
 **Developers** (lint, types, tests, notebook execution):
 
-```bash
+bash
 pip install -e ".[dev]"
-```
+
 
 Oris requires **Python 3.10+**. Runtime dependencies are minimal (**PyYAML** only). For a fuller walkthrough, see the [Installation](https://devstrikertech.github.io/oris/get-started/installation/) page in the docs.
 
@@ -69,35 +144,35 @@ If you are new to the project, start with the [**Introduction**](https://devstri
 
 **Preview locally:**
 
-```bash
+bash
 pip install -e ".[docs]"
 mkdocs serve
-```
 
-The **Docs** workflow publishes to GitHub Pages on pushes to **`prod`** ([`.github/workflows/docs.yml`](.github/workflows/docs.yml)). In **Settings → Pages**, choose **GitHub Actions** as the source if needed.
+
+The **Docs** workflow publishes to GitHub Pages on pushes to **prod** ([.github/workflows/docs.yml](.github/workflows/docs.yml)). In **Settings → Pages**, choose **GitHub Actions** as the source if needed.
 
 ## Features
 
 **YAML-first pipelines**  
-Define `steps`, optional `providers`, and `settings` (such as tracing). Configuration is validated before execution; YAML is loaded with `yaml.safe_load` only.
+Define steps, optional providers, and settings (such as tracing). Configuration is validated before execution; YAML is loaded with yaml.safe_load only.
 
 **Guards and policy**  
-A default `PolicyEnforcer` applies input checks (blocked keys, basic injection heuristics, simple PII-shaped patterns) and output checks (blocked terms and test-oriented stubs). The same policy surface is used by **SafeRunner** for external callables.
+A default PolicyEnforcer applies input checks (blocked keys, basic injection heuristics, simple PII-shaped patterns) and output checks (blocked terms and test-oriented stubs). The same policy surface is used by **SafeRunner** for external callables.
 
 **Built-in components and provider stubs**  
-Use `passthrough`, `template_response`, and `generate` / `llm_echo` from the default registry. Declared `openai` / `huggingface` provider types are **stubs** (no network I/O in the core package) so CI and demos stay reproducible.
+Use passthrough, template_response, and generate / llm_echo from the default registry. Declared openai / huggingface provider types are **stubs** (no network I/O in the core package) so CI and demos stay reproducible.
 
 **Observability**  
-Each run produces a `RunTrace` with per-step latency, status, and flags. `PipelineResult.to_run_summary()` gives a stable JSON-oriented shape for logs and the CLI (with optional redaction of sensitive-looking keys).
+Each run produces a RunTrace with per-step latency, status, and flags. PipelineResult.to_run_summary() gives a stable JSON-oriented shape for logs and the CLI (with optional redaction of sensitive-looking keys).
 
 **CLI parity**  
-`oris validate` and `oris run` use the same definitions as `Pipeline.from_yaml` in Python, with `--format pretty` and `--debug` for human-friendly output and stderr trace lines.
+oris validate and oris run use the same definitions as Pipeline.from_yaml in Python, with --format pretty and --debug for human-friendly output and stderr trace lines.
 
 ## Quick start
 
-Save as `pipeline.yaml`:
+Save as pipeline.yaml:
 
-```yaml
+yaml
 name: quickstart
 settings:
   tracing: true
@@ -106,57 +181,57 @@ steps:
     type: template_response
     config:
       template: "Answer placeholder for: {query}"
-```
+
 
 **Python**
 
-```python
+python
 from oris import Pipeline
 
 pipeline = Pipeline.from_yaml("pipeline.yaml")
 result = pipeline.run({"query": "What is responsible AI?"})
 
 print(result.output)
-```
+
 
 **CLI**
 
-```bash
+bash
 oris validate pipeline.yaml
 oris run pipeline.yaml --input-json '{"query":"What is responsible AI?"}'
 oris run pipeline.yaml --input-json '{"query":"hi"}' --format pretty --debug
-```
 
-`--debug` prints trace-oriented details on **stderr**; stdout remains the JSON summary. Sample YAML and notebooks live under [`examples/`](examples/).
+
+--debug prints trace-oriented details on **stderr**; stdout remains the JSON summary. Sample YAML and notebooks live under [examples/](examples/).
 
 ## CLI
 
 | Command | Purpose |
 | :--- | :--- |
-| `oris validate <file.yaml>` | Load and validate the pipeline (schema, components, providers). |
-| `oris run <file.yaml> --input-json '<json object>'` | Run with a JSON object as input; default stdout is a compact JSON summary. |
-| `oris run ... --format pretty` | Pretty-printed JSON summary. |
-| `oris run ... --debug` | Stderr: `run_id`, trace status, per-step latency and flags. |
-| `oris validate ... --debug` | Stderr: pipeline name and step list. |
+| oris validate <file.yaml> | Load and validate the pipeline (schema, components, providers). |
+| oris run <file.yaml> --input-json '<json object>' | Run with a JSON object as input; default stdout is a compact JSON summary. |
+| oris run ... --format pretty | Pretty-printed JSON summary. |
+| oris run ... --debug | Stderr: run_id, trace status, per-step latency and flags. |
+| oris validate ... --debug | Stderr: pipeline name and step list. |
 
 ## Output format
 
-`Pipeline.run` returns a **`PipelineResult`**: `output` (dict), `trace` (`RunTrace`), and `metadata`. See [`models.py`](https://github.com/DevStrikerTech/oris/blob/dev/src/oris/runtime/models.py).
+Pipeline.run returns a **PipelineResult**: output (dict), trace (RunTrace), and metadata. See [models.py](https://github.com/DevStrikerTech/oris/blob/dev/src/oris/runtime/models.py).
 
-`result.to_run_summary()` includes:
+result.to_run_summary() includes:
 
-- **`run_id`** — Run identifier.
-- **`status`** — `"success"` or `"failed"` from trace status.
-- **`output`** — Final payload (CLI may redact nested sensitive-looking keys).
-- **`trace`** — Per-step entries: `step_id`, `component_name`, `status`, `latency_ms`, `flags`.
+- **run_id** — Run identifier.
+- **status** — "success" or "failed" from trace status.
+- **output** — Final payload (CLI may redact nested sensitive-looking keys).
+- **trace** — Per-step entries: step_id, component_name, status, latency_ms, flags.
 
-CLI formatting and redaction: [`output.py`](https://github.com/DevStrikerTech/oris/blob/dev/src/oris/cli/output.py).
+CLI formatting and redaction: [output.py](https://github.com/DevStrikerTech/oris/blob/dev/src/oris/cli/output.py).
 
 ## SafeRunner
 
-**[`SafeRunner`](https://github.com/DevStrikerTech/oris/blob/dev/src/oris/integrations/safe_runner.py)** wraps external inference or tools with the same **`PolicyEnforcer`** as the main executor—validate input, run a callable or `run(dict)` target, validate output, optionally attach a one-step trace.
+**[SafeRunner](https://github.com/DevStrikerTech/oris/blob/dev/src/oris/integrations/safe_runner.py)** wraps external inference or tools with the same **PolicyEnforcer** as the main executor—validate input, run a callable or run(dict) target, validate output, optionally attach a one-step trace.
 
-```python
+python
 from oris.integrations import SafeRunner
 from oris.rai.policy import PolicyEnforcer
 
@@ -168,47 +243,658 @@ runner = SafeRunner(my_external_llm, policy=PolicyEnforcer())
 
 plain = runner.run({"query": "Hello"})
 traced = runner.run({"query": "Hello"}, include_trace=True)
-```
 
-Returns are normalized to `dict` from mappings or Pydantic-style `model_dump()`. More detail: [SafeRunner guide](https://devstrikertech.github.io/oris/guides/safe-runner/).
+
+Returns are normalized to dict from mappings or Pydantic-style model_dump(). More detail: [SafeRunner guide](https://devstrikertech.github.io/oris/guides/safe-runner/).
 
 ## Project layout
 
 | Area | Role |
 | :--- | :--- |
-| `oris.core` | Shared enums and exceptions. |
-| `oris.components` | Component registry and built-ins. |
-| `oris.pipeline` | YAML loading, schema, plan, builder. |
-| `oris.runtime` | Executor, orchestrator, hooks, trace manager, `PipelineResult`. |
-| `oris.rai` | `PolicyEnforcer`, input/output guards. |
-| `oris.providers` | `LLMProvider` and built-in YAML provider stubs. |
-| `oris.integrations` | `SafeRunner`. |
-| `oris.tracing` | Run and step trace models. |
-| `oris.cli` | `oris` CLI entrypoint. |
+| oris.core | Shared enums and exceptions. |
+| oris.components | Component registry and built-ins. |
+| oris.pipeline | YAML loading, schema, plan, builder. |
+| oris.runtime | Executor, orchestrator, hooks, trace manager, PipelineResult. |
+| oris.rai | PolicyEnforcer, input/output guards. |
+| oris.providers | LLMProvider and built-in YAML provider stubs. |
+| oris.integrations | SafeRunner. |
+| oris.tracing | Run and step trace models. |
+| oris.cli | oris CLI entrypoint. |
 
 ## Examples and notebooks
 
 | Asset | Description |
 | :--- | :--- |
-| [`examples/simple_generation.yaml`](examples/simple_generation.yaml) | Template step; good first `Pipeline.run`. |
-| [`examples/provider_pipeline.yaml`](examples/provider_pipeline.yaml) | Provider declaration + `generate` (needs `OPENAI_API_KEY` for the stub). |
-| [`examples/basic_pipeline.ipynb`](examples/basic_pipeline.ipynb) | YAML → run → `to_run_summary()`. |
-| [`examples/safe_runner.ipynb`](examples/safe_runner.ipynb) | SafeRunner, traces, policy violations. |
-| [`examples/llm_integration.ipynb`](examples/llm_integration.ipynb) | Optional Ollama + mock fallback; YAML provider stub. |
+| [examples/simple_generation.yaml](examples/simple_generation.yaml) | Template step; good first Pipeline.run. |
+| [examples/provider_pipeline.yaml](examples/provider_pipeline.yaml) | Provider declaration + generate (needs OPENAI_API_KEY for the stub). |
+| [examples/basic_pipeline.ipynb](examples/basic_pipeline.ipynb) | YAML → run → to_run_summary(). |
+| [examples/safe_runner.ipynb](examples/safe_runner.ipynb) | SafeRunner, traces, policy violations. |
+| [examples/llm_integration.ipynb](examples/llm_integration.ipynb) | Optional Ollama + mock fallback; YAML provider stub. |
+
+Execute notebooks from the repo root (after pip install -e ".[dev]"):
+
+bash
+export JUPYTER_CONFIG_DIR="$PWD/.jupyter" && mkdir -p .jupyter
+python -m nbconvert --to notebook --execute examples/basic_pipeline.ipynb --inplace
+
+
+Repeat for the other notebooks, or open them in your editor.
 
-Execute notebooks from the repo root (after `pip install -e ".[dev]"`):
+## Contributing
+
+We welcome issues and pull requests. Start with [CONTRIBUTING.md](CONTRIBUTING.md) (branches, quality gates, tests). Report security issues per [SECURITY.md](SECURITY.md). Community expectations: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+Ah! I see you’ve pasted your full Oris README content. If your goal is to have a single section you can copy-paste directly, I can simplify it into one self-contained block for easy use. Here’s a clean, ready-to-copy version of the Installation + Quick Start + CLI section (most commonly used):
+
+## Installation
+
+Install Oris via pip:
 
 ```bash
+pip install oris-ai
+Verify the CLI:
+
+oris --help
+From source:
+
+git clone https://github.com/DevStrikerTech/oris.git
+cd oris
+python -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e .
+Developers:
+
+pip install -e ".[dev]"
+Requires Python 3.10+. Minimal dependencies (PyYAML).
+
+Quick Start
+Save as pipeline.yaml:
+
+name: quickstart
+settings:
+  tracing: true
+steps:
+  - id: reply
+    type: template_response
+    config:
+      template: "Answer placeholder for: {query}"
+Python usage:
+
+from oris import Pipeline
+
+pipeline = Pipeline.from_yaml("pipeline.yaml")
+result = pipeline.run({"query": "What is responsible AI?"})
+print(result.output)
+CLI usage:
+
+oris validate pipeline.yaml
+oris run pipeline.yaml --input-json '{"query":"What is responsible AI?"}'
+oris run pipeline.yaml --input-json '{"query":"hi"}' --format pretty --debug
+CLI Commands
+Command	Purpose
+oris validate <file.yaml>	Validate the pipeline (schema, components, providers).
+oris run <file.yaml> --input-json '<json object>'	Run pipeline with JSON input; stdout gives JSON summary.
+oris run ... --format pretty	Pretty-printed JSON summary.
+oris run ... --debug	Shows step latency, flags, and run_id in stderr.
+
+This is **one section you can copy** and it includes everything needed to get started immediately without pasting multiple sections.  
+
+If you want, I can make an **even shorter “1-click copy” version** that’s **under 50 lines** including installation + quickstart + CLI + example, perfect for sharing in GitHub README.  
+
+Do you want me to do that?
+
+No i need this Make only SMALL README changes (wording, formatting, minor section cleanup, typo fixes, link fixes). No huge rewrite.
+
+Ah! Got it — you just want a small, careful polish of your existing README: fix typos, clean minor formatting, ensure links work, adjust wording slightly, but keep everything the same. I can do that. Here’s a cleaned-up version of your README with only small changes applied:
+
+<p align="center">   <a href="https://devstrikertech.github.io/oris/">     <img src="docs/images/oris_logo.png" width="180" alt="Oris — Responsible AI pipeline runtime for Python" />   </a> </p>
+CI	CItypes - MypyCoverageRuff
+Docs	WebsiteDocs
+Package	PyPIPyPI - Python VersionLicense
+Meta	IssuesGitHub
+Oris is an open-source Responsible AI runtime for Python. Define pipelines in YAML (or build them in code), run them through one executor, and get input/output policy checks and run- and step-level traces by default.
+
+Oris is framework-agnostic: anything you can invoke like run(dict) can use the same boundaries—including external LLM stacks wrapped with SafeRunner—so you can experiment locally and ship with clearer safety and observability defaults.
+
+Table of Contents
+Installation
+
+Documentation
+
+Features
+
+Quick Start
+
+CLI
+
+Output Format
+
+SafeRunner
+
+Project Layout
+
+Examples and Notebooks
+
+Contributing
+
+License
+
+Installation
+The simplest way to get Oris is via pip:
+
+pip install oris-ai
+Verify the CLI:
+
+oris --help
+From source (library, CLI, and tests):
+
+git clone https://github.com/DevStrikerTech/oris.git
+cd oris
+python -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e .
+Developers (lint, types, tests, notebook execution):
+
+pip install -e ".[dev]"
+Oris requires Python 3.10+. Runtime dependencies are minimal (PyYAML only). For a fuller walkthrough, see the Installation page in the docs.
+
+Documentation
+Start with the Introduction, then follow Installation and Quickstart. The Concepts section explains pipelines, components, providers, RAI, and traces; Guides cover CLI usage, SafeRunner, and run summaries.
+
+Site: devstrikertech.github.io/oris (MkDocs Material, similar to Haystack).
+
+Preview locally:
+
+pip install -e ".[docs]"
+mkdocs serve
+The Docs workflow publishes to GitHub Pages on pushes to prod (.github/workflows/docs.yml). In Settings → Pages, choose GitHub Actions as the source if needed.
+
+Features
+YAML-first pipelines: define steps, optional providers, and settings (tracing, etc.). Configuration is validated before execution.
+
+Guards and policy: default PolicyEnforcer applies input/output checks, including blocked keys, injection heuristics, and PII-shaped patterns. SafeRunner uses the same policy.
+
+Built-in components and provider stubs: includes passthrough, template_response, generate / llm_echo. openai / huggingface provider types are stubs (no network I/O).
+
+Observability: RunTrace provides per-step latency, status, and flags. PipelineResult.to_run_summary() produces JSON-friendly logs and CLI output.
+
+CLI parity: oris validate and oris run match Python definitions; use --format pretty and --debug for human-readable output.
+
+Quick Start
+Save as pipeline.yaml:
+name: quickstart
+settings:
+  tracing: true
+steps:
+  - id: reply
+    type: template_response
+    config:
+      template: "Answer placeholder for: {query}"
+Python
+from oris import Pipeline
+
+pipeline = Pipeline.from_yaml("pipeline.yaml")
+result = pipeline.run({"query": "What is responsible AI?"})
+print(result.output)
+CLI
+oris validate pipeline.yaml
+oris run pipeline.yaml --input-json '{"query":"What is responsible AI?"}'
+oris run pipeline.yaml --input-json '{"query":"hi"}' --format pretty --debug
+CLI
+| Command                                             | Purpose                                            |
+| :-------------------------------------------------- | :------------------------------------------------- |
+| `oris validate <file.yaml>`                         | Validate pipeline (schema, components, providers). |
+| `oris run <file.yaml> --input-json '<json object>'` | Run with JSON input; stdout gives JSON summary.    |
+| `oris run ... --format pretty`                      | Pretty-printed JSON summary.                       |
+| `oris run ... --debug`                              | Shows step latency, flags, and run_id in stderr.   |
+
+Hello
+
+Hello! 😄 How’s your day going?
+
+
+<p align="center">
+  <a href="https://devstrikertech.github.io/oris/">
+    <img src="docs/images/oris_logo.png" width="180" alt="Oris — Responsible AI pipeline runtime for Python" />
+  </a>
+</p>
+
+|         |     |
+| ------- | --- |
+| **CI** | [![CI](https://github.com/DevStrikerTech/oris/actions/workflows/ci.yml/badge.svg?branch=dev)](https://github.com/DevStrikerTech/oris/actions/workflows/ci.yml) [![types - Mypy](https://img.shields.io/badge/types-Mypy-blue.svg)](https://github.com/python/mypy) [![Coverage](https://img.shields.io/badge/coverage-%E2%89%A584%25-brightgreen.svg)](CONTRIBUTING.md#quality-gates) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) |
+| **Docs** | [![Website](https://img.shields.io/website?label=documentation&up_message=online&url=https%3A%2F%2Fdevstrikertech.github.io%2Foris%2F)](https://devstrikertech.github.io/oris/) [![Docs](https://github.com/DevStrikerTech/oris/actions/workflows/docs.yml/badge.svg?branch=prod)](https://github.com/DevStrikerTech/oris/actions/workflows/docs.yml) |
+| **Package** | [![PyPI](https://img.shields.io/pypi/v/oris-ai)](https://pypi.org/project/oris-ai/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/oris-ai?logo=python&logoColor=gold)](https://pypi.org/project/oris-ai/) [![License](https://img.shields.io/github/license/DevStrikerTech/oris)](https://github.com/DevStrikerTech/oris/blob/prod/LICENSE) |
+| **Meta** | [![Issues](https://img.shields.io/github/issues/DevStrikerTech/oris)](https://github.com/DevStrikerTech/oris/issues) [![GitHub](https://img.shields.io/badge/GitHub-DevStrikerTech%2Foris-181717?logo=github)](https://github.com/DevStrikerTech/oris) |
+
+[Oris](https://devstrikertech.github.io /oris/) is an open-source **Responsible AI** runtime for Python. Describe **pipelines** in YAML (or build them in code), run them through one **executor**, and get **input/output policy checks** and **run- and step-level traces** by default.
+
+Oris stays **framework-agnostic**: anything you can invoke like run(dict) can use the same boundaries—including external LLM stacks wrapped with **SafeRunner**—so you can experiment locally and ship with clearer safety and observability defaults.
+
+## Table of contents
+
+- [Installation](#installation)
+- [Documentation](#documentation)
+- [Features](#features)
+- [Quick start](#quick-start)
+- [CLI](#cli)
+- [Output format](#output-format)
+- [SafeRunner](#saferunner)
+- [Project layout](#project-layout)
+- [Examples and notebooks](#examples-and-notebooks)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Installation
+
+The simplest way to get Oris is via pip:
+
+bash
+pip install oris-ai
+
+
+Verify the CLI:
+
+bash
+oris --help
+
+
+**From source** (library, CLI, and tests):
+
+bash
+git clone https://github.com/DevStrikerTech/oris.git
+cd oris
+python -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e .
+
+
+**Developers** (lint, types, tests, notebook execution):
+
+bash
+pip install -e ".[dev]"
+
+
+Oris requires **Python 3.10+**. Runtime dependencies are minimal (**PyYAML** only). For a fuller walkthrough, see the [Installation](https://devstrikertech.github.io/oris/get-started/installation/) page in the docs.
+
+## Documentation
+
+If you are new to the project, start with the [**Introduction**](https://devstrikertech.github.io/oris/), then follow [**Installation**](https://devstrikertech.github.io/oris/get-started/installation/) and [**Quickstart**](https://devstrikertech.github.io/oris/get-started/quickstart/) on the documentation site. The [**Concepts**](https://devstrikertech.github.io/oris/concepts/overview/) section explains pipelines, components, providers, RAI, and traces; [**Guides**](https://devstrikertech.github.io/oris/guides/cli/) cover the CLI, SafeRunner, and run summaries.
+
+**Site:** [devstrikertech.github.io/oris](https://devstrikertech.github.io/oris/) (MkDocs Material, similar information architecture to projects like [Haystack](https://docs.haystack.deepset.ai/docs/intro)).
+
+**Preview locally:**
+
+bash
+pip install -e ".[docs]"
+mkdocs serve
+
+
+The **Docs** workflow publishes to GitHub Pages on pushes to **prod** ([.github/workflows/docs.yml](.github/workflows/docs.yml)). In **Settings → Pages**, choose **GitHub Actions** as the source if needed.
+
+## Features
+
+**YAML-first pipelines**  
+Define steps, optional providers, and settings (such as tracing). Configuration is validated before execution; YAML is loaded with yaml.safe_load only.
+
+**Guards and policy**  
+A default PolicyEnforcer applies input checks (blocked keys, basic injection heuristics, simple PII-shaped patterns) and output checks (blocked terms and test-oriented stubs). The same policy surface is used by **SafeRunner** for external callables.
+
+**Built-in components and provider stubs**  
+Use passthrough, template_response, and generate / llm_echo from the default registry. Declared openai / huggingface provider types are **stubs** (no network I/O in the core package) so CI and demos stay reproducible.
+
+**Observability**  
+Each run produces a RunTrace with per-step latency, status, and flags. PipelineResult.to_run_summary() gives a stable JSON-oriented shape for logs and the CLI (with optional redaction of sensitive-looking keys).
+
+**CLI parity**  
+oris validate and oris run use the same definitions as Pipeline.from_yaml in Python, with --format pretty and --debug for human-friendly output and stderr trace lines.
+
+## Quick start
+
+Save as pipeline.yaml:
+
+yaml
+name: quickstart
+settings:
+  tracing: true
+steps:
+  - id: reply
+    type: template_response
+    config:
+      template: "Answer placeholder for: {query}"
+
+
+**Python**
+
+python
+from oris import Pipeline
+
+pipeline = Pipeline.from_yaml("pipeline.yaml")
+result = pipeline.run({"query": "What is responsible AI?"})
+
+print(result.output)
+
+
+**CLI**
+
+bash
+oris validate pipeline.yaml
+oris run pipeline.yaml --input-json '{"query":"What is responsible AI?"}'
+oris run pipeline.yaml --input-json '{"query":"hi"}' --format pretty --debug
+
+
+--debug prints trace-oriented details on **stderr**; stdout remains the JSON summary. Sample YAML and notebooks live under [examples/](examples/).
+
+## CLI
+
+| Command | Purpose |
+| :--- | :--- |
+| oris validate <file.yaml> | Load and validate the pipeline (schema, components, providers). |
+| oris run <file.yaml> --input-json '<json object>' | Run with a JSON object as input; default stdout is a compact JSON summary. |
+| oris run ... --format pretty | Pretty-printed JSON summary. |
+| oris run ... --debug | Stderr: run_id, trace status, per-step latency and flags. |
+| oris validate ... --debug | Stderr: pipeline name and step list. |
+
+## Output format
+
+Pipeline.run returns a **PipelineResult**: output (dict), trace (RunTrace), and metadata. See [models.py](https://github.com/DevStrikerTech/oris/blob/dev/src/oris/runtime/models.py).
+
+result.to_run_summary() includes:
+
+- **run_id** — Run identifier.
+- **status** — "success" or "failed" from trace status.
+- **output** — Final payload (CLI may redact nested sensitive-looking keys).
+- **trace** — Per-step entries: step_id, component_name, status, latency_ms, flags.
+
+CLI formatting and redaction: [output.py](https://github.com/DevStrikerTech/oris/blob/dev/src/oris/cli/output.py).
+
+## SafeRunner
+
+**[SafeRunner](https://github.com/DevStrikerTech/oris/blob/dev/src/oris/integrations/safe_runner.py)** wraps external inference or tools with the same **PolicyEnforcer** as the main executor—validate input, run a callable or run(dict) target, validate output, optionally attach a one-step trace.
+
+python
+from oris.integrations import SafeRunner
+from oris.rai.policy import PolicyEnforcer
+
+def my_external_llm(payload: dict) -> dict:
+    q = payload.get("query", "")
+    return {"output": f"stub response for: {q!r}"}
+
+runner = SafeRunner(my_external_llm, policy=PolicyEnforcer())
+
+plain = runner.run({"query": "Hello"})
+traced = runner.run({"query": "Hello"}, include_trace=True)
+
+
+Returns are normalized to dict from mappings or Pydantic-style model_dump(). More detail: [SafeRunner guide](https://devstrikertech.github.io/oris/guides/safe-runner/).
+
+## Project layout
+
+| Area | Role |
+| :--- | :--- |
+| oris.core | Shared enums and exceptions. |
+| oris.components | Component registry and built-ins. |
+| oris.pipeline | YAML loading, schema, plan, builder. |
+| oris.runtime | Executor, orchestrator, hooks, trace manager, PipelineResult. |
+| oris.rai | PolicyEnforcer, input/output guards. |
+| oris.providers | LLMProvider and built-in YAML provider stubs. |
+| oris.integrations | SafeRunner. |
+| oris.tracing | Run and step trace models. |
+| oris.cli | oris CLI entrypoint. |
+
+## Examples and notebooks
+
+| Asset | Description |
+| :--- | :--- |
+| [examples/simple_generation.yaml](examples/simple_generation.yaml) | Template step; good first Pipeline.run. |
+| [examples/provider_pipeline.yaml](examples/provider_pipeline.yaml) | Provider declaration + generate (needs OPENAI_API_KEY for the stub). |
+| [examples/basic_pipeline.ipynb](examples/basic_pipeline.ipynb) | YAML → run → to_run_summary(). |
+| [examples/safe_runner.ipynb](examples/safe_runner.ipynb) | SafeRunner, traces, policy violations. |
+| [examples/llm_integration.ipynb](examples/llm_integration.ipynb) | Optional Ollama + mock fallback; YAML provider stub. |
+
+Execute notebooks from the repo root (after pip install -e ".[dev]"):
+
+bash
 export JUPYTER_CONFIG_DIR="$PWD/.jupyter" && mkdir -p .jupyter
 python -m nbconvert --to notebook --execute examples/basic_pipeline.ipynb --inplace
-```
+
 
 Repeat for the other notebooks, or open them in your editor.
 
 ## Contributing
 
-We welcome issues and pull requests. Start with [`CONTRIBUTING.md`](CONTRIBUTING.md) (branches, quality gates, tests). Report security issues per [`SECURITY.md`](SECURITY.md). Community expectations: [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md).
+We welcome issues and pull requests. Start with [CONTRIBUTING.md](CONTRIBUTING.md) (branches, quality gates, tests). Report security issues per [SECURITY.md](SECURITY.md). Community expectations: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
 
 ## License
 
-MIT — see [`LICENSE`](LICENSE).
+MIT — see [LICENSE](LICENSE).
+
+Ah! I see you’ve pasted your full Oris README content. If your goal is to have a single section you can copy-paste directly, I can simplify it into one self-contained block for easy use. Here’s a clean, ready-to-copy version of the Installation + Quick Start + CLI section (most commonly used):
+
+## Installation
+
+Install Oris via pip:
+
+```bash
+pip install oris-ai
+Verify the CLI:
+
+oris --help
+From source:
+
+git clone https://github.com/DevStrikerTech/oris.git
+cd oris
+python -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e .
+Developers:
+
+pip install -e ".[dev]"
+Requires Python 3.10+. Minimal dependencies (PyYAML).
+
+Quick Start
+Save as pipeline.yaml:
+
+name: quickstart
+settings:
+  tracing: true
+steps:
+  - id: reply
+    type: template_response
+    config:
+      template: "Answer placeholder for: {query}"
+Python usage:
+
+from oris import Pipeline
+
+pipeline = Pipeline.from_yaml("pipeline.yaml")
+result = pipeline.run({"query": "What is responsible AI?"})
+print(result.output)
+CLI usage:
+
+oris validate pipeline.yaml
+oris run pipeline.yaml --input-json '{"query":"What is responsible AI?"}'
+oris run pipeline.yaml --input-json '{"query":"hi"}' --format pretty --debug
+CLI Commands
+Command	Purpose
+oris validate <file.yaml>	Validate the pipeline (schema, components, providers).
+oris run <file.yaml> --input-json '<json object>'	Run pipeline with JSON input; stdout gives JSON summary.
+oris run ... --format pretty	Pretty-printed JSON summary.
+oris run ... --debug	Shows step latency, flags, and run_id in stderr.
+
+This is **one section you can copy** and it includes everything needed to get started immediately without pasting multiple sections.  
+
+If you want, I can make an **even shorter “1-click copy” version** that’s **under 50 lines** including installation + quickstart + CLI + example, perfect for sharing in GitHub README.  
+
+Do you want me to do that?
+
+No i need this Make only SMALL README changes (wording, formatting, minor section cleanup, typo fixes, link fixes). No huge rewrite.
+
+Ah! Got it — you just want a small, careful polish of your existing README: fix typos, clean minor formatting, ensure links work, adjust wording slightly, but keep everything the same. I can do that. Here’s a cleaned-up version of your README with only small changes applied:
+
+<p align="center">   <a href="https://devstrikertech.github.io/oris/">     <img src="docs/images/oris_logo.png" width="180" alt="Oris — Responsible AI pipeline runtime for Python" />   </a> </p>
+CI	CItypes - MypyCoverageRuff
+Docs	WebsiteDocs
+Package	PyPIPyPI - Python VersionLicense
+Meta	IssuesGitHub
+Oris is an open-source Responsible AI runtime for Python. Define pipelines in YAML (or build them in code), run them through one executor, and get input/output policy checks and run- and step-level traces by default.
+
+Oris is framework-agnostic: anything you can invoke like run(dict) can use the same boundaries—including external LLM stacks wrapped with SafeRunner—so you can experiment locally and ship with clearer safety and observability defaults.
+
+Table of Contents
+Installation
+
+Documentation
+
+Features
+
+Quick Start
+
+CLI
+
+Output Format
+
+SafeRunner
+
+Project Layout
+
+Examples and Notebooks
+
+Contributing
+
+License
+
+Installation
+The simplest way to get Oris is via pip:
+
+pip install oris-ai
+Verify the CLI:
+
+oris --help
+From source (library, CLI, and tests):
+
+git clone https://github.com/DevStrikerTech/oris.git
+cd oris
+python -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e .
+Developers (lint, types, tests, notebook execution):
+
+pip install -e ".[dev]"
+Oris requires Python 3.10+. Runtime dependencies are minimal (PyYAML only). For a fuller walkthrough, see the Installation page in the docs.
+
+Documentation
+Start with the Introduction, then follow Installation and Quickstart. The Concepts section explains pipelines, components, providers, RAI, and traces; Guides cover CLI usage, SafeRunner, and run summaries.
+
+Site: devstrikertech.github.io/oris (MkDocs Material, similar to Haystack).
+
+Preview locally:
+
+pip install -e ".[docs]"
+mkdocs serve
+The Docs workflow publishes to GitHub Pages on pushes to prod (.github/workflows/docs.yml). In Settings → Pages, choose GitHub Actions as the source if needed.
+
+Features
+YAML-first pipelines: define steps, optional providers, and settings (tracing, etc.). Configuration is validated before execution.
+
+Guards and policy: default PolicyEnforcer applies input/output checks, including blocked keys, injection heuristics, and PII-shaped patterns. SafeRunner uses the same policy.
+
+Built-in components and provider stubs: includes passthrough, template_response, generate / llm_echo. openai / huggingface provider types are stubs (no network I/O).
+
+Observability: RunTrace provides per-step latency, status, and flags. PipelineResult.to_run_summary() produces JSON-friendly logs and CLI output.
+
+CLI parity: oris validate and oris run match Python definitions; use --format pretty and --debug for human-readable output.
+
+Quick Start
+Save as pipeline.yaml:
+
+name: quickstart
+settings:
+  tracing: true
+steps:
+  - id: reply
+    type: template_response
+    config:
+      template: "Answer placeholder for: {query}"
+Python
+
+from oris import Pipeline
+
+pipeline = Pipeline.from_yaml("pipeline.yaml")
+result = pipeline.run({"query": "What is responsible AI?"})
+print(result.output)
+CLI
+
+oris validate pipeline.yaml
+oris run pipeline.yaml --input-json '{"query":"What is responsible AI?"}'
+oris run pipeline.yaml --input-json '{"query":"hi"}' --format pretty --debug
+CLI
+Command	Purpose
+oris validate <file.yaml>	Validate pipeline (schema, components, providers).
+oris run <file.yaml> --input-json '<json object>'	Run with JSON input; stdout gives JSON summary.
+oris run ... --format pretty	Pretty-printed JSON summary.
+oris run ... --debug	Shows step latency, flags, and run_id in stderr.
+Output Format
+Pipeline.run returns a PipelineResult: output (dict), trace (RunTrace), metadata. See models.py.
+
+result.to_run_summary() includes:
+
+run_id — Run identifier.
+
+status — "success" or "failed".
+
+output — Final payload (CLI may redact sensitive keys).
+
+trace — Step entries: step_id, component_name, status, latency_ms, flags.
+SafeRunner
+
+SafeRunner
+ wraps external callables with the same PolicyEnforcer.
+from oris.integrations import SafeRunner
+from oris.rai.policy import PolicyEnforcer
+
+def my_external_llm(payload: dict) -> dict:
+    q = payload.get("query", "")
+    return {"output": f"stub response for: {q!r}"}
+
+runner = SafeRunner(my_external_llm, policy=PolicyEnforcer())
+plain = runner.run({"query": "Hello"})
+traced = runner.run({"query": "Hello"}, include_trace=True)
+Returns are normalized to dict.
+
+Project Layout
+| Area                | Role                                                            |
+| :------------------ | :-------------------------------------------------------------- |
+| `oris.core`         | Enums and exceptions.                                           |
+| `oris.components`   | Component registry and built-ins.                               |
+| `oris.pipeline`     | YAML loading, schema, plan, builder.                            |
+| `oris.runtime`      | Executor, orchestrator, hooks, trace manager, `PipelineResult`. |
+| `oris.rai`          | `PolicyEnforcer`, input/output guards.                          |
+| `oris.providers`    | `LLMProvider` and provider stubs.                               |
+| `oris.integrations` | `SafeRunner`.                                                   |
+| `oris.tracing`      | Run and step trace models.                                      |
+| `oris.cli`          | CLI entrypoint.                                                 |
+| Asset                                                                | Description                                                 |
+| :------------------------------------------------------------------- | :---------------------------------------------------------- |
+| [`examples/simple_generation.yaml`](examples/simple_generation.yaml) | Template step; first `Pipeline.run`.                        |
+| [`examples/provider_pipeline.yaml`](examples/provider_pipeline.yaml) | Provider declaration + `generate` (needs `OPENAI_API_KEY`). |
+| [`examples/basic_pipeline.ipynb`](examples/basic_pipeline.ipynb)     | YAML → run → `to_run_summary()`.                            |
+| [`examples/safe_runner.ipynb`](examples/safe_runner.ipynb)           | SafeRunner, traces, policy violations.                      |
+| [`examples/llm_integration.ipynb`](examples/llm_integration.ipynb)   | Optional Ollama + mock fallback.                            |
+Execute notebooks from repo root:
+export JUPYTER_CONFIG_DIR="$PWD/.jupyter" && mkdir -p .jupyter
+python -m nbconvert --to notebook --execute examples/basic_pipeline.ipynb --inplace
+Repeat for other notebooks.
+
+Contributing
+
+See CONTRIBUTING.md
+, SECURITY.md
+, CODE_OF_CONDUCT.md
+. We welcome issues and PRs.
+License
+
+MIT — see LICENSE.

From 2d0adefd84fc6e048939d7df83f417fabce212d8 Mon Sep 17 00:00:00 2001
From: Mohamed Jadla <jadlamed444@gmail.com>
Date: Thu, 9 Apr 2026 19:22:34 +0100
Subject: [PATCH 02/12] docs: small README improvements

Removed introductory text and logo from README.
---
 README.md | 82 -------------------------------------------------------
 1 file changed, 82 deletions(-)

diff --git a/README.md b/README.md
index 1e36ae8..1e3a85f 100644
--- a/README.md
+++ b/README.md
@@ -1,86 +1,4 @@
-<p align="center">
-  <a href="https://devstrikertech.github.io/oris/">
-    <img src="docs/images/oris_logo.png" width="180" alt="Oris — Responsible AI pipeline runtime for Python" />
-  </a>
-</p>
-
-|         |     |
-| ------- | --- |
-| **CI** | [![CI](https://github.com/DevStrikerTech/oris/actions/workflows/ci.yml/badge.svg?branch=dev)](https://github.com/DevStrikerTech/oris/actions/workflows/ci.yml) [![types - Mypy](https://img.shields.io/badge/types-Mypy-blue.svg)](https://github.com/python/mypy) [![Coverage](https://img.shields.io/badge/coverage-%E2%89%A584%25-brightgreen.svg)](CONTRIBUTING.md#quality-gates) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) |
-| **Docs** | [![Website](https://img.shields.io/website?label=documentation&up_message=online&url=https%3A%2F%2Fdevstrikertech.github.io%2Foris%2F)](https://devstrikertech.github.io/oris/) [![Docs](https://github.com/DevStrikerTech/oris/actions/workflows/docs.yml/badge.svg?branch=prod)](https://github.com/DevStrikerTech/oris/actions/workflows/docs.yml) |
-| **Package** | [![PyPI](https://img.shields.io/pypi/v/oris-ai)](https://pypi.org/project/oris-ai/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/oris-ai?logo=python&logoColor=gold)](https://pypi.org/project/oris-ai/) [![License](https://img.shields.io/github/license/DevStrikerTech/oris)](https://github.com/DevStrikerTech/oris/blob/prod/LICENSE) |
-| **Meta** | [![Issues](https://img.shields.io/github/issues/DevStrikerTech/oris)](https://github.com/DevStrikerTech/oris/issues) [![GitHub](https://img.shields.io/badge/GitHub-DevStrikerTech%2Foris-181717?logo=github)](https://github.com/DevStrikerTech/oris) |
-
-[Oris](https://devstrikertech.github.io/oris/) 
-Oris
- is an open-source Responsible AI runtime for Python. Define pipelines in YAML (or build them in code), run them through one executor, and get input/output policy checks and run- and step-level traces by default.
-
-Oris is framework-agnostic: anything you can invoke like run(dict) can use the same boundaries—including external LLM stacks wrapped with SafeRunner—so you can experiment locally and ship with clearer safety and observability defaults.
-Table of Contents
-Installation
-Documentation
-Features
-Quick Start
-CLI
-Output Format
-SafeRunner
-Project Layout
-Examples and Notebooks
-Contributing
-License
-Installation
-
-The simplest way to get Oris is via pip:
-pip install oris-ai
-Verify the CLI:
-oris --help
-From source (library, CLI, and tests):
-git clone https://github.com/DevStrikerTech/oris.git
-cd oris
-python -m venv .venv
-source .venv/bin/activate   # Windows: .venv\Scripts\activate
-pip install -e .
-Developers (lint, types, tests, notebook execution):
-pip install -e ".[dev]"
-Oris requires Python 3.10+. Runtime dependencies are minimal (PyYAML only). For a fuller walkthrough, see the Installation
- page in the docs.
 
-Documentation
-Start with the Introduction
-, then follow Installation
- and Quickstart
-. The Concepts
- section explains pipelines, components, providers, RAI, and traces; Guides
- cover CLI usage, SafeRunner, and run summaries.
-
-Site: devstrikertech.github.io/oris
- (MkDocs Material, similar to Haystack
-).
-
-Preview locally:
-pip install -e ".[docs]"
-mkdocs serve
-The Docs workflow publishes to GitHub Pages on pushes to prod (.github/workflows/docs.yml
-). In Settings → Pages, choose GitHub Actions as the source if needed.
-
-Features
-YAML-first pipelines: define steps, optional providers, and settings (tracing, etc.). Configuration is validated before execution.
-
-Guards and policy: default PolicyEnforcer applies input/output checks, including blocked keys, injection heuristics, and PII-shaped patterns. SafeRunner uses the same policy.
-
-Hello
-
-Hello! 😄 How’s your day going?
-
-
-<p align="center">
-  <a href="https://devstrikertech.github.io/oris/">
-    <img src="docs/images/oris_logo.png" width="180" alt="Oris — Responsible AI pipeline runtime for Python" />
-  </a>
-</p>
-
-|         |     |
-| ------- | --- |
 | **CI** | [![CI](https://github.com/DevStrikerTech/oris/actions/workflows/ci.yml/badge.svg?branch=dev)](https://github.com/DevStrikerTech/oris/actions/workflows/ci.yml) [![types - Mypy](https://img.shields.io/badge/types-Mypy-blue.svg)](https://github.com/python/mypy) [![Coverage](https://img.shields.io/badge/coverage-%E2%89%A584%25-brightgreen.svg)](CONTRIBUTING.md#quality-gates) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) |
 | **Docs** | [![Website](https://img.shields.io/website?label=documentation&up_message=online&url=https%3A%2F%2Fdevstrikertech.github.io%2Foris%2F)](https://devstrikertech.github.io/oris/) [![Docs](https://github.com/DevStrikerTech/oris/actions/workflows/docs.yml/badge.svg?branch=prod)](https://github.com/DevStrikerTech/oris/actions/workflows/docs.yml) |
 | **Package** | [![PyPI](https://img.shields.io/pypi/v/oris-ai)](https://pypi.org/project/oris-ai/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/oris-ai?logo=python&logoColor=gold)](https://pypi.org/project/oris-ai/) [![License](https://img.shields.io/github/license/DevStrikerTech/oris)](https://github.com/DevStrikerTech/oris/blob/prod/LICENSE) |

From 64f201d874824918376003bc5aa253142be35227 Mon Sep 17 00:00:00 2001
From: Mohamed Jadla <jadlamed444@gmail.com>
Date: Thu, 9 Apr 2026 19:23:11 +0100
Subject: [PATCH 03/12] docs: small README improvements

---
 README.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 1e3a85f..940bb88 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,4 @@
-
-| **CI** | [![CI](https://github.com/DevStrikerTech/oris/actions/workflows/ci.yml/badge.svg?branch=dev)](https://github.com/DevStrikerTech/oris/actions/workflows/ci.yml) [![types - Mypy](https://img.shields.io/badge/types-Mypy-blue.svg)](https://github.com/python/mypy) [![Coverage](https://img.shields.io/badge/coverage-%E2%89%A584%25-brightgreen.svg)](CONTRIBUTING.md#quality-gates) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) |
+ [![CI](https://github.com/DevStrikerTech/oris/actions/workflows/ci.yml/badge.svg?branch=dev)](https://github.com/DevStrikerTech/oris/actions/workflows/ci.yml) [![types - Mypy](https://img.shields.io/badge/types-Mypy-blue.svg)](https://github.com/python/mypy) [![Coverage](https://img.shields.io/badge/coverage-%E2%89%A584%25-brightgreen.svg)](CONTRIBUTING.md#quality-gates) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) |
 | **Docs** | [![Website](https://img.shields.io/website?label=documentation&up_message=online&url=https%3A%2F%2Fdevstrikertech.github.io%2Foris%2F)](https://devstrikertech.github.io/oris/) [![Docs](https://github.com/DevStrikerTech/oris/actions/workflows/docs.yml/badge.svg?branch=prod)](https://github.com/DevStrikerTech/oris/actions/workflows/docs.yml) |
 | **Package** | [![PyPI](https://img.shields.io/pypi/v/oris-ai)](https://pypi.org/project/oris-ai/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/oris-ai?logo=python&logoColor=gold)](https://pypi.org/project/oris-ai/) [![License](https://img.shields.io/github/license/DevStrikerTech/oris)](https://github.com/DevStrikerTech/oris/blob/prod/LICENSE) |
 | **Meta** | [![Issues](https://img.shields.io/github/issues/DevStrikerTech/oris)](https://github.com/DevStrikerTech/oris/issues) [![GitHub](https://img.shields.io/badge/GitHub-DevStrikerTech%2Foris-181717?logo=github)](https://github.com/DevStrikerTech/oris) |

From 5d141cc92a3de380a34ff9d0828543017aaa7738 Mon Sep 17 00:00:00 2001
From: Mohamed Jadla <jadlamed444@gmail.com>
Date: Thu, 9 Apr 2026 19:32:36 +0100
Subject: [PATCH 04/12] docs: small README improvements

---
 README.md | 384 ------------------------------------------------------
 1 file changed, 384 deletions(-)

diff --git a/README.md b/README.md
index 940bb88..d1e49fc 100644
--- a/README.md
+++ b/README.md
@@ -1,387 +1,3 @@
- [![CI](https://github.com/DevStrikerTech/oris/actions/workflows/ci.yml/badge.svg?branch=dev)](https://github.com/DevStrikerTech/oris/actions/workflows/ci.yml) [![types - Mypy](https://img.shields.io/badge/types-Mypy-blue.svg)](https://github.com/python/mypy) [![Coverage](https://img.shields.io/badge/coverage-%E2%89%A584%25-brightgreen.svg)](CONTRIBUTING.md#quality-gates) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) |
-| **Docs** | [![Website](https://img.shields.io/website?label=documentation&up_message=online&url=https%3A%2F%2Fdevstrikertech.github.io%2Foris%2F)](https://devstrikertech.github.io/oris/) [![Docs](https://github.com/DevStrikerTech/oris/actions/workflows/docs.yml/badge.svg?branch=prod)](https://github.com/DevStrikerTech/oris/actions/workflows/docs.yml) |
-| **Package** | [![PyPI](https://img.shields.io/pypi/v/oris-ai)](https://pypi.org/project/oris-ai/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/oris-ai?logo=python&logoColor=gold)](https://pypi.org/project/oris-ai/) [![License](https://img.shields.io/github/license/DevStrikerTech/oris)](https://github.com/DevStrikerTech/oris/blob/prod/LICENSE) |
-| **Meta** | [![Issues](https://img.shields.io/github/issues/DevStrikerTech/oris)](https://github.com/DevStrikerTech/oris/issues) [![GitHub](https://img.shields.io/badge/GitHub-DevStrikerTech%2Foris-181717?logo=github)](https://github.com/DevStrikerTech/oris) |
-
-[Oris](https://devstrikertech.github.io /oris/) is an open-source **Responsible AI** runtime for Python. Describe **pipelines** in YAML (or build them in code), run them through one **executor**, and get **input/output policy checks** and **run- and step-level traces** by default.
-
-Oris stays **framework-agnostic**: anything you can invoke like run(dict) can use the same boundaries—including external LLM stacks wrapped with **SafeRunner**—so you can experiment locally and ship with clearer safety and observability defaults.
-
-## Table of contents
-
-- [Installation](#installation)
-- [Documentation](#documentation)
-- [Features](#features)
-- [Quick start](#quick-start)
-- [CLI](#cli)
-- [Output format](#output-format)
-- [SafeRunner](#saferunner)
-- [Project layout](#project-layout)
-- [Examples and notebooks](#examples-and-notebooks)
-- [Contributing](#contributing)
-- [License](#license)
-
-## Installation
-
-The simplest way to get Oris is via pip:
-
-bash
-pip install oris-ai
-
-
-Verify the CLI:
-
-bash
-oris --help
-
-
-**From source** (library, CLI, and tests):
-
-bash
-git clone https://github.com/DevStrikerTech/oris.git
-cd oris
-python -m venv .venv
-source .venv/bin/activate   # Windows: .venv\Scripts\activate
-pip install -e .
-
-
-**Developers** (lint, types, tests, notebook execution):
-
-bash
-pip install -e ".[dev]"
-
-
-Oris requires **Python 3.10+**. Runtime dependencies are minimal (**PyYAML** only). For a fuller walkthrough, see the [Installation](https://devstrikertech.github.io/oris/get-started/installation/) page in the docs.
-
-## Documentation
-
-If you are new to the project, start with the [**Introduction**](https://devstrikertech.github.io/oris/), then follow [**Installation**](https://devstrikertech.github.io/oris/get-started/installation/) and [**Quickstart**](https://devstrikertech.github.io/oris/get-started/quickstart/) on the documentation site. The [**Concepts**](https://devstrikertech.github.io/oris/concepts/overview/) section explains pipelines, components, providers, RAI, and traces; [**Guides**](https://devstrikertech.github.io/oris/guides/cli/) cover the CLI, SafeRunner, and run summaries.
-
-**Site:** [devstrikertech.github.io/oris](https://devstrikertech.github.io/oris/) (MkDocs Material, similar information architecture to projects like [Haystack](https://docs.haystack.deepset.ai/docs/intro)).
-
-**Preview locally:**
-
-bash
-pip install -e ".[docs]"
-mkdocs serve
-
-
-The **Docs** workflow publishes to GitHub Pages on pushes to **prod** ([.github/workflows/docs.yml](.github/workflows/docs.yml)). In **Settings → Pages**, choose **GitHub Actions** as the source if needed.
-
-## Features
-
-**YAML-first pipelines**  
-Define steps, optional providers, and settings (such as tracing). Configuration is validated before execution; YAML is loaded with yaml.safe_load only.
-
-**Guards and policy**  
-A default PolicyEnforcer applies input checks (blocked keys, basic injection heuristics, simple PII-shaped patterns) and output checks (blocked terms and test-oriented stubs). The same policy surface is used by **SafeRunner** for external callables.
-
-**Built-in components and provider stubs**  
-Use passthrough, template_response, and generate / llm_echo from the default registry. Declared openai / huggingface provider types are **stubs** (no network I/O in the core package) so CI and demos stay reproducible.
-
-**Observability**  
-Each run produces a RunTrace with per-step latency, status, and flags. PipelineResult.to_run_summary() gives a stable JSON-oriented shape for logs and the CLI (with optional redaction of sensitive-looking keys).
-
-**CLI parity**  
-oris validate and oris run use the same definitions as Pipeline.from_yaml in Python, with --format pretty and --debug for human-friendly output and stderr trace lines.
-
-## Quick start
-
-Save as pipeline.yaml:
-
-yaml
-name: quickstart
-settings:
-  tracing: true
-steps:
-  - id: reply
-    type: template_response
-    config:
-      template: "Answer placeholder for: {query}"
-
-
-**Python**
-
-python
-from oris import Pipeline
-
-pipeline = Pipeline.from_yaml("pipeline.yaml")
-result = pipeline.run({"query": "What is responsible AI?"})
-
-print(result.output)
-
-
-**CLI**
-
-bash
-oris validate pipeline.yaml
-oris run pipeline.yaml --input-json '{"query":"What is responsible AI?"}'
-oris run pipeline.yaml --input-json '{"query":"hi"}' --format pretty --debug
-
-
---debug prints trace-oriented details on **stderr**; stdout remains the JSON summary. Sample YAML and notebooks live under [examples/](examples/).
-
-## CLI
-
-| Command | Purpose |
-| :--- | :--- |
-| oris validate <file.yaml> | Load and validate the pipeline (schema, components, providers). |
-| oris run <file.yaml> --input-json '<json object>' | Run with a JSON object as input; default stdout is a compact JSON summary. |
-| oris run ... --format pretty | Pretty-printed JSON summary. |
-| oris run ... --debug | Stderr: run_id, trace status, per-step latency and flags. |
-| oris validate ... --debug | Stderr: pipeline name and step list. |
-
-## Output format
-
-Pipeline.run returns a **PipelineResult**: output (dict), trace (RunTrace), and metadata. See [models.py](https://github.com/DevStrikerTech/oris/blob/dev/src/oris/runtime/models.py).
-
-result.to_run_summary() includes:
-
-- **run_id** — Run identifier.
-- **status** — "success" or "failed" from trace status.
-- **output** — Final payload (CLI may redact nested sensitive-looking keys).
-- **trace** — Per-step entries: step_id, component_name, status, latency_ms, flags.
-
-CLI formatting and redaction: [output.py](https://github.com/DevStrikerTech/oris/blob/dev/src/oris/cli/output.py).
-
-## SafeRunner
-
-**[SafeRunner](https://github.com/DevStrikerTech/oris/blob/dev/src/oris/integrations/safe_runner.py)** wraps external inference or tools with the same **PolicyEnforcer** as the main executor—validate input, run a callable or run(dict) target, validate output, optionally attach a one-step trace.
-
-python
-from oris.integrations import SafeRunner
-from oris.rai.policy import PolicyEnforcer
-
-def my_external_llm(payload: dict) -> dict:
-    q = payload.get("query", "")
-    return {"output": f"stub response for: {q!r}"}
-
-runner = SafeRunner(my_external_llm, policy=PolicyEnforcer())
-
-plain = runner.run({"query": "Hello"})
-traced = runner.run({"query": "Hello"}, include_trace=True)
-
-
-Returns are normalized to dict from mappings or Pydantic-style model_dump(). More detail: [SafeRunner guide](https://devstrikertech.github.io/oris/guides/safe-runner/).
-
-## Project layout
-
-| Area | Role |
-| :--- | :--- |
-| oris.core | Shared enums and exceptions. |
-| oris.components | Component registry and built-ins. |
-| oris.pipeline | YAML loading, schema, plan, builder. |
-| oris.runtime | Executor, orchestrator, hooks, trace manager, PipelineResult. |
-| oris.rai | PolicyEnforcer, input/output guards. |
-| oris.providers | LLMProvider and built-in YAML provider stubs. |
-| oris.integrations | SafeRunner. |
-| oris.tracing | Run and step trace models. |
-| oris.cli | oris CLI entrypoint. |
-
-## Examples and notebooks
-
-| Asset | Description |
-| :--- | :--- |
-| [examples/simple_generation.yaml](examples/simple_generation.yaml) | Template step; good first Pipeline.run. |
-| [examples/provider_pipeline.yaml](examples/provider_pipeline.yaml) | Provider declaration + generate (needs OPENAI_API_KEY for the stub). |
-| [examples/basic_pipeline.ipynb](examples/basic_pipeline.ipynb) | YAML → run → to_run_summary(). |
-| [examples/safe_runner.ipynb](examples/safe_runner.ipynb) | SafeRunner, traces, policy violations. |
-| [examples/llm_integration.ipynb](examples/llm_integration.ipynb) | Optional Ollama + mock fallback; YAML provider stub. |
-
-Execute notebooks from the repo root (after pip install -e ".[dev]"):
-
-bash
-export JUPYTER_CONFIG_DIR="$PWD/.jupyter" && mkdir -p .jupyter
-python -m nbconvert --to notebook --execute examples/basic_pipeline.ipynb --inplace
-
-
-Repeat for the other notebooks, or open them in your editor.
-
-## Contributing
-
-We welcome issues and pull requests. Start with [CONTRIBUTING.md](CONTRIBUTING.md) (branches, quality gates, tests). Report security issues per [SECURITY.md](SECURITY.md). Community expectations: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
-
-## License
-
-MIT — see [LICENSE](LICENSE).
-
-Ah! I see you’ve pasted your full Oris README content. If your goal is to have a single section you can copy-paste directly, I can simplify it into one self-contained block for easy use. Here’s a clean, ready-to-copy version of the Installation + Quick Start + CLI section (most commonly used):
-
-## Installation
-
-Install Oris via pip:
-
-```bash
-pip install oris-ai
-Verify the CLI:
-
-oris --help
-From source:
-
-git clone https://github.com/DevStrikerTech/oris.git
-cd oris
-python -m venv .venv
-source .venv/bin/activate   # Windows: .venv\Scripts\activate
-pip install -e .
-Developers:
-
-pip install -e ".[dev]"
-Requires Python 3.10+. Minimal dependencies (PyYAML).
-
-Quick Start
-Save as pipeline.yaml:
-
-name: quickstart
-settings:
-  tracing: true
-steps:
-  - id: reply
-    type: template_response
-    config:
-      template: "Answer placeholder for: {query}"
-Python usage:
-
-from oris import Pipeline
-
-pipeline = Pipeline.from_yaml("pipeline.yaml")
-result = pipeline.run({"query": "What is responsible AI?"})
-print(result.output)
-CLI usage:
-
-oris validate pipeline.yaml
-oris run pipeline.yaml --input-json '{"query":"What is responsible AI?"}'
-oris run pipeline.yaml --input-json '{"query":"hi"}' --format pretty --debug
-CLI Commands
-Command	Purpose
-oris validate <file.yaml>	Validate the pipeline (schema, components, providers).
-oris run <file.yaml> --input-json '<json object>'	Run pipeline with JSON input; stdout gives JSON summary.
-oris run ... --format pretty	Pretty-printed JSON summary.
-oris run ... --debug	Shows step latency, flags, and run_id in stderr.
-
-This is **one section you can copy** and it includes everything needed to get started immediately without pasting multiple sections.  
-
-If you want, I can make an **even shorter “1-click copy” version** that’s **under 50 lines** including installation + quickstart + CLI + example, perfect for sharing in GitHub README.  
-
-Do you want me to do that?
-
-No i need this Make only SMALL README changes (wording, formatting, minor section cleanup, typo fixes, link fixes). No huge rewrite.
-
-Ah! Got it — you just want a small, careful polish of your existing README: fix typos, clean minor formatting, ensure links work, adjust wording slightly, but keep everything the same. I can do that. Here’s a cleaned-up version of your README with only small changes applied:
-
-<p align="center">   <a href="https://devstrikertech.github.io/oris/">     <img src="docs/images/oris_logo.png" width="180" alt="Oris — Responsible AI pipeline runtime for Python" />   </a> </p>
-CI	CItypes - MypyCoverageRuff
-Docs	WebsiteDocs
-Package	PyPIPyPI - Python VersionLicense
-Meta	IssuesGitHub
-Oris is an open-source Responsible AI runtime for Python. Define pipelines in YAML (or build them in code), run them through one executor, and get input/output policy checks and run- and step-level traces by default.
-
-Oris is framework-agnostic: anything you can invoke like run(dict) can use the same boundaries—including external LLM stacks wrapped with SafeRunner—so you can experiment locally and ship with clearer safety and observability defaults.
-
-Table of Contents
-Installation
-
-Documentation
-
-Features
-
-Quick Start
-
-CLI
-
-Output Format
-
-SafeRunner
-
-Project Layout
-
-Examples and Notebooks
-
-Contributing
-
-License
-
-Installation
-The simplest way to get Oris is via pip:
-
-pip install oris-ai
-Verify the CLI:
-
-oris --help
-From source (library, CLI, and tests):
-
-git clone https://github.com/DevStrikerTech/oris.git
-cd oris
-python -m venv .venv
-source .venv/bin/activate   # Windows: .venv\Scripts\activate
-pip install -e .
-Developers (lint, types, tests, notebook execution):
-
-pip install -e ".[dev]"
-Oris requires Python 3.10+. Runtime dependencies are minimal (PyYAML only). For a fuller walkthrough, see the Installation page in the docs.
-
-Documentation
-Start with the Introduction, then follow Installation and Quickstart. The Concepts section explains pipelines, components, providers, RAI, and traces; Guides cover CLI usage, SafeRunner, and run summaries.
-
-Site: devstrikertech.github.io/oris (MkDocs Material, similar to Haystack).
-
-Preview locally:
-
-pip install -e ".[docs]"
-mkdocs serve
-The Docs workflow publishes to GitHub Pages on pushes to prod (.github/workflows/docs.yml). In Settings → Pages, choose GitHub Actions as the source if needed.
-
-Features
-YAML-first pipelines: define steps, optional providers, and settings (tracing, etc.). Configuration is validated before execution.
-
-Guards and policy: default PolicyEnforcer applies input/output checks, including blocked keys, injection heuristics, and PII-shaped patterns. SafeRunner uses the same policy.
-
-Built-in components and provider stubs: includes passthrough, template_response, generate / llm_echo. openai / huggingface provider types are stubs (no network I/O).
-
-Observability: RunTrace provides per-step latency, status, and flags. PipelineResult.to_run_summary() produces JSON-friendly logs and CLI output.
-
-CLI parity: oris validate and oris run match Python definitions; use --format pretty and --debug for human-readable output.
-
-Quick Start
-Save as pipeline.yaml:
-name: quickstart
-settings:
-  tracing: true
-steps:
-  - id: reply
-    type: template_response
-    config:
-      template: "Answer placeholder for: {query}"
-Python
-from oris import Pipeline
-
-pipeline = Pipeline.from_yaml("pipeline.yaml")
-result = pipeline.run({"query": "What is responsible AI?"})
-print(result.output)
-CLI
-oris validate pipeline.yaml
-oris run pipeline.yaml --input-json '{"query":"What is responsible AI?"}'
-oris run pipeline.yaml --input-json '{"query":"hi"}' --format pretty --debug
-CLI
-| Command                                             | Purpose                                            |
-| :-------------------------------------------------- | :------------------------------------------------- |
-| `oris validate <file.yaml>`                         | Validate pipeline (schema, components, providers). |
-| `oris run <file.yaml> --input-json '<json object>'` | Run with JSON input; stdout gives JSON summary.    |
-| `oris run ... --format pretty`                      | Pretty-printed JSON summary.                       |
-| `oris run ... --debug`                              | Shows step latency, flags, and run_id in stderr.   |
-
-Hello
-
-Hello! 😄 How’s your day going?
-
-
-<p align="center">
-  <a href="https://devstrikertech.github.io/oris/">
-    <img src="docs/images/oris_logo.png" width="180" alt="Oris — Responsible AI pipeline runtime for Python" />
-  </a>
-</p>
-
-|         |     |
-| ------- | --- |
 | **CI** | [![CI](https://github.com/DevStrikerTech/oris/actions/workflows/ci.yml/badge.svg?branch=dev)](https://github.com/DevStrikerTech/oris/actions/workflows/ci.yml) [![types - Mypy](https://img.shields.io/badge/types-Mypy-blue.svg)](https://github.com/python/mypy) [![Coverage](https://img.shields.io/badge/coverage-%E2%89%A584%25-brightgreen.svg)](CONTRIBUTING.md#quality-gates) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) |
 | **Docs** | [![Website](https://img.shields.io/website?label=documentation&up_message=online&url=https%3A%2F%2Fdevstrikertech.github.io%2Foris%2F)](https://devstrikertech.github.io/oris/) [![Docs](https://github.com/DevStrikerTech/oris/actions/workflows/docs.yml/badge.svg?branch=prod)](https://github.com/DevStrikerTech/oris/actions/workflows/docs.yml) |
 | **Package** | [![PyPI](https://img.shields.io/pypi/v/oris-ai)](https://pypi.org/project/oris-ai/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/oris-ai?logo=python&logoColor=gold)](https://pypi.org/project/oris-ai/) [![License](https://img.shields.io/github/license/DevStrikerTech/oris)](https://github.com/DevStrikerTech/oris/blob/prod/LICENSE) |

From 36d3fc5fd9a6ef3e083d62e38e49c98cf21bb9d1 Mon Sep 17 00:00:00 2001
From: Mohamed Jadla <jadlamed444@gmail.com>
Date: Thu, 9 Apr 2026 19:33:29 +0100
Subject: [PATCH 05/12] docs: small README improvements

Remove unnecessary link from Oris description.
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index d1e49fc..4f995ea 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,7 @@
 | **Package** | [![PyPI](https://img.shields.io/pypi/v/oris-ai)](https://pypi.org/project/oris-ai/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/oris-ai?logo=python&logoColor=gold)](https://pypi.org/project/oris-ai/) [![License](https://img.shields.io/github/license/DevStrikerTech/oris)](https://github.com/DevStrikerTech/oris/blob/prod/LICENSE) |
 | **Meta** | [![Issues](https://img.shields.io/github/issues/DevStrikerTech/oris)](https://github.com/DevStrikerTech/oris/issues) [![GitHub](https://img.shields.io/badge/GitHub-DevStrikerTech%2Foris-181717?logo=github)](https://github.com/DevStrikerTech/oris) |
 
-[Oris](https://devstrikertech.github.io /oris/) is an open-source **Responsible AI** runtime for Python. Describe **pipelines** in YAML (or build them in code), run them through one **executor**, and get **input/output policy checks** and **run- and step-level traces** by default.
+Oris is an open-source **Responsible AI** runtime for Python. Describe **pipelines** in YAML (or build them in code), run them through one **executor**, and get **input/output policy checks** and **run- and step-level traces** by default.
 
 Oris stays **framework-agnostic**: anything you can invoke like run(dict) can use the same boundaries—including external LLM stacks wrapped with **SafeRunner**—so you can experiment locally and ship with clearer safety and observability defaults.
 

From e7c84dc86eb2c9540a0e0dd9bd02c12a7bf5ed82 Mon Sep 17 00:00:00 2001
From: Mohamed Jadla <jadlamed444@gmail.com>
Date: Thu, 9 Apr 2026 19:35:15 +0100
Subject: [PATCH 06/12] docs: small README improvements

Added badges for CI, documentation, package, and meta information.
---
 README.md | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/README.md b/README.md
index 4f995ea..b51f06a 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,18 @@
+<p align="center">
+  <a href="https://devstrikertech.github.io/oris/">
+    <img src="docs/images/oris_logo.png" width="180" alt="Oris — Responsible AI pipeline runtime for Python" />
+  </a>
+</p>
+
+|         |     |
+| ------- | --- |
 | **CI** | [![CI](https://github.com/DevStrikerTech/oris/actions/workflows/ci.yml/badge.svg?branch=dev)](https://github.com/DevStrikerTech/oris/actions/workflows/ci.yml) [![types - Mypy](https://img.shields.io/badge/types-Mypy-blue.svg)](https://github.com/python/mypy) [![Coverage](https://img.shields.io/badge/coverage-%E2%89%A584%25-brightgreen.svg)](CONTRIBUTING.md#quality-gates) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) |
 | **Docs** | [![Website](https://img.shields.io/website?label=documentation&up_message=online&url=https%3A%2F%2Fdevstrikertech.github.io%2Foris%2F)](https://devstrikertech.github.io/oris/) [![Docs](https://github.com/DevStrikerTech/oris/actions/workflows/docs.yml/badge.svg?branch=prod)](https://github.com/DevStrikerTech/oris/actions/workflows/docs.yml) |
 | **Package** | [![PyPI](https://img.shields.io/pypi/v/oris-ai)](https://pypi.org/project/oris-ai/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/oris-ai?logo=python&logoColor=gold)](https://pypi.org/project/oris-ai/) [![License](https://img.shields.io/github/license/DevStrikerTech/oris)](https://github.com/DevStrikerTech/oris/blob/prod/LICENSE) |
 | **Meta** | [![Issues](https://img.shields.io/github/issues/DevStrikerTech/oris)](https://github.com/DevStrikerTech/oris/issues) [![GitHub](https://img.shields.io/badge/GitHub-DevStrikerTech%2Foris-181717?logo=github)](https://github.com/DevStrikerTech/oris) |
 
+[Oris](https://devstrikertech.github.io/oris/)
+
 Oris is an open-source **Responsible AI** runtime for Python. Describe **pipelines** in YAML (or build them in code), run them through one **executor**, and get **input/output policy checks** and **run- and step-level traces** by default.
 
 Oris stays **framework-agnostic**: anything you can invoke like run(dict) can use the same boundaries—including external LLM stacks wrapped with **SafeRunner**—so you can experiment locally and ship with clearer safety and observability defaults.

From 0f9c8751c8d2910dea0e692f4305d88f505cae3a Mon Sep 17 00:00:00 2001
From: Mohamed Jadla <jadlamed444@gmail.com>
Date: Thu, 9 Apr 2026 19:39:11 +0100
Subject: [PATCH 07/12] docs: small README improvements

---
 README.md | 2 --
 1 file changed, 2 deletions(-)

diff --git a/README.md b/README.md
index b51f06a..b2d5d3f 100644
--- a/README.md
+++ b/README.md
@@ -34,8 +34,6 @@ Oris stays **framework-agnostic**: anything you can invoke like run(dict) can us
 ## Installation
 
 The simplest way to get Oris is via pip:
-
-bash
 pip install oris-ai
 
 

From 57dbfd5b5b385dac8fa162c03a0ba5dd307d4afc Mon Sep 17 00:00:00 2001
From: Mohamed Jadla <jadlamed444@gmail.com>
Date: Thu, 9 Apr 2026 19:41:28 +0100
Subject: [PATCH 08/12] docs: small README improvements

---
 README.md | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index b2d5d3f..3b56e2a 100644
--- a/README.md
+++ b/README.md
@@ -34,23 +34,26 @@ Oris stays **framework-agnostic**: anything you can invoke like run(dict) can us
 ## Installation
 
 The simplest way to get Oris is via pip:
-pip install oris-ai
 
+```bash
+pip install oris-ai
+```
 
 Verify the CLI:
 
-bash
+```bash
 oris --help
-
+```
 
 **From source** (library, CLI, and tests):
 
-bash
+```bash
 git clone https://github.com/DevStrikerTech/oris.git
 cd oris
 python -m venv .venv
 source .venv/bin/activate   # Windows: .venv\Scripts\activate
 pip install -e .
+```
 
 
 **Developers** (lint, types, tests, notebook execution):

From 95e869ca6911d4f1d52f96394944d043e4767531 Mon Sep 17 00:00:00 2001
From: Mohamed Jadla <jadlamed444@gmail.com>
Date: Thu, 9 Apr 2026 19:45:51 +0100
Subject: [PATCH 09/12] docs: small README improvements

---
 README.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/README.md b/README.md
index 3b56e2a..aaf4d40 100644
--- a/README.md
+++ b/README.md
@@ -111,6 +111,7 @@ steps:
       template: "Answer placeholder for: {query}"
 
 
+
 **Python**
 
 python

From 5982b555b96b3c37767b8aaf7fea577d20bf1a5d Mon Sep 17 00:00:00 2001
From: Mohamed Jadla <jadlamed444@gmail.com>
Date: Thu, 9 Apr 2026 19:47:54 +0100
Subject: [PATCH 10/12] docs: small README improvements

---
 README.md | 57 -------------------------------------------------------
 1 file changed, 57 deletions(-)

diff --git a/README.md b/README.md
index aaf4d40..0a0e021 100644
--- a/README.md
+++ b/README.md
@@ -289,63 +289,6 @@ Oris is an open-source Responsible AI runtime for Python. Define pipelines in YA
 
 Oris is framework-agnostic: anything you can invoke like run(dict) can use the same boundaries—including external LLM stacks wrapped with SafeRunner—so you can experiment locally and ship with clearer safety and observability defaults.
 
-Table of Contents
-Installation
-
-Documentation
-
-Features
-
-Quick Start
-
-CLI
-
-Output Format
-
-SafeRunner
-
-Project Layout
-
-Examples and Notebooks
-
-Contributing
-
-License
-
-Installation
-The simplest way to get Oris is via pip:
-
-pip install oris-ai
-Verify the CLI:
-
-oris --help
-From source (library, CLI, and tests):
-
-git clone https://github.com/DevStrikerTech/oris.git
-cd oris
-python -m venv .venv
-source .venv/bin/activate   # Windows: .venv\Scripts\activate
-pip install -e .
-Developers (lint, types, tests, notebook execution):
-
-pip install -e ".[dev]"
-Oris requires Python 3.10+. Runtime dependencies are minimal (PyYAML only). For a fuller walkthrough, see the Installation page in the docs.
-
-Documentation
-Start with the Introduction, then follow Installation and Quickstart. The Concepts section explains pipelines, components, providers, RAI, and traces; Guides cover CLI usage, SafeRunner, and run summaries.
-
-Site: devstrikertech.github.io/oris (MkDocs Material, similar to Haystack).
-
-Preview locally:
-
-pip install -e ".[docs]"
-mkdocs serve
-The Docs workflow publishes to GitHub Pages on pushes to prod (.github/workflows/docs.yml). In Settings → Pages, choose GitHub Actions as the source if needed.
-
-Features
-YAML-first pipelines: define steps, optional providers, and settings (tracing, etc.). Configuration is validated before execution.
-
-Guards and policy: default PolicyEnforcer applies input/output checks, including blocked keys, injection heuristics, and PII-shaped patterns. SafeRunner uses the same policy.
 
 Built-in components and provider stubs: includes passthrough, template_response, generate / llm_echo. openai / huggingface provider types are stubs (no network I/O).
 

From 3175125667f4660883bf44e0fe0b6b19cdc9f96e Mon Sep 17 00:00:00 2001
From: Mohamed Jadla <jadlamed444@gmail.com>
Date: Thu, 9 Apr 2026 19:51:56 +0100
Subject: [PATCH 11/12] docs: small README improvements

---
 README.md | 170 ------------------------------------------------------
 1 file changed, 170 deletions(-)

diff --git a/README.md b/README.md
index 0a0e021..1e41425 100644
--- a/README.md
+++ b/README.md
@@ -216,173 +216,3 @@ We welcome issues and pull requests. Start with [CONTRIBUTING.md](CONTRIBUTING.m
 ## License
 
 MIT — see [LICENSE](LICENSE).
-
-Ah! I see you’ve pasted your full Oris README content. If your goal is to have a single section you can copy-paste directly, I can simplify it into one self-contained block for easy use. Here’s a clean, ready-to-copy version of the Installation + Quick Start + CLI section (most commonly used):
-
-## Installation
-
-Install Oris via pip:
-
-```bash
-pip install oris-ai
-Verify the CLI:
-
-oris --help
-From source:
-
-git clone https://github.com/DevStrikerTech/oris.git
-cd oris
-python -m venv .venv
-source .venv/bin/activate   # Windows: .venv\Scripts\activate
-pip install -e .
-Developers:
-
-pip install -e ".[dev]"
-Requires Python 3.10+. Minimal dependencies (PyYAML).
-
-Quick Start
-Save as pipeline.yaml:
-
-name: quickstart
-settings:
-  tracing: true
-steps:
-  - id: reply
-    type: template_response
-    config:
-      template: "Answer placeholder for: {query}"
-Python usage:
-
-from oris import Pipeline
-
-pipeline = Pipeline.from_yaml("pipeline.yaml")
-result = pipeline.run({"query": "What is responsible AI?"})
-print(result.output)
-CLI usage:
-
-oris validate pipeline.yaml
-oris run pipeline.yaml --input-json '{"query":"What is responsible AI?"}'
-oris run pipeline.yaml --input-json '{"query":"hi"}' --format pretty --debug
-CLI Commands
-Command	Purpose
-oris validate <file.yaml>	Validate the pipeline (schema, components, providers).
-oris run <file.yaml> --input-json '<json object>'	Run pipeline with JSON input; stdout gives JSON summary.
-oris run ... --format pretty	Pretty-printed JSON summary.
-oris run ... --debug	Shows step latency, flags, and run_id in stderr.
-
-This is **one section you can copy** and it includes everything needed to get started immediately without pasting multiple sections.  
-
-If you want, I can make an **even shorter “1-click copy” version** that’s **under 50 lines** including installation + quickstart + CLI + example, perfect for sharing in GitHub README.  
-
-Do you want me to do that?
-
-No i need this Make only SMALL README changes (wording, formatting, minor section cleanup, typo fixes, link fixes). No huge rewrite.
-
-Ah! Got it — you just want a small, careful polish of your existing README: fix typos, clean minor formatting, ensure links work, adjust wording slightly, but keep everything the same. I can do that. Here’s a cleaned-up version of your README with only small changes applied:
-
-<p align="center">   <a href="https://devstrikertech.github.io/oris/">     <img src="docs/images/oris_logo.png" width="180" alt="Oris — Responsible AI pipeline runtime for Python" />   </a> </p>
-CI	CItypes - MypyCoverageRuff
-Docs	WebsiteDocs
-Package	PyPIPyPI - Python VersionLicense
-Meta	IssuesGitHub
-Oris is an open-source Responsible AI runtime for Python. Define pipelines in YAML (or build them in code), run them through one executor, and get input/output policy checks and run- and step-level traces by default.
-
-Oris is framework-agnostic: anything you can invoke like run(dict) can use the same boundaries—including external LLM stacks wrapped with SafeRunner—so you can experiment locally and ship with clearer safety and observability defaults.
-
-
-Built-in components and provider stubs: includes passthrough, template_response, generate / llm_echo. openai / huggingface provider types are stubs (no network I/O).
-
-Observability: RunTrace provides per-step latency, status, and flags. PipelineResult.to_run_summary() produces JSON-friendly logs and CLI output.
-
-CLI parity: oris validate and oris run match Python definitions; use --format pretty and --debug for human-readable output.
-
-Quick Start
-Save as pipeline.yaml:
-
-name: quickstart
-settings:
-  tracing: true
-steps:
-  - id: reply
-    type: template_response
-    config:
-      template: "Answer placeholder for: {query}"
-Python
-
-from oris import Pipeline
-
-pipeline = Pipeline.from_yaml("pipeline.yaml")
-result = pipeline.run({"query": "What is responsible AI?"})
-print(result.output)
-CLI
-
-oris validate pipeline.yaml
-oris run pipeline.yaml --input-json '{"query":"What is responsible AI?"}'
-oris run pipeline.yaml --input-json '{"query":"hi"}' --format pretty --debug
-CLI
-Command	Purpose
-oris validate <file.yaml>	Validate pipeline (schema, components, providers).
-oris run <file.yaml> --input-json '<json object>'	Run with JSON input; stdout gives JSON summary.
-oris run ... --format pretty	Pretty-printed JSON summary.
-oris run ... --debug	Shows step latency, flags, and run_id in stderr.
-Output Format
-Pipeline.run returns a PipelineResult: output (dict), trace (RunTrace), metadata. See models.py.
-
-result.to_run_summary() includes:
-
-run_id — Run identifier.
-
-status — "success" or "failed".
-
-output — Final payload (CLI may redact sensitive keys).
-
-trace — Step entries: step_id, component_name, status, latency_ms, flags.
-SafeRunner
-
-SafeRunner
- wraps external callables with the same PolicyEnforcer.
-from oris.integrations import SafeRunner
-from oris.rai.policy import PolicyEnforcer
-
-def my_external_llm(payload: dict) -> dict:
-    q = payload.get("query", "")
-    return {"output": f"stub response for: {q!r}"}
-
-runner = SafeRunner(my_external_llm, policy=PolicyEnforcer())
-plain = runner.run({"query": "Hello"})
-traced = runner.run({"query": "Hello"}, include_trace=True)
-Returns are normalized to dict.
-
-Project Layout
-| Area                | Role                                                            |
-| :------------------ | :-------------------------------------------------------------- |
-| `oris.core`         | Enums and exceptions.                                           |
-| `oris.components`   | Component registry and built-ins.                               |
-| `oris.pipeline`     | YAML loading, schema, plan, builder.                            |
-| `oris.runtime`      | Executor, orchestrator, hooks, trace manager, `PipelineResult`. |
-| `oris.rai`          | `PolicyEnforcer`, input/output guards.                          |
-| `oris.providers`    | `LLMProvider` and provider stubs.                               |
-| `oris.integrations` | `SafeRunner`.                                                   |
-| `oris.tracing`      | Run and step trace models.                                      |
-| `oris.cli`          | CLI entrypoint.                                                 |
-| Asset                                                                | Description                                                 |
-| :------------------------------------------------------------------- | :---------------------------------------------------------- |
-| [`examples/simple_generation.yaml`](examples/simple_generation.yaml) | Template step; first `Pipeline.run`.                        |
-| [`examples/provider_pipeline.yaml`](examples/provider_pipeline.yaml) | Provider declaration + `generate` (needs `OPENAI_API_KEY`). |
-| [`examples/basic_pipeline.ipynb`](examples/basic_pipeline.ipynb)     | YAML → run → `to_run_summary()`.                            |
-| [`examples/safe_runner.ipynb`](examples/safe_runner.ipynb)           | SafeRunner, traces, policy violations.                      |
-| [`examples/llm_integration.ipynb`](examples/llm_integration.ipynb)   | Optional Ollama + mock fallback.                            |
-Execute notebooks from repo root:
-export JUPYTER_CONFIG_DIR="$PWD/.jupyter" && mkdir -p .jupyter
-python -m nbconvert --to notebook --execute examples/basic_pipeline.ipynb --inplace
-Repeat for other notebooks.
-
-Contributing
-
-See CONTRIBUTING.md
-, SECURITY.md
-, CODE_OF_CONDUCT.md
-. We welcome issues and PRs.
-License
-
-MIT — see LICENSE.

From f14c717196e1fafa07325359665f31e3b2822330 Mon Sep 17 00:00:00 2001
From: Mohamed Jadla <jadlamed444@gmail.com>
Date: Thu, 9 Apr 2026 22:05:45 +0100
Subject: [PATCH 12/12] docs: small README improvements

---
 README.md | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 1e41425..06f12d1 100644
--- a/README.md
+++ b/README.md
@@ -13,11 +13,11 @@
 
 [Oris](https://devstrikertech.github.io/oris/)
 
-Oris is an open-source **Responsible AI** runtime for Python. Describe **pipelines** in YAML (or build them in code), run them through one **executor**, and get **input/output policy checks** and **run- and step-level traces** by default.
+[Oris](...) is an open-source **Responsible AI** runtime for Python.. Describe **pipelines** in YAML (or build them in code), run them through an **executor**, and get **input/output policy checks** and **run- and step-level traces** by default.
 
-Oris stays **framework-agnostic**: anything you can invoke like run(dict) can use the same boundaries—including external LLM stacks wrapped with **SafeRunner**—so you can experiment locally and ship with clearer safety and observability defaults.
+Oris stays **framework-agnostic**: anything you can invoke like `run(dict)` can use the same boundaries—including external LLM stacks wrapped with **SafeRunner**—allowing you to experiment locally and ship with clearer safety and observability defaults.
 
-## Table of contents
+## Table of Contents
 
 - [Installation](#installation)
 - [Documentation](#documentation)
@@ -33,13 +33,13 @@ Oris stays **framework-agnostic**: anything you can invoke like run(dict) can us
 
 ## Installation
 
-The simplest way to get Oris is via pip:
+The simplest way to install Oris is via pip:
 
 ```bash
 pip install oris-ai
 ```
 
-Verify the CLI:
+Verify the CLI installation:
 
 ```bash
 oris --help
@@ -51,7 +51,7 @@ oris --help
 git clone https://github.com/DevStrikerTech/oris.git
 cd oris
 python -m venv .venv
-source .venv/bin/activate   # Windows: .venv\Scripts\activate
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
 pip install -e .
 ```
 
@@ -96,7 +96,7 @@ Each run produces a RunTrace with per-step latency, status, and flags. PipelineR
 **CLI parity**  
 oris validate and oris run use the same definitions as Pipeline.from_yaml in Python, with --format pretty and --debug for human-friendly output and stderr trace lines.
 
-## Quick start
+## Quick Start
 
 Save as pipeline.yaml:
 
@@ -143,7 +143,7 @@ oris run pipeline.yaml --input-json '{"query":"hi"}' --format pretty --debug
 | oris run ... --debug | Stderr: run_id, trace status, per-step latency and flags. |
 | oris validate ... --debug | Stderr: pipeline name and step list. |
 
-## Output format
+## Output Format
 
 Pipeline.run returns a **PipelineResult**: output (dict), trace (RunTrace), and metadata. See [models.py](https://github.com/DevStrikerTech/oris/blob/dev/src/oris/runtime/models.py).
 
@@ -176,7 +176,7 @@ traced = runner.run({"query": "Hello"}, include_trace=True)
 
 Returns are normalized to dict from mappings or Pydantic-style model_dump(). More detail: [SafeRunner guide](https://devstrikertech.github.io/oris/guides/safe-runner/).
 
-## Project layout
+## Project Layout
 
 | Area | Role |
 | :--- | :--- |
@@ -190,7 +190,7 @@ Returns are normalized to dict from mappings or Pydantic-style model_dump(). Mor
 | oris.tracing | Run and step trace models. |
 | oris.cli | oris CLI entrypoint. |
 
-## Examples and notebooks
+## Examples and Notebooks
 
 | Asset | Description |
 | :--- | :--- |