Cyc Core API Specification 1.1.1

@nwinant nwinant released this Jan 17, 2018 · 1 commit to master since this release

Version number incremented to reflect core client implementation update.

Cyc Core API Specification 1.1.0

@nwinant nwinant released this Jan 17, 2018 · 2 commits to master since this release

Javadoc corrections. References to cyc-core-client-impl updated to 1.1.0.

Cyc Core API Specification 1.0.0

@nwinant nwinant released this Jan 17, 2018 · 3 commits to master since this release

1.0.0 release. Future 1.x releases will be backwards-compatible, per the
Semantic Versioning 2.0.0 specification.

Cyc Core API Specification 1.0.0-rc9.0

@nwinant nwinant released this Jan 17, 2018 · 4 commits to master since this release

Consolidates and streamlines factory methods, in addition to other assorted improvements. It is
not backwards-compatible with earlier API releases.

This release contains numerous minor improvements and cleanup in preparation for 1.0.0.

Cyc Core API Specification 1.0.0-rc8.0

@nwinant nwinant released this Jan 17, 2018 · 5 commits to master since this release

Consolidates and streamlines factory methods, in addition to other assorted improvements. It is
not backwards-compatible with earlier API releases.

Java 1.8

Now requires Java 8 or greater to run, and JDK 1.8 or greater to build.

Core API Factories

This release primarily simplifies all of the many factories. Previously, we had a separate factory
for each object (Assertion -> AssertionFactory, KbTerm -> KbTermFactory, Query -> QueryFactory,
etc.) which was a constant headache. Now, each API has a single entry point via a service-provider
interface (marked by com.cyc.CycApiEntryPoint) for which implementations are loaded at runtime;
e.g., KbApiService, QueryApiService, SessionApiService. For convenience, we then provide
static methods which trampoline to these factories.

