Recursive AI

Parse contacts with rules only in C#

OneContact is a free, open-source contact data library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies, no network access.

Temporarily parse names and addresses using rules, then restore the models that were in use before the scope.

Terminal
dotnet add package RecursiveAI.OneContact

Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.

C#
using RecursiveAI.OneContact;
using RecursiveAI.OneContact.Models;
 
using (ContactModels.Use(null, null, null))
    Console.WriteLine(PersonName.Parse(
        "Ada Example", Region.US));

Unzip the example, then dotnet run.

Prints:

Text
Ada Example

The full program

The full program creates an outer scope with a small address-model stub that returns no labels. It does not load a learned model. Inside it, an explicit all-null scope parses a controlled address and name, refuses an incomplete address and then restores the exact prior model object.

C#
using RecursiveAI.OneContact;
using RecursiveAI.OneContact.Models;
 
// An outer scope makes restoration visible without a model package.
using (ContactModels.Use(new EmptyAddressModel(), null))
{
    var prior = ContactModels.Address;
    using (ContactModels.Use(null, null, null))
    {
        Console.WriteLine($"Rule-only: {ContactModels.Address is null && ContactModels.Name is null && ContactModels.Spans is null}");
        Console.WriteLine(PostalAddress.Parse(
            "123 Main St, Springfield, IL 62704", Region.US));
        Console.WriteLine(PersonName.Parse("Ada Example", Region.US));
        try { Console.WriteLine(PostalAddress.Parse("Main Street")); }
        catch (ContactParseException error)
        { Console.WriteLine($"Refused: {error.Message}"); }
    }
    Console.WriteLine($"Restored: {ReferenceEquals(prior, ContactModels.Address)}");
}
 
sealed class EmptyAddressModel : IAddressFieldModel
{
    public IReadOnlyList<ModelSpan> Tag(string text) => [];
}

dotnet run prints:

Text
Rule-only: True
123 MAIN ST, SPRINGFIELD IL 62704
Ada Example
Refused: The text is not a valid Address value: no city, state or postal code was found (address.no-last-line).
Restored: True

A refused Parse throws ContactParseException; leaving the using scope still restores the prior models.

Variations

Handle refused user input without an exception

Use the high-level TryParse when an incomplete address is an expected input. Run this separately:

C#
using RecursiveAI.OneContact;
using RecursiveAI.OneContact.Models;
 
using (ContactModels.Use(null, null, null))
{
    bool usable = PostalAddress.TryParse(
        "Main Street", out var address);
    Console.WriteLine($"Usable: {usable}");
}
Text
Usable: False

The short answer

Wrap the calls in using (ContactModels.Use(null, null, null)). The three null arguments explicitly disable the address, name and contact-span model roles for that scope. Disposing the scope restores the prior scoped registration. This is a scoped choice, not a process-wide removal of registered models.

At the pinned OneContact 1.0.0 release, the published library runs on rules; trained model packages are described for 1.1. The scope is still useful for making your intent explicit and for applications with caller-supplied model implementations. The example uses a harmless stub only to make restoration observable.

How do I disable contact parsing models in C#?

Use ContactModels.Use around the smallest set of parsing calls that should be rule-only. A using block disposes even if parsing throws, so the outer context is restored on both normal and exceptional exits. Keep the scope alive until all of the work that needs it is complete.

The address and name examples are literal inputs, not reads from another source. The complete address supplies a street, city, state and postal code, plus a US hint. The name supplies a country hint as well. Passing country context does not enable a model; it gives the rules information they can use.

The API documentation says: “A null model means no model, not the registered one.” This also applies to documented parser overloads that accept an explicit model argument. A call that omits a model argument can consult the registry; explicitly passing null is a different instruction.

Does a rule-only scope restore the previous model?

Yes. The pinned implementation saves the prior scoped registration and restores it on disposal. Its scoped storage is AsyncLocal, leaving the process-wide registration untouched.

The full program creates an outer scope with a non-null address-model stub, then enters an all-null inner scope. Rule-only: True checks all three roles inside it. Restored: True checks object identity afterward, not just whether some model happens to exist. The stub returns no labels and makes no claim to learned-model accuracy.

Do not use Register to temporarily disable models. Registration is the package-level mechanism; packages compete by rank, and referencing a model package can arrange its registration through a compiled source file. A scope is the mechanism for a temporary override in the current asynchronous flow.

What happens when rules cannot parse an address?

A rule-only scope does not make an unsupported input usable. The incomplete Main Street input in the example is refused with address.no-last-line. Use TryParse when this is an expected user-input outcome, as the variation shows, or catch ContactParseException at the application boundary.

Country ambiguity has its own behavior. The high-level Parse and TryParse methods refuse an address when its country cannot be determined. The low-level status-returning span overload can retain the partial reading, including AddressFacts.CountryUndetermined, with an unknown country. That is a partial interpretation, not a fully usable normalized address.

Rule-only parsing and model-assisted parsing are not promised to produce equivalent readings. Context, supported address rules and the actual input all matter. Keep reasons with refused inputs, and route unresolved entries to review rather than replacing them with guessed fields. The address documentation distinguishes missing country evidence from a successful parse with an explicit hint.

All onecontact recipes