Ragex.Agent.Core (Ragex v0.10.0)

View Source

Main entry point for Ragex Agent operations.

Orchestrates the full project analysis pipeline:

  1. Analyze project (build knowledge graph, embeddings)
  2. Discover issues (dead code, duplicates, security, smells, complexity)
  3. Generate AI-polished report
  4. Enable conversation session for follow-up

Usage

# Full project analysis with report
{:ok, result} = Agent.Core.analyze_project("/path/to/project")

# Continue conversation
{:ok, response} = Agent.Core.chat(result.session_id, "Tell me more about the security issues")

# Get just the report
{:ok, report} = Agent.Core.get_report(result.session_id)

Summary

Types

analysis_result()

Functions

analyze_project(path, opts \\ [])

Analyze a project and generate an AI-polished report.

chat(session_id, message, opts \\ [])

Continue a conversation with the agent in an existing session.

clear_session(session_id)

Clear/end a session.

get_report(session_id, opts \\ [])

Get the generated report from a session.

get_session(session_id)

Get session details.

list_sessions(opts \\ [])

List all active agent sessions.

quick_analyze(path, opts \\ [])

Quick analysis - runs all detectors without AI polishing.

stream_chat(session_id, message, opts \\ [])

Continue a conversation with streaming support.

stream_generate_report(path, issues, opts \\ [])

Generate an AI audit report with streaming support.

Types

analysis_result()

@type analysis_result() :: %{
  session_id: String.t(),
  report: String.t(),
  issues: map(),
  summary: map()
}

Functions

analyze_project(path, opts \\ [])

@spec analyze_project(
  String.t(),
  keyword()
) :: {:ok, analysis_result()} | {:error, term()}

Analyze a project and generate an AI-polished report.

Parameters

  • path - Project root path
  • opts - Options:
    • :provider - AI provider (:deepseek_r1, :openai, :anthropic)
    • :include_suggestions - Include refactoring suggestions (default: true)
    • :max_files - Maximum files to analyze (default: 500)
    • :skip_embeddings - Skip embedding generation (default: false)
    • :include_dead_code - Enable dead code analysis (default: false)
    • :exclude_patterns - Patterns to exclude (default: standard ignores)

Returns

  • {:ok, result} - Analysis completed with session ID and report
  • {:error, reason} - Analysis failed

chat(session_id, message, opts \\ [])

@spec chat(String.t(), String.t(), keyword()) :: {:ok, map()} | {:error, term()}

Continue a conversation with the agent in an existing session.

Parameters

  • session_id - Active session ID
  • message - User message
  • opts - Options (same as analyze_project)

Returns

  • {:ok, response} - Agent response
  • {:error, reason} - Chat failed

clear_session(session_id)

@spec clear_session(String.t()) :: :ok

Clear/end a session.

get_report(session_id, opts \\ [])

@spec get_report(
  String.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Get the generated report from a session.

If not yet generated, generates it on-demand.

get_session(session_id)

@spec get_session(String.t()) :: {:ok, map()} | {:error, :not_found}

Get session details.

list_sessions(opts \\ [])

@spec list_sessions(keyword()) :: [map()]

List all active agent sessions.

quick_analyze(path, opts \\ [])

@spec quick_analyze(
  String.t(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Quick analysis - runs all detectors without AI polishing.

Useful for programmatic access to raw issue data.

stream_chat(session_id, message, opts \\ [])

@spec stream_chat(String.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, term()}

Continue a conversation with streaming support.

Same as chat/3 but streams the final AI response in real-time via callbacks. Intermediate tool-call steps use blocking calls, but the final text response is streamed chunk-by-chunk.

Additional Options

  • :on_chunk - (chunk -> :ok) callback for real-time content/thinking delivery

  • :on_phase - (:thinking | :answering | :done -> :ok) phase transition callback

  • :on_tool_progress - (map() -> :ok) callback when tools are being called

Returns

Same as chat/3.

stream_generate_report(path, issues, opts \\ [])

@spec stream_generate_report(String.t(), map(), keyword()) ::
  {:ok, String.t(), map()} | {:error, term()}

Generate an AI audit report with streaming support.

Requires the knowledge graph and embeddings to be populated first (call analyze_project/2 with skip_report: true).

The :on_chunk callback receives streaming chunks as they arrive.

Options

  • :on_chunk - (chunk -> :ok) callback for real-time content delivery
  • :provider - AI provider override
  • :model - Model override