There are now two recommended ways to create or retrieve an object: either call static methods on
com.cyc.Cyc, or on the relevant interface itself. E.g.:

  • Cyc.getKbTermService().findOrCreate("SomeTerm")
  • Cyc.getQueryService().getQuery("SomeQueryId")
  • KbTerm.findOrCreate("SomeTerm)
  • Query.get("SomeQueryId")

Additionally, commonly-used constants can now be found on com.cyc.Cyc.Constants. E.g.:

  • Cyc.Constants.INFERENCE_PSC
  • Cyc.Constants.UV_MT
  • Cyc.Constants.ISA
  • Cyc.Constants.GENLS
  • Cyc.Constants.TRUE_CYCL
  • Cyc.Constants.FALSE_CYCL

Improvements have also been added to facilitate more fluent API calls via method chaining,
particularly for queries. Instance methods have been added, where appropriate, which trampoline to
factories. Query answers are returned in a QueryAnswers instance, which contains a number of
convenience methods. A number of typical CycL variables (ARG, ARG0, ARG1, ARG2, VAR,
VAR0, VAR1, VAR2, etc.) have been added to com.cyc.Cyc.Constants for static import.

For example, here are two different ways to run a query which finds and prints all instances of the
Collection #$Dog:

import com.cyc.kb.KbCollection;
import com.cyc.kb.Sentence;
import com.cyc.query.Query;
import static com.cyc.Cyc.Constants.ARG1;
import static com.cyc.Cyc.Constants.INFERENCE_PSC;
import static com.cyc.Cyc.Constants.ISA;
...

Query.get("(isa ?VAR Dog)", "InferencePSC")
        .getAnswers()
        .getBindingsForOnlyVariable()
        .forEach(System.out::println);

...

Sentence.get(ISA, ARG1, KbCollection.get("Dog"))
        .toQuery(INFERENCE_PSC)
        .getAnswers()
        .getBindingsForVariable(ARG1)
        .forEach(System.out::println);

KB API

  • Adds static factory methods to KbObject interfaces. E.g., KbTerm#findOrCreate(String),
    KbTerm#get(String), etc.
  • Adds abstract base classes for implementing KbObjects per decorator pattern: com.cyc.kb.wrapper.
    There is only partial coverage for the KbObject hierarchy at the moment, but this will be fleshed
    out soon.

Query API

  • Adds static factory methods to Query API interfaces. E.g., Query#getQuery(String),
    ProofViewSpecification#get(), ProofView#getProofView(QueryAnswer, ProofViewSpecification).

Session API

  • Adds static factory method to CycSession interface: CycSession#getCurrentSession().
  • CycAddress interface replaces CycServerAddress and CycServer, for which the nomenclature was
    too ambiguous.
  • Add CycAddress#getConcurrencyLevel(), which represents the maximum # of simultaneous jobs that
    can be delegated to a particular server.

Cyc Core API Specification 1.0.0-rc7.0

@nwinant nwinant released this Sep 1, 2017 · 6 commits to master since this release

Refactors a number of interfaces to improve clarity, particularly in the KB API. It is
not backwards-compatible with earlier API releases.

Java 1.7

Now requires Java 7 or greater to run, and JDK 1.7 or greater to build.

KB API

A number of methods on com.cyc.kb.KbObject have been moved to subtypes to better reflect their
relevance within the type hierarchy, and some have been renamed for clarity or consistency. For
example:

KbObject#addFact      -> KbPredicate#addFact

KbObject#getValues    -> KbPredicate#getValuesForArgPosition
                      -> KbPredicate#getValuesForArgPositionWithMatchArg
					  
KbObject#formulaArity -> Assertion#getArity
                      -> KbTerm#getArity
                      -> Sentence#getArity

A few methods have also had their arg signatures modified to reflect these changes. In particular,
methods which had required a predicate for their first arg were moved to KbPredicate and their
arg signatures were updated accordingly. For example:

   KbObject    #addFact(Context ctx, KbPredicate pred, int thisArgPos, Object... otherArgs)
-> KbPredicate #addFact(Context ctx, Object... args)

   KbObject    #getFact(Context ctx, KbPredicate pred, int thisArgPos, Object... otherArgs)
-> KbPredicate #getFact(Context ctx, Object... args)

   KbObject    #getFacts(KbPredicate pred, int thisArgPos, Context ctx)	 
-> KbPredicate #getFacts(Object arg, int argPosition, Context ctx)

   KbObject    #getSentence(KbPredicate pred, int thisArgPos, Object... otherArgs)	 
-> KbPredicate #getSentence(Object... args)

   KbObject    #getValues(KbPredicate pred, int thisArgPos, int valuePosition, Context ctx)
-> KbPredicate #getValuesForArgPosition(Object arg, int argPosition, int valuePosition, Context ctx)

This update also includes assorted refactorings which shouldn't impact existing application code: a
few service provider interfaces have been renamed, some unnecessary generics have been removed from
some SPIs, com.cyc.query.graphs is now com.cyc.query.graph, etc.

Query API

com.cyc.query.QuerySpecification no longer has any mutating methods on it; those are on the new
com.cyc.query.QuerySpecification.MutableQuerySpecification, which is extended by
com.cyc.query.Query. QuerySpecification is useful for cases where something wants to make the
details of a Query available to external processes (for reporting, etc.) in a read-only fashion,
whereas MutableQuerySpecification can be used to create or modify queries & KBQs, and generally has
a pretty bean-like interface.

The map-like methods on com.cyc.query.parameters.InferenceParameters (#keySet, #get,
#putAll, etc.) have been moved to InferenceParameterGetter and InferenceParameterSetter, as
appropriate. QuerySpecification#getInferenceParameters() returns an InferenceParameterGetter,
whereas MutableQuerySpecification & Query return a full, mutable, InferenceParameters instance.

Cyc Core API Specification 1.0.0-rc6

@nwinant nwinant released this Aug 31, 2017 · 8 commits to master since this release

Adds assorted new functionality. 1.0.0-rc6 is not backwards-compatible with earlier API releases.

Query API

Adds support for ProofViews. To generate a ProofView:

  1. Call QueryFactory#getProofViewSpecification() to retrieve a ProofViewSpecification.
  2. Configure the ProofViewSpecification via its setters.
  3. Then, call QueryFactory#getProofView(QueryAnswer, ProofViewSpecification).

Also:

  • Query now extends QuerySpecification, which solely represents the query itself; processing
    information is still represented by Query.
  • Query#getAnswers() now returns QueryAnswers instead of a raw List<QueryAnswer>. QueryAnswers
    extends List, but adds several convenience methods to retrieve all bindings for a
    particular variable, get all bindings as a list for single-variable queries, get a single binding
    from queries which should return exactly one binding, and to print answers in a formatted table.
  • Query rules can be retrieved via QuerySpecification#getRules().
  • Query indexicals cans be retrieved via QuerySpecification#getUnresolvedIndexicals().

KB API

Improves support for working with quoted terms:

  • KbObject#isQuoted()
  • KbObject#quote()
  • KbObject#unquote()
  • KbObject#toQuoted()
  • KbObject#toUnquoted()

Improves support for working with indexicals and variables:

  • KbObject#isIndexical()
  • KbObject#possiblyResolveIndexical(Map)
  • KbObject#resolveIndexical()
  • Sentence#getIndexicals(boolean)
  • Sentence#getVariables(boolean)

Improves support for performing substitutions:

  • KbTerm#replaceTerms(Map)
  • Sentence#replaceTerms(Map)

Other changes

  • Assorted minor changes to API methods.

Cyc Core Client Implementation 1.0.0-rc5.2

@nwinant nwinant released this Jan 27, 2016 · 9 commits to master since this release

1.0.0-rc5.2 - 2016-01-26

  • Fixes a ParaphraserFactory-related StackOverflowError in the Base Client
    (CycClient#commonInitialization()) which occurred when NL API was on the classpath.
  • The warning message which is logged when the NL API is missing from the classpath has been toned
    down & clarified a bit, and is only logged when the user actually attempts to do something
    NL-related (i.e., when the ParaphraserFactory first attempts to load a Paraphraser).

Cyc Core Client Implementation 1.0.0-rc5.1

@nwinant nwinant released this Jan 19, 2016 · 10 commits to master since this release

1.0.0-rc5.1 - 2016-01-18

Fixes several bugs in the Core Client implementation:

  • QueryImpl#getAnswerSentence() not substituting bindings.
  • CycListParser mangling very big integers.
  • LegacyCycClientManager#setCurrentSession(CycServerAddress) being ignored.
  • UnmodifiableCycList modified by java.util.Collections#sort() under Java 8.

Additionally, in keeping with Google Java Style, references to "ELMt" have been changed to "ElMt".

Cyc Core Client Implementation 1.0.0-rc5

@nwinant nwinant released this Dec 24, 2015 · 11 commits to master since this release

The fifth release candidate of Cycorp's Java API suite, and the first in which the Core API
specification and the Core Client implementation are packaged as wholly separate artifacts.

1.0.0-rc5 is not backwards-compatible with earlier API releases. Note that ResearchCyc 4.0q and
EnterpriseCyc 1.7-preview require server code patching for compatibility
with the 1.0.0-rc5 release.

API & implementation division

There is now a clean division between the Core APIs and their reference implementation; they have
been split into two artifacts:

  • The implementation-independent Core API specification: core-api-spec
  • The Core Client reference implementation: cyc-core-client-impl

See the CHANGELOG in the Cyc Core API (v1.0.0-rc5) for additional details.

Other changes

  • The Cyc Core API GitHub repository has been renamed and expanded into the
    Cyc Java API Suite repository, of which core-api-spec and
    core-client are sub-projects.
  • Reorganization of classes (especially exceptions) within the com.cyc.* package space.
  • Implementation projects built on the Base Client have had their artifactIds renamed to incorporate
    the word "client". E.g., cyc-core-suite is now cyc-core-client-impl, cyc-session is now
    cyc-session-client, etc.
  • Project/module directories have been renamed to mirror their artifactIds, dropping the "cyc-"
    prefix. E.g., the cyc-session-client project lives in the session-client directory.
  • The cyc-core-api-parent and cyc-core-client-parent POMs now inherit from cyc-api-parent,
    which inherits from cyc-default-config-parent.
  • Assorted bug fixes.