core.ai package

Subpackages

• core.ai.providers package
  • Submodules
  • core.ai.providers.base module
    • AIProvider
      • AIProvider.chat()
      • AIProvider.chat_stream()
      • AIProvider.is_available()
      • AIProvider.model_name()
  • core.ai.providers.deepseek_provider module
    • DeepSeekProvider
      • DeepSeekProvider.DEFAULT_BASE_URL
      • DeepSeekProvider.MAX_RETRIES
      • DeepSeekProvider.RETRY_BASE_DELAY
      • DeepSeekProvider.chat()
      • DeepSeekProvider.chat_stream()
      • DeepSeekProvider.is_available()
      • DeepSeekProvider.model_name()
  • core.ai.providers.local_provider module
    • LocalLLMProvider
      • LocalLLMProvider.chat()
      • LocalLLMProvider.chat_stream()
      • LocalLLMProvider.is_available()
      • LocalLLMProvider.model_name()
  • core.ai.providers.openai_provider module
    • OpenAIProvider
      • OpenAIProvider.MAX_RETRIES
      • OpenAIProvider.RETRY_BASE_DELAY
      • OpenAIProvider.chat()
      • OpenAIProvider.chat_stream()
      • OpenAIProvider.is_available()
      • OpenAIProvider.model_name()
  • core.ai.providers.openrouter_provider module
    • OpenRouterProvider
      • OpenRouterProvider.DEFAULT_BASE_URL
      • OpenRouterProvider.MAX_RETRIES
      • OpenRouterProvider.RETRY_BASE_DELAY
      • OpenRouterProvider.chat()
      • OpenRouterProvider.chat_stream()
      • OpenRouterProvider.chat_with_tools()
      • OpenRouterProvider.fetch_free_models()
      • OpenRouterProvider.fetch_models()
      • OpenRouterProvider.is_available()
      • OpenRouterProvider.model_name()
  • Module contents

Submodules

core.ai.action_tracker module

Tracks AI assistant file actions for revert support.

class core.ai.action_tracker.AIActionTracker

Bases: object

Records file snapshots before AI tool executions for revert support.

Usage:

tracker.begin_prompt(index) # Before tool loop starts tracker.snapshot_file(path) # Before each file write tracker.end_prompt() # After tool loop completes tracker.revert(index) # Restore files from prompt snapshot

begin_prompt(prompt_index: int)

Start tracking actions for a new prompt.

clear()

Clear all tracked actions.

end_prompt()

Finish tracking. Store the group only if it has actions.

get_modified_files(prompt_index: int) → List[str]

Get list of files modified by a prompt.

has_actions(prompt_index: int) → bool

Check if a prompt had any file-modifying actions.

is_reverted(prompt_index: int) → bool

Check if a prompt’s actions have been reverted.

revert(prompt_index: int) → Dict[str, str]

Revert all file changes from a prompt. Returns dict of path -> status.

snapshot_file(abs_path: str)

Capture file content before modification. Only snapshots once per file per prompt.

class core.ai.action_tracker.FileSnapshot(path: str, content: str | None, existed: bool)

Bases: object

Snapshot of a file before AI modification.

content: str | None

existed: bool

path: str

class core.ai.action_tracker.PromptActionGroup(prompt_index: int, snapshots: Dict[str, ~core.ai.action_tracker.FileSnapshot]=<factory>, reverted: bool = False)

Bases: object

All file actions from a single AI prompt.

property has_actions: bool

prompt_index: int

reverted: bool = False

snapshots: Dict[str, FileSnapshot]

core.ai.api_index module

Complete API reference for the AxisPy Engine, used as context for AI chat.

core.ai.api_index.get_engine_api_reference() → str

Return a comprehensive API reference string for the engine.

core.ai.chat_manager module

Chat manager that orchestrates AI conversations with engine context.

class core.ai.chat_manager.ChatManager

Bases: object

Manages AI chat conversations with engine and project context.

Supports an agentic tool-calling loop: when the AI returns tool calls, the manager executes them and feeds results back, up to max_steps.

