Skip to content

Commit ba7dce7

Browse files
sebuzdugansebuzdugan
committed
update: all README files
1 parent e9fb76f commit ba7dce7

File tree

3 files changed

+372
-209
lines changed

3 files changed

+372
-209
lines changed

‎README.md‎

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,26 @@
1+
<div align="center">
2+
3+
<pre>
4+
5+
███████████ ███████████ █████████ █████
6+
░░███░░░░░░█░░███░░░░░███ ███░░░░░███ ░░███
7+
░███ █ ░ ░███ ░███ ░███ ░███ ░███
8+
░███████ ░██████████ ░███████████ ░███
9+
░███░░░█ ░███░░░░░███ ░███░░░░░███ ░███
10+
░███ ░ ░███ ░███ ░███ ░███ ░███
11+
█████ █████ █████ █████ █████ █████
12+
░░░░░ ░░░░░ ░░░░░ ░░░░░ ░░░░░ ░░░░░
13+
14+
</pre>
15+
16+
</div>
17+
118
# FRAI · Framework of Responsible Artificial Intelligence
219

320
![npm version](https://img.shields.io/npm/v/frai)
4-
![npm version core](https://img.shields.io/npm/v/frai-core)
521
![npm downloads](https://img.shields.io/npm/dt/frai)
622

23+
724
FRAI is an open-source toolkit that helps teams launch AI features responsibly. It guides you through evidence gathering, scans your code, and assembles documentation you can hand to reviewers: implementation checklists, model cards, risk files, evaluation reports, and compliance-aware RAG indexes. The toolkit ships as two packages that work together:
825

926
- `frai` – the command-line app with ready-to-run workflows.
@@ -209,6 +226,8 @@ FRAI ships as two npm packages and they must be published independently.
209226
---
210227

211228
## Learn More
229+
- Website: [frai.cc](https://frai.cc)
230+
- NPM package: [frai](https://www.npmjs.com/package/frai)
212231
- docs/ai_feature_backlog.md – roadmap for AI capabilities.
213232
- docs/eval_harness_design.md – evaluation harness design notes.
214233
- docs/architecture-target.md – monorepo architecture.

‎packages/frai-cli/README.md‎

Lines changed: 176 additions & 104 deletions
Original file line numberDiff line numberDiff line change
@@ -15,149 +15,221 @@
1515

1616
</div>
1717

18-
1918
# FRAI · Framework of Responsible Artificial Intelligence
2019

2120
![npm version](https://img.shields.io/npm/v/frai)
21+
![npm downloads](https://img.shields.io/npm/dt/frai)
2222

23-
FRAI (Framework of Responsible Artificial Intelligence) is an open-source toolkit that helps any team — from solo developers to compliance officers — ship AI features responsibly. It walks you through quick questions, scans your code, and generates documentation you can actually hand to stakeholders: implementation checklists, model cards, risk files, evaluation reports, and policy-aware RAG indexes.
2423

25-
Think of FRAI as a safety net for AI launches: it collects the right facts, highlights blind spots, and keeps evidence tidy so production reviews stop feeling like guesswork.
24+
FRAI is an open-source toolkit that helps teams launch AI features responsibly. It guides you through evidence gathering, scans your code, and assembles documentation you can hand to reviewers: implementation checklists, model cards, risk files, evaluation reports, and compliance-aware RAG indexes. The toolkit ships as two packages that work together:
2625

27-
## 🚀 Getting Started
26+
- `frai` – the command-line app with ready-to-run workflows.
27+
- `frai-core` – the reusable SDK that powers the CLI and any custom integrations.
2828

29-
**1. Install FRAI globally:**
30-
```bash
31-
npm install -g frai
32-
```
29+
### Short Answer
30+
- `frai-core` is the library/SDK. Use it when you are embedding FRAI capabilities into your own tools, servers, automations, or extensions.
31+
- `frai` is the CLI. It wraps `frai-core` to deliver an end-user experience with no coding required.
3332

34-
**2. Set up your OpenAI API key (required for AI-powered tips):**
35-
```bash
36-
frai --setup
37-
```
38-
You only need to do this once per machine or project. Your key is stored securely and never shared.
33+
### Why Keep Both?
34+
- Independent versioning and stability
35+
- `frai-core` can evolve APIs for integrators without forcing a CLI release.
36+
- `frai` can improve UX/commands without breaking programmatic users.
37+
- Reuse across surfaces
38+
- `frai-core` powers the CLI today and future VS Code/Chrome extensions, GitHub Actions, internal CLIs, services, or SDKs.
39+
- Smaller, focused installs
40+
- Operators install the CLI.
41+
- Builders install only the core library they need.
3942

40-
**3. Run FRAI in your project:**
41-
```bash
42-
frai
43-
```
43+
### When to Use Each
44+
- Choose **`frai` (CLI)** when you want interactive prompts, one-command scans, RAG indexing, evaluation reports, or CI-friendly automation without writing code.
45+
- Choose **`frai-core` (SDK)** when you want API access to FRAI capabilities from Node scripts, services, custom CLIs, extensions, or unusual I/O flows.
4446

45-
> **Tip:** `frai` is available globally after installing the published npm package. If you're working from a local clone, follow the steps in [Local Development](#-local-development) to run the CLI from source.
47+
### Concrete Examples
48+
- CLI user: run `frai --scan` and `frai eval` in a repository to generate governance docs and audit reports.
49+
- Library user: call `Documents.generateDocuments` from an internal portal to produce standardized docs, use `Scanners.scanCodebase` inside a GitHub Action, or embed `Rag.indexDocuments` inside a VS Code extension for grounded hints.
4650

47-
---
48-
49-
## 🛠️ CLI Commands & Features
50-
51-
| Command | Description |
52-
|------------------------|-------------|
53-
| `frai` | Interactive mode for documenting an AI feature (8-question progressive system) |
54-
| `frai --scan` | Scan codebase for AI/ML code and generate docs |
55-
| `frai --setup` | Set up your OpenAI API key (local/global) |
56-
| `frai --ci` | Run in CI mode (non-interactive) |
57-
| `frai --help`, `-h` | Show help and usage info |
58-
| `frai --version`, `-v` | Show current version |
59-
| `frai --update` | Check for new versions of FRAI |
60-
| `frai --list-docs` | List generated documentation files |
61-
| `frai --clean` | Remove generated documentation files |
62-
| `frai --export-pdf` | Export documentation markdown files as PDFs |
63-
| `frai --show-config` | Show API key config status |
64-
| `frai --key=API_KEY` | Provide OpenAI API key directly (one-off use) |
65-
| `frai --global` | Use with --setup to save API key globally |
66-
| `frai rag index` | Index compliance docs into a local vector store |
67-
| `frai eval` | Run baseline evaluation metrics and write reports |
68-
69-
### RAG Indexing
51+
In short: CLI = product; Core = platform. They overlap in capability on purpose but target different audiences and distribution needs.
7052

71-
```bash
72-
frai rag index --input docs/policies --output .frai/compliance-index.json --chunk-size 400
73-
```
74-
- Scans `.md`, `.txt`, `.json`, `.yaml` files recursively.
75-
- Generates a lightweight JSON vector store consumable by SDKs and future connectors.
53+
---
7654

77-
### Evaluation Harness
55+
## Getting Started with the CLI
56+
57+
1. Install the published CLI:
58+
```bash
59+
npm install -g frai
60+
```
61+
2. Configure your OpenAI API key (needed for AI-generated tips and evaluations):
62+
```bash
63+
frai --setup
64+
```
65+
Keys can be stored per-project (`.env`) or globally (`~/.config/frai/config`). You can also provide a one-off key using `frai --key sk-...`.
66+
3. Run the interactive workflow:
67+
```bash
68+
frai
69+
```
70+
FRAI walks you through feature discovery, writes `checklist.md`, `model_card.md`, and `risk_file.md`, and optionally exports PDFs.
71+
72+
Generated artefacts live in your current working directory. Supplementary commands cover scanning, evaluation, RAG indexing, and fine-tuning governance.
7873

79-
```bash
80-
frai eval --outputs runs/outputs.json --references runs/golden.json --report reports/eval --format markdown
81-
```
82-
- Runs baseline metrics (exact match, toxicity keyword scan, length variance).
83-
- Produces JSON and/or Markdown summaries for CI and governance reviews.
74+
---
8475

85-
**Docs generated:**
86-
- `checklist.md` — Implementation checklist
87-
- `model_card.md` — Model card
88-
- `risk_file.md` — Risk & compliance
76+
## CLI Command Reference
77+
78+
| Command | Purpose |
79+
|---------|---------|
80+
| `frai [options]` | Interactive documentation workflow with backward-compatible shortcut flags. |
81+
| `frai generate [options]` | Explicit interactive workflow command. |
82+
| `frai scan [--ci] [--json]` | Scan the repository for AI/ML indicators. |
83+
| `frai setup [--key <apiKey>] [--global]` | Store an OpenAI API key locally or globally. |
84+
| `frai config` | Show key configuration status. |
85+
| `frai docs list` / `frai docs clean` / `frai docs export` | Manage generated documentation. |
86+
| `frai rag index [options]` | Build a local compliance-aware vector index. |
87+
| `frai eval --outputs <file> [...]` | Run baseline evaluation metrics and write reports. |
88+
| `frai finetune template` / `frai finetune validate <plan>` | Create or validate fine-tuning governance plans. |
89+
| `frai update` | Check npm for the latest CLI release. |
90+
91+
### Default Command: `frai [options]`
92+
Runs the interactive documentation flow. Optional flags add shortcuts:
93+
- `--scan` – run code scanning before questions.
94+
- `--ci` – exit after scanning when no AI indicators are detected.
95+
- `--setup` – jump directly into key configuration.
96+
- `--key <apiKey>` / `--global` – provide a key and optionally persist it globally.
97+
- `--list-docs` / `--clean` – list or remove generated docs.
98+
- `--export-pdf` – convert generated markdown to PDFs (requires `markdown-pdf`).
99+
- `--show-config` – display key storage status.
100+
- `--update` – check npm for a newer CLI version.
101+
102+
### `frai generate [options]`
103+
Same workflow as the default command, but scoped to documentation only. Options mirror the defaults: `--scan`, `--ci`, `--key`, `--global`, `--export-pdf`, and `--show-config`.
104+
105+
### `frai scan`
106+
Scans the repository for AI-related libraries, functions, and files. Use `--ci` for non-interactive mode or `--json` to emit raw JSON.
107+
108+
### `frai setup`
109+
Guided API key storage. Supply `--key <apiKey>` for headless use and `--global` to persist at `~/.config/frai/config`.
110+
111+
### `frai config`
112+
Prints whether local (`.env`) or global configuration holds an API key.
113+
114+
### `frai docs`
115+
Utilities for generated artefacts:
116+
- `frai docs list` – list detected `checklist.md`, `model_card.md`, and `risk_file.md`.
117+
- `frai docs clean` – delete generated docs.
118+
- `frai docs export` – export docs to PDF via `markdown-pdf`.
119+
120+
### `frai rag index [options]`
121+
Create a lightweight JSON vector store for compliance policies.
122+
- `--input <path>` – file or directory to index (defaults to cwd).
123+
- `--output <path>` – target JSON file (defaults to `frai-index.json`).
124+
- `--chunk-size <words>` – words per chunk (default 800).
125+
- `--extensions <a,b,c>` – allowlisted extensions (default `.md,.markdown,.txt,.json,.yaml,.yml`).
126+
127+
### `frai eval`
128+
Generate evaluation reports for model outputs.
129+
- `--outputs <file>` *(required)* – JSON file with model outputs.
130+
- `--references <file>` – JSON file with reference answers.
131+
- `--report <path>` – output location (`frai-eval-report.json` by default).
132+
- `--format <json|markdown>` – output format (defaults to JSON). Markdown reports include human-readable summaries for review boards.
133+
134+
### `frai finetune`
135+
Fine-tuning governance helpers:
136+
- `frai finetune template [--output <path>]` – write a governance template JSON (`frai-finetune-plan.json` by default).
137+
- `frai finetune validate <plan> [--readiness]` – validate a plan and optionally print readiness checkpoints and summaries.
138+
139+
### `frai update`
140+
Check npm for the latest `frai` release and print upgrade instructions.
89141

90142
---
91143

92-
## 💡 Features
93-
- **Progressive 8-question system**: Context-aware, fast, and actionable
94-
- **AI-powered recommendations**: Get tailored tips for responsible AI
95-
- **Comprehensive documentation**: Checklist, model card, and risk file
96-
- **PDF export**: Convert docs to PDF with one command
97-
- **Codebase scanning**: Detects AI/ML code and generates relevant docs
98-
- **Easy setup**: One-time API key configuration
99-
- **Compliance-aware RAG**: Build vector stores from policies for knowledge-grounded guardrails
100-
- **Evaluation harness**: Run baseline metrics and capture auditable reports
101-
102-
### Monorepo Layout
144+
## Using `frai-core` (SDK)
103145

104-
```
105-
frai/
106-
├─ packages/
107-
│ ├─ frai-cli/ # CLI entry point and command wiring
108-
│ └─ frai-core/ # Reusable services (config, questionnaire, documents, scanners, RAG, eval)
109-
├─ docs/ # Roadmaps, design notes, and feature backlogs
110-
└─ examples/ # Sample AI projects used in tests and demos
146+
Install from npm:
147+
```bash
148+
pnpm add frai-core
111149
```
112150

113-
---
114-
115-
## 🔑 API Key Setup
116-
FRAI requires an OpenAI API key for generating AI-powered tips and documentation. Run:
117-
```bash
118-
frai --setup
151+
`frai-core` exposes modular helpers that the CLI uses under the hood:
152+
- `Questionnaire` – interactive question flows.
153+
- `Documents` – generate checklists, model cards, and risk files.
154+
- `Scanners` – static analysis for AI indicators.
155+
- `Rag` – policy-grounded indexing utilities.
156+
- `Eval` – baseline evaluation metrics and report writers.
157+
- `Finetune` – governance templates, validation, and readiness scoring.
158+
- `Config` & `Providers` – key management and LLM provider wiring.
159+
160+
Example: generate documentation programmatically.
161+
162+
```ts
163+
import fs from 'fs/promises';
164+
import inquirer from 'inquirer';
165+
import { Documents, Questionnaire, Scanners } from 'frai-core';
166+
167+
const answers = await Questionnaire.runQuestionnaire({
168+
prompt: (questions) => inquirer.prompt(questions)
169+
});
170+
171+
const { checklist, modelCard, riskFile } = Documents.generateDocuments({ answers });
172+
const scan = Scanners.scanCodebase({ root: process.cwd() });
173+
const aiContext = Documents.buildContextForAITips(answers);
174+
175+
await fs.writeFile('checklist.md', checklist);
176+
await fs.writeFile('model_card.md', modelCard);
177+
await fs.writeFile('risk_file.md', riskFile);
178+
await fs.writeFile('scan-summary.json', JSON.stringify(scan, null, 2));
179+
await fs.writeFile('ai-context.txt', aiContext);
119180
```
120-
If you skip this step, FRAI will prompt you to set up your key on first use.
121181

122-
---
182+
Because `frai-core` is a regular ESM package, you can import only the modules you need and embed FRAI capabilities inside automation pipelines, CI jobs, or custom products.
123183

124-
## 🧑‍💻 Local Development
184+
---
125185

126-
Run FRAI directly from this repository without publishing:
186+
## Local Development
127187

188+
Clone the repository and work from source:
128189
```bash
129190
pnpm install
130191
pnpm --filter frai run build
131192
node packages/frai-cli/dist/index.js --help
132193
```
133194

134-
### Configure an OpenAI key from source
135-
136-
- Interactive CLI:
137-
```bash
138-
node packages/frai-cli/dist/index.js --setup YOUR_KEY
139-
```
140-
- Manual `.env`:
141-
```
142-
OPENAI_API_KEY=YOUR_KEY
143-
```
144-
145-
To test the global binary locally (without npm publishing), install the workspace package:
146-
195+
During development you can install the CLI locally without publishing:
147196
```bash
148197
pnpm install --global ./packages/frai-cli
149-
# then:
198+
# then
150199
frai --setup
151200
```
152201

202+
Store your OpenAI key by running the CLI setup flow or setting `OPENAI_API_KEY` in `.env`.
203+
153204
---
154205

155-
## 📖 Learn More
156-
- [GitHub Repository](https://github.com/sebastianbuzdugan/frai)
157-
- [NPM Package](https://www.npmjs.com/package/frai)
158-
- [AI Feature Backlog](docs/ai_feature_backlog.md)
159-
- [Evaluation Harness Design](docs/eval_harness_design.md)
206+
## Publishing (Maintainers)
207+
208+
FRAI ships as two npm packages and they must be published independently.
209+
210+
1. Bump versions in `packages/frai-core/package.json` and `packages/frai-cli/package.json`. Update the CLI dependency to match the published `frai-core` version (drop `workspace:*`).
211+
2. Build the CLI:
212+
```bash
213+
pnpm --filter frai run build
214+
```
215+
3. Publish `frai-core` first, then `frai`:
216+
```bash
217+
cd packages/frai-core && npm publish
218+
cd ../frai-cli && npm publish
219+
```
220+
4. Verify on npm:
221+
```bash
222+
npm view frai versions --json
223+
npm view frai-core versions --json
224+
```
160225

161226
---
162227

163-
*Generated by FRAI - Responsible AI in Minutes*
228+
## Learn More
229+
- Website: [frai.cc](https://frai.cc)
230+
- NPM package: [frai](https://www.npmjs.com/package/frai)
231+
- docs/ai_feature_backlog.md – roadmap for AI capabilities.
232+
- docs/eval_harness_design.md – evaluation harness design notes.
233+
- docs/architecture-target.md – monorepo architecture.
234+
235+
*Framework of Responsible Artificial Intelligence*

0 commit comments

Comments
 (0)