PyO3 And WASM Function Reference

5. PyO3 (Python) Binding Functions

Header Validation

• validate_headers(headers: dict) -> Optional[str]
• validate_headers_with_config(headers: dict, required_headers: Optional[list[str]], min_score: Optional[int]) -> Optional[str]

Matchers and record conversion

• KeywordMatcher(keywords).first_match(path) returns the first matching keyword or None.
• RouteMatcher(prefixes).match_index(path) returns the matching prefix index or None.
• Record helpers include build_records, extract_raw_features, and extract_training_features.

Feature Extraction

• extract_features(records: list[dict], static_keywords: list[str]) -> list[dict]
• extract_features_batch_with_state(records: list[dict], static_keywords: list[str], state: Optional[dict]) -> dict
• finalize_feature_state(static_keywords: list[str], state: Optional[dict]) -> dict

Recent Behavior Analysis

• analyze_recent_behavior(entries: list[dict], static_keywords: list[str]) -> Optional[dict]

IsolationForest (PyO3)

• Constructor supports n_estimators, max_samples, contamination, max_features, bootstrap, n_jobs (ignored), random_state, verbose, warm_start.
• Methods: fit, retrain, anomaly_score, is_anomaly, score_samples, decision_function, predict, to_json, from_json.

6. Isolation Forest Internals And Semantics

• Core implementation in rust/crates/aiwaf_core/src/lib.rs.
• fit resets trees unless warm-start append is enabled.
• retrain temporarily forces warm-start append behavior.
• anomaly_score: higher means more anomalous.
• score_samples: higher means more normal (sklearn-aligned direction).
• decision_function = score_samples - offset_.
• predict returns 1 (inlier) and -1 (outlier).
• Contamination "auto" keeps offset_ = -0.5; fixed contamination computes percentile-based offset.

7. WASM Binding Functions

• validate_headers, validate_headers_with_config
• extract_features, extract_features_batch_with_state, finalize_feature_state
• analyze_recent_behavior

WASM also exports KeywordMatcher, RouteMatcher, validate_url, validate_content, and record-conversion helpers.

WASM IsolationForest class

• new(config?), fit, retrain, anomaly_score, is_anomaly, score_samples, decision_function, predict, to_json, from_json

Header Handling Notes

• WASM accepts JS object or Headers.
• Auto-fills user-agent from navigator.userAgent when absent.
• Core still expects normalized HTTP_* style names internally.

8. Integration Patterns

Python service pattern

1. Build normalized request dict.
2. Run header validation early; block on non-None reason.
3. Build feature records and update state incrementally.
4. Score with IsolationForest and combine with rule outcomes.

JS/browser WASM pattern

1. await init() at startup.
2. Use wasm exports in request/event pipeline.
3. Persist forest/state with to_json() as needed.

Python ↔ WASM portability

Both bindings expose JSON state from the shared Rust core. Validate the serialized feature schema and forest version before exchanging artifacts. Java supports Python Rust-model JSON state; JavaScript-native and legacy artifacts are not generally interchangeable.

PyO3 CSV and retained training capabilities

The 0.2.2 Python extension additionally exposes CSV snapshot reads/indexed lookups, locked mutations, synchronous append/close operations, shared request policies, route-plan selection, and exemption matching. These are Python binding capabilities; the current WASM API does not expose filesystem CSV transactions or the retained training classes.

• TrainingCSVReader reads plain/gzip CSV in bounded batches via next_batch(size), preserving quoted newlines and timing units.
• NativeTrainingBatch retains features; feature_columns() supplies the six-column order, fit_predict(model) builds/fits/scores in Rust and returns per-IP anomaly statistics, and to_dicts() supports compatibility inspection.
• NativeTrainingBuilder.add_batch(...) retains incremental feature state; finish() returns a native batch.
• extract_native_training_features prepares a native feature batch from normalized records and route eligibility.
• training_date_parts parses supported Apache/ISO parts; Python preserves datetime/epoch semantics and unsupported forms. Native ISO use is opt-in.
• csv_log_append locks/flushes a row; csv_log_close(path=None) releases cached handles. Policy mutations remain separate transactions.

Use the framework adapters and core/training_pipeline.py for normal application integration. Low-level bindings expect the established schemas, units, and argument order; check capabilities before using them with older extensions.

Native pipeline API

Release candidate: this page documents Python 1.1.8 and Rust/Python 0.2.7 in the current source checkout. Source versions do not establish registry availability. Python 1.1.8 requires aiwaf-rust>=0.2.7; framework dependencies remain extras.

NativeCSVPipeline(profile_json) validates configuration and CSV schemas at construction. begin(...) accepts normalized request facts and returns an engine-owned NativePipelineRequest. finish(context, status, now, content_length, monotonic) finalizes response observations and logging once. Use the framework adapters to construct transport facts and enable monotonic timing.

set_model(model) snapshots a trained six-feature Rust IsolationForest; set_model(None) disables inference. seed_history(...) supplies warm history and route-eligibility facts; diagnostics() exposes activation/state counters. The Python binding is separate from WASM exports.

Continue with the request lifecycle, the native profile, migration, and performance and deployment.

Node/WASM native API

Native mode: Node source candidate aiwaf 1.1.4 declares aiwaf-wasm ^0.2.4. Explicit native registration validates NativeRequestPipeline at startup; missing or incompatible support is an error. There is no JavaScript policy fallback for this engine. Installing the dependency does not switch an existing legacy middleware chain.

NativeRequestPipeline(profile_json) validates configuration once. begin(request_json) returns an engine-owned token/decision; finish(context,status,elapsed_ms,now) emits log/policy CSV rows and updates response state once. Hapi uses inspect_body for its deferred parsed-body phase. The engine snapshots a fitted forest with set_model, supports clear_model, and exposes activation/inference/state counters through diagnostics. Node owns filesystem access; the Python NativeCSVPipeline filesystem API is separate.

Read the native lifecycle, configuration, deployment and measurements, and migration.