MAX_TOOL_STEPS = 5

clear_history()

Clear history and active session messages.

create_new_session(name: str = '') → str

Create a new session and switch to it.

property current_prompt_index: int

The prompt index of the most recent (or in-progress) prompt.

delete_session(session_id: str) → bool

Delete a session.

rename_session(session_id: str, name: str) → bool

Rename a session.

revert_prompt(prompt_index: int) → Dict[str, str]

Revert all file changes from a specific prompt.

send_message(user_message: str) → str

Send a message and get a complete response (blocking).

send_message_stream(user_message: str)

Send a message and stream the response via callbacks. Returns the full response when complete.

set_callbacks(on_chunk: Callable[[str], None] = None, on_complete: Callable[[str], None] = None, on_error: Callable[[str], None] = None, on_tool_call: Callable[[str, dict], None] = None, on_tool_result: Callable[[str, str], None] = None, on_session_changed: Callable[[], None] = None)

Set streaming callbacks.

set_project_path(path: str)

Set project path for session persistence and context.

set_provider(provider: AIProvider)

switch_session(session_id: str) → bool

Switch to a different session.

class core.ai.chat_manager.ChatMessage(role: str, content: str, tool_call_id: str = '', name: str = '')

Bases: object

A single message in the conversation.

content

name

role

timestamp

tool_call_id

core.ai.context_builder module

Builds context about the user’s project and current editor state for AI chat.

class core.ai.context_builder.ContextBuilder

Bases: object

Collects project structure, scene info, and user scripts to provide rich context to the AI assistant.

build_context() → str

Build a context string describing the user’s project and current state.

get_user_script_content(script_path: str) → str

Read the content of a user script file.

set_project_path(path: str)

set_scene_getter(getter)

Set a callable that returns the current Scene object.

set_selected_entities_getter(getter)

Set a callable that returns the list of selected entities.

core.ai.session_manager module

Session manager for AI chat conversations — save/load to .axispy/project.ai

class core.ai.session_manager.ChatSession(id: str, name: str, created_at: float, updated_at: float, messages: Dict[str, ~typing.Any]]=<factory>)

Bases: object

A single conversation session.

add_message(role: str, content: str, **kwargs)

Add a message to the session.

classmethod create(name: str = 'New Session') → ChatSession

created_at: float

classmethod from_dict(data: dict) → ChatSession

id: str

messages: List[Dict[str, Any]]

name: str

to_dict() → dict

updated_at: float

class core.ai.session_manager.SessionManager(project_path: str = '')

Bases: object

Manages chat sessions persistence to .axispy/project.ai

active_session_id: str | None

add_message_to_active(role: str, content: str, **kwargs)

Add a message to the active session.

clear_active_session()

Clear all messages from the active session.

create_session(name: str = '') → ChatSession

Create a new session and make it active.

delete_session(session_id: str) → bool

Delete a session. Returns True if deleted.

get_active_messages() → List[Dict[str, Any]]

Get messages from the active session.

get_active_session() → ChatSession | None

Get the currently active session.

get_session_list() → List[ChatSession]

Get all sessions sorted by updated_at (newest first).

load() → bool

Load sessions from disk. Returns True if loaded successfully.

rename_session(session_id: str, new_name: str) → bool

Rename a session.

save() → bool

Save sessions to disk. Returns True if saved successfully.

sessions: Dict[str, ChatSession]

set_project_path(path: str)

Set the project path and compute the sessions file path.

switch_session(session_id: str) → bool

Switch to a different session.

core.ai.tools module

Engine-specific tools that the AI agent can call to inspect the project.

class core.ai.tools.ToolExecutor

Bases: object

Executes engine tools using callbacks wired to the editor state.

execute(tool_name: str, arguments: Dict[str, Any]) → str

Execute a tool by name and return the result as a string.

set_project_path(path: str)

set_scene_getter(getter: Callable)

set_scene_reload_callback(callback: Callable)

Set callback to trigger scene reload after file edits.

set_selected_entities_getter(getter: Callable)

Module contents