Initial commit

ai/README.md

@@ -0,0 +1,110 @@
+# FuzzForge AI Module
+
+FuzzForge AI is the multi-agent layer that lets you operate the FuzzForge security platform through natural language. It orchestrates local tooling, registered Agent-to-Agent (A2A) peers, and the Prefect-powered backend while keeping long-running context in memory and project knowledge graphs.
+
+## Quick Start
+
+1. **Initialise a project**
+   ```bash
+   cd /path/to/project
+   fuzzforge init
+   ```
+2. **Review environment settings** – copy `.fuzzforge/.env.template` to `.fuzzforge/.env`, then edit the values to match your provider. The template ships with commented defaults for OpenAI-style usage and placeholders for Cognee keys.
+   ```env
+   LLM_PROVIDER=openai
+   LITELLM_MODEL=gpt-5-mini
+   OPENAI_API_KEY=sk-your-key
+   FUZZFORGE_MCP_URL=http://localhost:8010/mcp
+   SESSION_PERSISTENCE=sqlite
+   ```
+   Optional flags you may want to enable early:
+   ```env
+   MEMORY_SERVICE=inmemory
+   AGENTOPS_API_KEY=sk-your-agentops-key   # Enable hosted tracing
+   LOG_LEVEL=INFO                          # CLI / server log level
+   ```
+3. **Populate the knowledge graph**
+   ```bash
+   fuzzforge ingest --path . --recursive
+   # alias: fuzzforge rag ingest --path . --recursive
+   ```
+4. **Launch the agent shell**
+   ```bash
+   fuzzforge ai agent
+   ```
+   Keep the backend running (Prefect API at `FUZZFORGE_MCP_URL`) so workflow commands succeed.
+
+## Everyday Workflow
+
+- Run `fuzzforge ai agent` and start with `list available fuzzforge workflows` or `/memory status` to confirm everything is wired.
+- Use natural prompts for automation (`run fuzzforge workflow …`, `search project knowledge for …`) and fall back to slash commands for precision (`/recall`, `/sendfile`).
+- Keep `/memory datasets` handy to see which Cognee datasets are available after each ingest.
+- Start the HTTP surface with `python -m fuzzforge_ai` when external agents need access to artifacts or graph queries. The CLI stays usable at the same time.
+- Refresh the knowledge graph regularly: `fuzzforge ingest --path . --recursive --force` keeps responses aligned with recent code changes.
+
+## What the Agent Can Do
+
+- **Route requests** – automatically selects the right local tool or remote agent using the A2A capability registry.
+- **Run security workflows** – list, submit, and monitor FuzzForge workflows via MCP wrappers.
+- **Manage artifacts** – create downloadable files for reports, code edits, and shared attachments.
+- **Maintain context** – stores session history, semantic recall, and Cognee project graphs.
+- **Serve over HTTP** – expose the same agent as an A2A server using `python -m fuzzforge_ai`.
+
+## Essential Commands
+
+Inside `fuzzforge ai agent` you can mix slash commands and free-form prompts:
+
+```text
+/list                     # Show registered A2A agents
+/register http://:10201   # Add a remote agent
+/artifacts                 # List generated files
+/sendfile SecurityAgent src/report.md "Please review"
+You> route_to SecurityAnalyzer: scan ./backend for secrets
+You> run fuzzforge workflow static_analysis_scan on ./test_projects/demo
+You> search project knowledge for "prefect status" using INSIGHTS
+```
+
+Artifacts created during the conversation are served from `.fuzzforge/artifacts/` and exposed through the A2A HTTP API.
+
+## Memory & Knowledge
+
+The module layers three storage systems:
+
+- **Session persistence** (SQLite or in-memory) for chat transcripts.
+- **Semantic recall** via the ADK memory service for fuzzy search.
+- **Cognee graphs** for project-wide knowledge built from ingestion runs.
+
+Re-run ingestion after major code changes to keep graph answers relevant. If Cognee variables are not set, graph-specific tools automatically respond with a polite "not configured" message.
+
+## Sample Prompts
+
+Use these to validate the setup once the agent shell is running:
+
+- `list available fuzzforge workflows`
+- `run fuzzforge workflow static_analysis_scan on ./backend with target_branch=main`
+- `show findings for that run once it finishes`
+- `refresh the project knowledge graph for ./backend`
+- `search project knowledge for "prefect readiness" using INSIGHTS`
+- `/recall terraform secrets`
+- `/memory status`
+- `ROUTE_TO SecurityAnalyzer: audit infrastructure_vulnerable`
+
+## Need More Detail?
+
+Dive into the dedicated guides under `ai/docs/advanced/`:
+
+- [Architecture](https://docs.fuzzforge.ai/docs/ai/intro) – High-level architecture with diagrams and component breakdowns.
+- [Ingestion](https://docs.fuzzforge.ai/docs/ai/ingestion.md) – Command options, Cognee persistence, and prompt examples.
+- [Configuration](https://docs.fuzzforge.ai/docs/ai/configuration.md) – LLM provider matrix, local model setup, and tracing options.
+- [Prompts](https://docs.fuzzforge.ai/docs/ai/prompts.md) – Slash commands, workflow prompts, and routing tips.
+- [A2A Services](https://docs.fuzzforge.ai/docs/ai/a2a-services.md) – HTTP endpoints, agent card, and collaboration flow.
+- [Memory Persistence](https://docs.fuzzforge.ai/docs/ai/architecture.md#memory--persistence) – Deep dive on memory storage, datasets, and how `/memory status` inspects them.
+
+## Development Notes
+
+- Entry point for the CLI: `ai/src/fuzzforge_ai/cli.py`
+- A2A HTTP server: `ai/src/fuzzforge_ai/a2a_server.py`
+- Tool routing & workflow glue: `ai/src/fuzzforge_ai/agent_executor.py`
+- Ingestion helpers: `ai/src/fuzzforge_ai/ingest_utils.py`
+
+Install the module in editable mode (`pip install -e ai`) while iterating so CLI changes are picked up immediately.