features.md

PyFlowintel Features

Summary of functionality in PyFlowintel v0.1 (Alpha).

Table of Contents

• Client Initialization
• API Endpoints
  • Case Operations
  • Task Operations
  • Template Operations
  • Admin Operations
  • Importer Operations
• Core Features
  • Error Handling
  • Configuration
  • Logging

Client Initialization

PyFlowintel supports three initialization methods:

From YAML configuration (recommended):

frompyflowintelimportPyFlowinteltry:
client=PyFlowintel.from_config() # Uses config.yaml in project rootexceptPyflowintelConfigurationErrorase:
# Handle error in Flowintel settings (e.g., missing api key)
...
try:
client=PyFlowintel.from_config("my_settings.yaml") # Custom fileexceptPyflowintelConfigurationErrorase:
# Handle error in Flowintel settings
...

From explicit arguments:

client=PyFlowintel.from_args(
base_url="http://localhost:7006/api",
api_key="your-api-key"
)

As context manager (auto-cleanup):

try:
client=PyFlowintel.from_config()
exceptPyflowintelConfigurationErrorase:
logger.error("Failed to initialize PyFlowintel client: %s", e)
returnwithclient:
cases=client.cases.list_all()

API Endpoints

Case Operations

Access via client.cases:

Method	Description
create(title, **kwargs)	Create a new case
list_all()	List all cases
search_by_title(search_query)	Search cases by title substring
search_by_id(case_id)	Get case details
update(case_id, case_payload)	Update an existing case
delete(case_id)	Delete a case
complete(case_id)	Mark case as completed
create_template_from_case(case_id, template_name)	Create template from existing case
add_task(case_id, task_title, **kwargs)	Add task to a case
append_note(case_id, note)	Append note to a case

Task Operations

Access via client.tasks:

Method	Description
list_of_case(case_id)	List all tasks in a case
search_by_id(task_id)	Get task details
search_by_title(search_string)	Search tasks by title substring
edit(task_id, **kwargs)	Update task properties
delete(task_id)	Delete a task
complete(task_id)	Mark task as complete

Template Operations

Access via client.templates:

Creation:

• create_case_template(template_data) - Create case template from dict
• create_task_template(template_data) - Create task template from dict
• create_case_from_template(template_id, case_title) - Instantiate case from template

Retrieval:

• find_case_temp_by_id(tid) - Get case template by ID
• find_task_temp_by_id(tid) - Get task template by ID
• find_case_temp_by_title(title) - Search case templates by exact title match
• get_case_template_title(tid) - Get case template title

Modification:

• add_task_templates_to_case_template(case_template_id, task_template_ids) - Add existing task templates
• add_tasks_to_case_template(case_template_id, tasks) - Create and add new task templates

Deletion:

• delete_case(case_template_id, delete_tasks=False) - Delete case template (optionally with tasks)
• delete_task(task_template_id) - Delete task template
• delete_tasks(task_template_ids) - Delete multiple task templates

Admin Operations

Access via client.admin:

User Management:

• add_user(first_name, last_name, email, password, role, org=None)
• list_users()
• get_user_by_id(user_id)
• get_user_by_lastname(lastname)
• edit_user(user_id, **kwargs)
• delete_user(user_id)

Organization Management:

• add_org(name, desc=None, uuid=None)
• get_org(oid)

Role Management:

• list_roles()

Importer Operations

Access via client.importers:

• import_case(file) - Import case from JSON file
• import_template(file) - Import template from JSON file

Note: Template import has limited native support in Flowintel. Use client.templates.create_case_template() for better reliability.

Core Features

Error Handling

PyFlowintel provides custom exceptions for different error scenarios:

Exception	When Raised
PyflowintelException	Base class for all PyFlowintel errors
PyflowintelValidationError	Invalid parameters (e.g., negative IDs, wrong types)
FlowintelAPIError	Generic API error response
FlowintelAuthenticationError	Invalid/missing API key (401)
FlowintelUnauthorizedError	Insufficient permissions (403) - stub only in v0.1
FlowintelBadRequestError	Malformed request (400) - stub only in v0.1
FlowintelNotFoundError	Resource not found (404) - stub only in v0.1
FlowintelServerError	Server error (5xx) - stub only in v0.1
FlowintelConnectionError	Connection failure
FlowintelTimeoutError	Request timeout

Configuration

Configuration Options:

Parameter	Type	Required	Default	Description
base_url	string	Yes	-	Flowintel API base URL
api_key	string	Yes	-	API authentication key
verify_ssl	bool	No	True	Verify SSL certificates
timeout	int	No	30	Request timeout (seconds)

YAML Format (config.yaml):

flowintel:
base_url: http://localhost:7006/apiapi_key: your-api-key-hereverify_ssl: truetimeout: 30testing:
base_url: your-testing-instance-urlapi_key: your-test-api-key-here

Logging

PyFlowintel includes package-wide logging:

• Default level:INFO (configurable in pyflowintel/commons/logging_config.py)
• Format:[LEVEL] timestamp - logger_name: message
• Logs: API requests/responses, errors, resource operations, validation issues

Logging functions:

• setup_logging(level, format_string) - Configure package logging
• get_logger(name) - Get module-specific logger
• set_log_level(level) - Change log level dynamically

Input Validation

Automatic validation for:

• IDs must be positive integers (cases, tasks, templates, users)
• Lists must contain expected types
• Files must have correct extensions (.json, .yaml, .yml)

Validation utilities:

• validate_nat_num(id) - Validate positive integer
• validate_list_of(parameter, item_type) - Validate list type
• validate_file_ext(file, exts) - Validate file extension

HTTP Client

The underlying HTTPClient provides:

• Methods: GET, POST, DELETE
• Features: Persistent sessions, automatic authentication, timeout management, SSL verification
• Response handling: Automatic JSON parsing, HTTP error conversion to exceptions

Utility Functions

Function	Description
read_yaml(path)	Parse YAML configuration files
read_json(file)	Parse JSON files
extract_values_from_dicts(dict_list, key)	Extract specific values from list of dicts
pretty_json(obj)	Print formatted JSON

---

Examples: See examples/ folder for working code samples:

• cases_sample.py - Case operations
• templates_sample.py - Template creation and instantiation

Tests: Run ./scripts/run_tests.sh for unit and integration tests.

For installation and setup, see the main README.