AI Module Recommender

The AI module recommender translates a natural-language requirement into a ranked list of modules. It is an optional catalog-discovery feature; it is not the Workspace Intelligence model, graph, context engine, or autonomous repair loop.

Commands

Task	Command
Recommend modules	workspai ai recommend <query> [--number <n>] [--json]
Show current AI configuration	workspai ai info
Generate a missing catalog	workspai ai generate-embeddings [--force]
Refresh an existing catalog	workspai ai update-embeddings
Enable or disable AI	workspai config ai <enable|disable>
Store a local provider key	workspai config set-api-key
Remove the stored key	workspai config remove-api-key [--yes]

Use npx workspai instead of workspai when the CLI is not installed globally.

How ranking works

Natural-language requirement
            ↓
Query embedding (provider or deterministic mock)
            ↓
Bundled/runtime module embedding catalog
            ↓
Cosine similarity + dependency metadata
            ↓
Ranked suggestions

The catalog is loaded from the published package when available. Development and refresh workflows can obtain current module metadata through the validated Python Core bridge. A bounded fallback catalog keeps discovery available when Core is absent.

Interpreting a result

A recommendation contains module identity, description, category, declared dependencies, similarity score, and a short match reason.

Treat the score as a ranking signal only:

• it is not a probability that the module is correct;
• it does not prove framework/runtime compatibility;
• it does not approve licensing, security, or production readiness;
• it is not comparable across embedding models or catalog revisions without a controlled benchmark.

Before installation, inspect the project capability and the selected module's dependencies. Workspai refuses Core-backed installation when the current project does not advertise the required command surface.

Provider and mock behavior

• With OPENAI_API_KEY or a stored key, the current implementation uses the configured OpenAI embedding client.
• Without a key, deterministic mock mode exercises the workflow without a network request.
• Mock results are for development and UI testing, not production selection.
• Provider latency, limits, model availability, and prices can change. Consult the provider dashboard rather than relying on hard-coded cost estimates.

The current default embedding model and vector dimensions are implementation details recorded with generated catalog data. Consumers must read that metadata instead of assuming every catalog uses the same model.

Key storage and security

The preferred order is:

1. environment secret (OPENAI_API_KEY) for CI and ephemeral sessions;
2. interactive user configuration for a trusted local machine;
3. never a committed workspace file, shell history entry, screenshot, or issue.

workspai config show masks a stored key. config remove-api-key --yes supports non-interactive cleanup. See config-file-guide.md for configuration precedence and locations.

JSON automation

npx workspai ai recommend "PostgreSQL with migrations" --number 3 --json

JSON mode is intended for scripts. Treat non-zero exit codes and structured error codes as failures; do not scrape human-formatted output.

Relationship to Workspace Intelligence

Capability	Requires provider AI?	Durable evidence?	Main purpose
Module recommender	Optional	No	Discover modules from requirements
Workspace model/graph	No	Yes	Describe the current software system
Context and agent sync	No	Yes	Ground AI tools in shared evidence
Impact/verify/readiness	No	Yes	Govern changes and releases

For the main Workspai architecture, start with workspace-knowledge-graph.md and workspace-intelligence-runner.md.